@cyphra/runtime 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +131 -4
- package/dist/index.js +257 -1
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/dist/index.d.ts
CHANGED
|
@@ -203,6 +203,12 @@ type ModelTypeDef = {
|
|
|
203
203
|
/** `@id` / `@unique` keys usable in `findUnique`, `connect`, … */
|
|
204
204
|
readonly unique: string;
|
|
205
205
|
readonly relations: Record<string, RelationTypeDef>;
|
|
206
|
+
/** `Vector(N)` scalar keys (absent when the model has none). */
|
|
207
|
+
readonly vectors?: string;
|
|
208
|
+
/** `Vector(N)` keys with a `@vectorIndex`: the fields `findSimilar` can search. */
|
|
209
|
+
readonly vectorIndexes?: string;
|
|
210
|
+
/** Names of the model's `@@fulltext` indexes: what `search` can query (absent when none). */
|
|
211
|
+
readonly fulltextIndexes?: string;
|
|
206
212
|
};
|
|
207
213
|
type TypeMap = Record<string, ModelTypeDef>;
|
|
208
214
|
type Scalars<TM extends TypeMap, M extends keyof TM> = TM[M]["scalars"];
|
|
@@ -212,6 +218,18 @@ type Target<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM
|
|
|
212
218
|
type Simplify<T> = {
|
|
213
219
|
[K in keyof T]: T[K];
|
|
214
220
|
} & {};
|
|
221
|
+
/** `Vector(N)` scalar keys of model `M`. */
|
|
222
|
+
type VectorKeys<TM extends TypeMap, M extends keyof TM> = TM[M] extends {
|
|
223
|
+
vectors: infer V extends string;
|
|
224
|
+
} ? V : never;
|
|
225
|
+
/** `Vector(N)` keys of model `M` with a `@vectorIndex` (what `findSimilar` searches). */
|
|
226
|
+
type VectorIndexKeys<TM extends TypeMap, M extends keyof TM> = TM[M] extends {
|
|
227
|
+
vectorIndexes: infer V extends string;
|
|
228
|
+
} ? V : never;
|
|
229
|
+
/** Names of the `@@fulltext` indexes of model `M` (what `search` queries). */
|
|
230
|
+
type FulltextIndexNames<TM extends TypeMap, M extends keyof TM> = TM[M] extends {
|
|
231
|
+
fulltextIndexes: infer V extends string;
|
|
232
|
+
} ? V : never;
|
|
215
233
|
/** Types with `lt` / `lte` / `gt` / `gte` (strings compare lexicographically, by code point). */
|
|
216
234
|
type Comparable = number | string | Date;
|
|
217
235
|
/** Filter on one scalar field. A bare value means `equals`; `null` means "property absent". */
|
|
@@ -260,8 +278,13 @@ type RelationFilter<TM extends TypeMap, D extends RelationTypeDef> = D["many"] e
|
|
|
260
278
|
/** No related node matching this (`null`: a related node exists). */
|
|
261
279
|
isNot?: WhereInput<TM, D["target"] & keyof TM> | null;
|
|
262
280
|
};
|
|
281
|
+
/** Vector fields only filter on presence (search them with `findSimilar`). */
|
|
282
|
+
type VectorFilter = null | {
|
|
283
|
+
equals?: null;
|
|
284
|
+
not?: null;
|
|
285
|
+
};
|
|
263
286
|
type WhereInput<TM extends TypeMap, M extends keyof TM> = {
|
|
264
|
-
[K in keyof Scalars<TM, M>]?: ScalarFilter<Scalars<TM, M>[K]>;
|
|
287
|
+
[K in keyof Scalars<TM, M>]?: K extends VectorKeys<TM, M> ? VectorFilter : ScalarFilter<Scalars<TM, M>[K]>;
|
|
265
288
|
} & {
|
|
266
289
|
[R in keyof Relations<TM, M>]?: RelationFilter<TM, Rel<TM, M, R>>;
|
|
267
290
|
} & {
|
|
@@ -283,7 +306,7 @@ type ToManyRelations<TM extends TypeMap, M extends keyof TM> = {
|
|
|
283
306
|
}[keyof Relations<TM, M> & string];
|
|
284
307
|
/** One `orderBy` entry: scalars, or a to-many relation by its count (`{ posts: { _count: "desc" } }`). */
|
|
285
308
|
type OrderByItem<TM extends TypeMap, M extends keyof TM> = {
|
|
286
|
-
[K in keyof Scalars<TM, M
|
|
309
|
+
[K in Exclude<keyof Scalars<TM, M>, VectorKeys<TM, M>>]?: SortOrder;
|
|
287
310
|
} & {
|
|
288
311
|
[R in ToManyRelations<TM, M>]?: {
|
|
289
312
|
_count?: SortOrder;
|
|
@@ -679,6 +702,82 @@ type ShortestPathArgs<TM extends TypeMap, M extends keyof TM, R extends SelfRela
|
|
|
679
702
|
};
|
|
680
703
|
/** A shortest path: its nodes (honouring `select` / `include`) and its typed edges. */
|
|
681
704
|
type ShortestPathResult<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM, M>, N> = Path<N, PathEdge<EdgeProps<Rel<TM, M, R>>>>;
|
|
705
|
+
type FindSimilarArgs<TM extends TypeMap, M extends keyof TM> = {
|
|
706
|
+
/** The `Vector(N)` field to search; it must have a `@vectorIndex`. */
|
|
707
|
+
field: VectorIndexKeys<TM, M>;
|
|
708
|
+
/** Query embedding. Its length must equal the field's dimensions (checked at runtime). */
|
|
709
|
+
vector: readonly number[];
|
|
710
|
+
/** Number of results (best first). */
|
|
711
|
+
k: number;
|
|
712
|
+
/**
|
|
713
|
+
* Filter on the results. The vector index has no filter argument, so `findSimilar` asks it for
|
|
714
|
+
* `candidates` neighbours, filters them, and widens the search (×4) until `k` rows match or the
|
|
715
|
+
* index is exhausted. Use `exact: true` when the filter is selective.
|
|
716
|
+
*/
|
|
717
|
+
where?: WhereInput<TM, M>;
|
|
718
|
+
/** Drop results scoring below this (scores are in `[0, 1]`, higher is more similar). */
|
|
719
|
+
minScore?: number;
|
|
720
|
+
/**
|
|
721
|
+
* Neighbours asked from the index on the first attempt (at least `k`; default `k`, or
|
|
722
|
+
* `max(10 × k, 100)` with a `where`). More candidates improve the recall of the approximate search.
|
|
723
|
+
*/
|
|
724
|
+
candidates?: number;
|
|
725
|
+
/** Upper bound on the candidates of a filtered search (default: no bound). */
|
|
726
|
+
maxCandidates?: number;
|
|
727
|
+
/**
|
|
728
|
+
* Skip the index: score every node matching `where` with `vector.similarity.*` (exact results,
|
|
729
|
+
* Neo4j 5.18+). Fast when `where` narrows the search to a few thousand nodes.
|
|
730
|
+
*/
|
|
731
|
+
exact?: boolean;
|
|
732
|
+
};
|
|
733
|
+
/** A `findSimilar` result: the node (honouring `select` / `include`) and its similarity score. */
|
|
734
|
+
type SimilarResult<N> = Simplify<N & {
|
|
735
|
+
$score: number;
|
|
736
|
+
}>;
|
|
737
|
+
type VectorDelegate<TM extends TypeMap, M extends keyof TM> = [VectorIndexKeys<TM, M>] extends [
|
|
738
|
+
never
|
|
739
|
+
] ? unknown : {
|
|
740
|
+
/**
|
|
741
|
+
* The `k` nodes whose `field` is most similar to `vector`, best first, each with its
|
|
742
|
+
* `$score`, through the field's vector index (`db.index.vector.queryNodes`, Neo4j 5.15+).
|
|
743
|
+
*/
|
|
744
|
+
findSimilar<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args: FindSimilarArgs<TM, M> & Projection<S, I>): Promise<SimilarResult<Out<TM, M, S, I>>[]>;
|
|
745
|
+
};
|
|
746
|
+
/**
|
|
747
|
+
* How `search` reads `query`: `"lucene"` passes it through as Lucene query syntax (`title:graph*`,
|
|
748
|
+
* `"exact phrase"`, `a AND NOT b`, `fuzzy~`); `"terms"` escapes it and matches any of its words
|
|
749
|
+
* (ranked by relevance); `"phrase"` escapes it and matches the words in that order.
|
|
750
|
+
*/
|
|
751
|
+
type SearchMode = "lucene" | "terms" | "phrase";
|
|
752
|
+
type SearchArgs<TM extends TypeMap, M extends keyof TM> = {
|
|
753
|
+
/** The `@@fulltext` index to query (one of this model's index names). */
|
|
754
|
+
index: FulltextIndexNames<TM, M>;
|
|
755
|
+
/** The search text. A blank query matches nothing (`[]`). */
|
|
756
|
+
query: string;
|
|
757
|
+
/** How to read `query` (default `"lucene"`: Lucene query syntax, passed through). */
|
|
758
|
+
mode?: SearchMode;
|
|
759
|
+
/** Filter on the hits, applied in the same statement before `skip` / `take`. */
|
|
760
|
+
where?: WhereInput<TM, M>;
|
|
761
|
+
/** Drop hits scoring below this (Lucene scores: positive, unbounded, per-query). */
|
|
762
|
+
minScore?: number;
|
|
763
|
+
/** Hits to skip, after filtering and ranking. */
|
|
764
|
+
skip?: number;
|
|
765
|
+
/** Maximum number of hits (default: all of them). */
|
|
766
|
+
take?: number;
|
|
767
|
+
};
|
|
768
|
+
/** A `search` result: the node (honouring `select` / `include`) and its relevance score. */
|
|
769
|
+
type SearchResult<N> = Simplify<N & {
|
|
770
|
+
$score: number;
|
|
771
|
+
}>;
|
|
772
|
+
type FulltextDelegate<TM extends TypeMap, M extends keyof TM> = [
|
|
773
|
+
FulltextIndexNames<TM, M>
|
|
774
|
+
] extends [never] ? unknown : {
|
|
775
|
+
/**
|
|
776
|
+
* Nodes matching a full-text `query` on one of the model's `@@fulltext` indexes, best first,
|
|
777
|
+
* each with its `$score` (`db.index.fulltext.queryNodes`).
|
|
778
|
+
*/
|
|
779
|
+
search<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args: SearchArgs<TM, M> & Projection<S, I>): Promise<SearchResult<Out<TM, M, S, I>>[]>;
|
|
780
|
+
};
|
|
682
781
|
type Sel<TM extends TypeMap, M extends keyof TM> = SelectInput<TM, M> | undefined;
|
|
683
782
|
type Inc<TM extends TypeMap, M extends keyof TM> = IncludeInput<TM, M> | undefined;
|
|
684
783
|
type Out<TM extends TypeMap, M extends keyof TM, S, I> = Payload<TM, M, {
|
|
@@ -686,7 +785,8 @@ type Out<TM extends TypeMap, M extends keyof TM, S, I> = Payload<TM, M, {
|
|
|
686
785
|
include: I;
|
|
687
786
|
}>;
|
|
688
787
|
/** Operations available on `db.<model>`. */
|
|
689
|
-
type ModelDelegate<TM extends TypeMap, M extends keyof TM> =
|
|
788
|
+
type ModelDelegate<TM extends TypeMap, M extends keyof TM> = BaseModelDelegate<TM, M> & VectorDelegate<TM, M> & FulltextDelegate<TM, M>;
|
|
789
|
+
type BaseModelDelegate<TM extends TypeMap, M extends keyof TM> = {
|
|
690
790
|
findMany<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args?: FindManyArgs<TM, M> & Projection<S, I>): Promise<Out<TM, M, S, I>[]>;
|
|
691
791
|
findFirst<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args?: FindManyArgs<TM, M> & Projection<S, I>): Promise<Out<TM, M, S, I> | null>;
|
|
692
792
|
/** `null` when no node matches. */
|
|
@@ -817,10 +917,37 @@ declare class NotFoundError extends CyphraError {
|
|
|
817
917
|
/** Collision-resistant, URL-safe id (cuid2-style: a letter followed by 23 base-36 chars). */
|
|
818
918
|
declare function createCuid(): string;
|
|
819
919
|
|
|
920
|
+
/**
|
|
921
|
+
* `search`: full-text search on a node model through one of its `@@fulltext` indexes.
|
|
922
|
+
*
|
|
923
|
+
* One read-only statement: `db.index.fulltext.queryNodes(index, query)` returns every node of the
|
|
924
|
+
* index matching the Lucene query, with its relevance score; `where` and `minScore` filter those
|
|
925
|
+
* hits in the same statement, then the rows are ranked by score (best first) and `skip` / `take`
|
|
926
|
+
* page through them. Unlike a vector search there is no top-k cut-off before the filter, so a
|
|
927
|
+
* filtered search never comes back short.
|
|
928
|
+
*
|
|
929
|
+
* Scores are Lucene's (BM25): positive, unbounded, and only comparable within one query.
|
|
930
|
+
*
|
|
931
|
+
* @packageDocumentation
|
|
932
|
+
*/
|
|
933
|
+
|
|
934
|
+
/**
|
|
935
|
+
* Escape `text` for Lucene's query syntax (what `db.index.fulltext.queryNodes` parses): every
|
|
936
|
+
* special character (`+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /`) and the `AND` / `OR` / `NOT`
|
|
937
|
+
* operators are backslash-escaped, so user input is searched as plain words.
|
|
938
|
+
*
|
|
939
|
+
* @example
|
|
940
|
+
* ```ts
|
|
941
|
+
* escapeLucene('C++ (beta) AND "x"'); // 'C\\+\\+ \\(beta\\) \\AND \\"x\\"'
|
|
942
|
+
* await db.post.search({ index: "postSearch", query: `title:${escapeLucene(input)}~` });
|
|
943
|
+
* ```
|
|
944
|
+
*/
|
|
945
|
+
declare function escapeLucene(text: string): string;
|
|
946
|
+
|
|
820
947
|
/**
|
|
821
948
|
* Best-effort conversion of arbitrary driver values to plain JS: integers → number,
|
|
822
949
|
* temporal values → `Date`, nodes/relationships → their properties. Used for raw queries.
|
|
823
950
|
*/
|
|
824
951
|
declare function toNative(value: unknown): unknown;
|
|
825
952
|
|
|
826
|
-
export { type AggregateArgs, type AggregateFieldsInput, type AggregateResult, type BatchResult, type CountAggregateInput, type CountArgs, type CreateArgs, type CreateInput, type CreateManyArgs, CyphraClient, type CyphraClientOptions, type CyphraConnectionOptions, type CyphraDriverOptions, CyphraError, CyphraValidationError, type DelegateKey, type DeleteArgs, type DriverLike, type EdgeWhereInput, type FindManyArgs, type FindUniqueArgs, type GroupByArgs, type GroupByField, type GroupByKeys, type GroupByOrderByInput, type GroupByRow, type HavingInput, type IncludeInput, type MinMaxKeys, type ModelDelegate, type ModelDelegates, type ModelPath, type ModelTypeDef, NotFoundError, type NumericKeys, type OrderByInput, type OrmClient, type OrmOptions, type OrmTransactionClient, type Path, type PathEdge, type Payload, type QueryMode, type RelationCountInput, type RelationLoadArgs, type RelationTypeDef, type ScalarFilter, type SelectInput, type SelfRelations, type SessionLike, type ShortestPathArgs, type ShortestPathResult, type SortOrder, type ToManyRelations, type TransactionLike, type TraversalDirection, type TraversalResult, type TraverseArgs, type TypeMap, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpsertArgs, type WhereInput, type WhereUniqueInput, createCuid, createOrm, toNative, toPlainRecord, toPlainRecords };
|
|
953
|
+
export { type AggregateArgs, type AggregateFieldsInput, type AggregateResult, type BatchResult, type CountAggregateInput, type CountArgs, type CreateArgs, type CreateInput, type CreateManyArgs, CyphraClient, type CyphraClientOptions, type CyphraConnectionOptions, type CyphraDriverOptions, CyphraError, CyphraValidationError, type DelegateKey, type DeleteArgs, type DriverLike, type EdgeWhereInput, type FindManyArgs, type FindSimilarArgs, type FindUniqueArgs, type FulltextIndexNames, type GroupByArgs, type GroupByField, type GroupByKeys, type GroupByOrderByInput, type GroupByRow, type HavingInput, type IncludeInput, type MinMaxKeys, type ModelDelegate, type ModelDelegates, type ModelPath, type ModelTypeDef, NotFoundError, type NumericKeys, type OrderByInput, type OrmClient, type OrmOptions, type OrmTransactionClient, type Path, type PathEdge, type Payload, type QueryMode, type RelationCountInput, type RelationLoadArgs, type RelationTypeDef, type ScalarFilter, type SearchArgs, type SearchMode, type SearchResult, type SelectInput, type SelfRelations, type SessionLike, type ShortestPathArgs, type ShortestPathResult, type SimilarResult, type SortOrder, type ToManyRelations, type TransactionLike, type TraversalDirection, type TraversalResult, type TraverseArgs, type TypeMap, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpsertArgs, type VectorFilter, type VectorIndexKeys, type VectorKeys, type WhereInput, type WhereUniqueInput, createCuid, createOrm, escapeLucene, toNative, toPlainRecord, toPlainRecords };
|
package/dist/index.js
CHANGED
|
@@ -239,6 +239,26 @@ function encodeOne(type, value, where) {
|
|
|
239
239
|
}
|
|
240
240
|
throw new CyphraValidationError(`${where}: expected ${type}, got ${describe(value)}.`);
|
|
241
241
|
}
|
|
242
|
+
function encodeVector(value, dimensions, where) {
|
|
243
|
+
if (!Array.isArray(value) && !ArrayBuffer.isView(value)) {
|
|
244
|
+
throw new CyphraValidationError(
|
|
245
|
+
`${where}: expected a vector (number[] of length ${dimensions}), got ${describe(value)}.`
|
|
246
|
+
);
|
|
247
|
+
}
|
|
248
|
+
const arr = Array.from(value);
|
|
249
|
+
if (arr.length !== dimensions) {
|
|
250
|
+
throw new CyphraValidationError(
|
|
251
|
+
`${where}: expected a vector of ${dimensions} dimensions, got ${arr.length}.`
|
|
252
|
+
);
|
|
253
|
+
}
|
|
254
|
+
for (let i = 0; i < arr.length; i++) {
|
|
255
|
+
const x = arr[i];
|
|
256
|
+
if (typeof x !== "number" || !Number.isFinite(x)) {
|
|
257
|
+
throw new CyphraValidationError(`${where}[${i}]: expected a finite number.`);
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
return arr;
|
|
261
|
+
}
|
|
242
262
|
function describe(v) {
|
|
243
263
|
if (v === null) return "null";
|
|
244
264
|
if (v instanceof Date) return "Date";
|
|
@@ -253,6 +273,7 @@ function encodeScalar(field, value, owner) {
|
|
|
253
273
|
}
|
|
254
274
|
return null;
|
|
255
275
|
}
|
|
276
|
+
if (field.type === "Vector") return encodeVector(value, field.dimensions ?? 0, where);
|
|
256
277
|
if (field.list) {
|
|
257
278
|
if (!Array.isArray(value)) {
|
|
258
279
|
throw new CyphraValidationError(`${where}: expected an array.`);
|
|
@@ -262,6 +283,11 @@ function encodeScalar(field, value, owner) {
|
|
|
262
283
|
return encodeOne(field.type, value, where);
|
|
263
284
|
}
|
|
264
285
|
function encodeFilterValue(field, value, owner) {
|
|
286
|
+
if (field.type === "Vector") {
|
|
287
|
+
throw new CyphraValidationError(
|
|
288
|
+
`${owner}.${field.name}: Vector fields can only be filtered on null (use findSimilar to search them).`
|
|
289
|
+
);
|
|
290
|
+
}
|
|
265
291
|
return encodeOne(field.type, value, `${owner}.${field.name}`);
|
|
266
292
|
}
|
|
267
293
|
function decodeOne(type, value) {
|
|
@@ -279,6 +305,10 @@ function decodeOne(type, value) {
|
|
|
279
305
|
return value;
|
|
280
306
|
}
|
|
281
307
|
function decodeScalar(field, value) {
|
|
308
|
+
if (field.type === "Vector") {
|
|
309
|
+
if (value === null || value === void 0) return null;
|
|
310
|
+
return Array.from(value, (x) => isInt(x) ? integerToNumber(x) : x);
|
|
311
|
+
}
|
|
282
312
|
if (field.list) {
|
|
283
313
|
if (value === null || value === void 0) return [];
|
|
284
314
|
return value.map((v) => decodeOne(field.type, v));
|
|
@@ -395,8 +425,20 @@ function compileListFilter(ctx, model, field, ref, filter) {
|
|
|
395
425
|
}
|
|
396
426
|
return and(parts);
|
|
397
427
|
}
|
|
428
|
+
function compileVectorFilter(model, field, ref, filter) {
|
|
429
|
+
if (filter === null) return `${ref} IS NULL`;
|
|
430
|
+
const keys = isPlainObject(filter) ? Object.keys(filter).filter((k) => filter[k] !== void 0) : [];
|
|
431
|
+
if (isPlainObject(filter) && keys.every((k) => (k === "equals" || k === "not") && filter[k] === null)) {
|
|
432
|
+
const parts = keys.map((k) => k === "equals" ? `${ref} IS NULL` : `${ref} IS NOT NULL`);
|
|
433
|
+
return and(parts);
|
|
434
|
+
}
|
|
435
|
+
throw new CyphraValidationError(
|
|
436
|
+
`${model.name}.${field.name}: Vector fields can only be filtered on null (null, { equals: null }, { not: null }); use findSimilar to search them.`
|
|
437
|
+
);
|
|
438
|
+
}
|
|
398
439
|
function compileScalarFilter(ctx, model, field, ref, filter, inheritedMode = "default") {
|
|
399
440
|
if (filter === void 0) return null;
|
|
441
|
+
if (field.type === "Vector") return compileVectorFilter(model, field, ref, filter);
|
|
400
442
|
if (field.list) return compileListFilter(ctx, model, field, ref, filter);
|
|
401
443
|
const enc = (v) => encodeFilterValue(field, v, model.name);
|
|
402
444
|
if (filter === null) return `${ref} IS NULL`;
|
|
@@ -577,7 +619,11 @@ function compileOrderBy(ctx, model, alias, orderBy) {
|
|
|
577
619
|
parts.push(`${compileRelationCount(ctx, model, alias, rel)} ${d}`);
|
|
578
620
|
continue;
|
|
579
621
|
}
|
|
580
|
-
scalarOrThrow(model, key)
|
|
622
|
+
if (scalarOrThrow(model, key).type === "Vector") {
|
|
623
|
+
throw new CyphraValidationError(
|
|
624
|
+
`orderBy ${model.name}.${key}: Vector fields cannot be sorted.`
|
|
625
|
+
);
|
|
626
|
+
}
|
|
581
627
|
parts.push(`${alias}.${q(key)} ${sortDirection(dir, `${model.name}.${key}`)}`);
|
|
582
628
|
}
|
|
583
629
|
}
|
|
@@ -1429,6 +1475,200 @@ function compileShortestPath(ctx, model, args, cap, all) {
|
|
|
1429
1475
|
};
|
|
1430
1476
|
}
|
|
1431
1477
|
|
|
1478
|
+
// src/orm/vector.ts
|
|
1479
|
+
var ARG_KEYS3 = /* @__PURE__ */ new Set([
|
|
1480
|
+
"field",
|
|
1481
|
+
"vector",
|
|
1482
|
+
"k",
|
|
1483
|
+
"where",
|
|
1484
|
+
"select",
|
|
1485
|
+
"include",
|
|
1486
|
+
"minScore",
|
|
1487
|
+
"candidates",
|
|
1488
|
+
"maxCandidates",
|
|
1489
|
+
"exact"
|
|
1490
|
+
]);
|
|
1491
|
+
var CANDIDATE_GROWTH = 4;
|
|
1492
|
+
function positiveInt(v, name, op) {
|
|
1493
|
+
if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
|
|
1494
|
+
throw new CyphraValidationError(`${op}: ${name} must be a positive integer.`);
|
|
1495
|
+
}
|
|
1496
|
+
return v;
|
|
1497
|
+
}
|
|
1498
|
+
function toScore(v) {
|
|
1499
|
+
return typeof v === "number" ? v : Number(v);
|
|
1500
|
+
}
|
|
1501
|
+
function vectorField(model, name, op) {
|
|
1502
|
+
const indexed = model.fields.filter(
|
|
1503
|
+
(f2) => f2.kind === "scalar" && Boolean(f2.vectorIndex)
|
|
1504
|
+
);
|
|
1505
|
+
if (typeof name !== "string") {
|
|
1506
|
+
throw new CyphraValidationError(
|
|
1507
|
+
`${op}: field is required (${indexed.map((f2) => f2.name).join(", ") || `${model.name} has no @vectorIndex field`}).`
|
|
1508
|
+
);
|
|
1509
|
+
}
|
|
1510
|
+
const f = model.fields.find((x) => x.name === name);
|
|
1511
|
+
if (!f || f.kind !== "scalar" || f.type !== "Vector") {
|
|
1512
|
+
throw new CyphraValidationError(`${op}: ${model.name}.${name} is not a Vector field.`);
|
|
1513
|
+
}
|
|
1514
|
+
if (!f.vectorIndex) {
|
|
1515
|
+
throw new CyphraValidationError(
|
|
1516
|
+
`${op}: ${model.name}.${name} has no @vectorIndex; declare one to search it.`
|
|
1517
|
+
);
|
|
1518
|
+
}
|
|
1519
|
+
return f;
|
|
1520
|
+
}
|
|
1521
|
+
async function findSimilar(exec, ctxFactory, model, args) {
|
|
1522
|
+
const op = `${model.name}.findSimilar`;
|
|
1523
|
+
for (const key of Object.keys(args)) {
|
|
1524
|
+
if (!ARG_KEYS3.has(key)) throw new CyphraValidationError(`${op}: unknown argument "${key}".`);
|
|
1525
|
+
}
|
|
1526
|
+
const field = vectorField(model, args.field, op);
|
|
1527
|
+
const index = field.vectorIndex;
|
|
1528
|
+
const vector = encodeVector(args.vector, field.dimensions ?? 0, `${op} vector`);
|
|
1529
|
+
if (args.k === void 0) throw new CyphraValidationError(`${op}: k is required.`);
|
|
1530
|
+
const k = positiveInt(args.k, "k", op);
|
|
1531
|
+
const minScore = args.minScore;
|
|
1532
|
+
if (minScore !== void 0 && (typeof minScore !== "number" || !Number.isFinite(minScore))) {
|
|
1533
|
+
throw new CyphraValidationError(`${op}: minScore must be a finite number.`);
|
|
1534
|
+
}
|
|
1535
|
+
if (args.exact !== void 0 && typeof args.exact !== "boolean") {
|
|
1536
|
+
throw new CyphraValidationError(`${op}: exact must be a boolean.`);
|
|
1537
|
+
}
|
|
1538
|
+
const ctx = ctxFactory();
|
|
1539
|
+
const where = compileWhere(ctx, model, "n", args.where);
|
|
1540
|
+
const candidates = args.candidates === void 0 ? where ? Math.max(10 * k, 100) : k : positiveInt(args.candidates, "candidates", op);
|
|
1541
|
+
if (candidates < k) {
|
|
1542
|
+
throw new CyphraValidationError(`${op}: candidates must be at least k (${k}).`);
|
|
1543
|
+
}
|
|
1544
|
+
const maxCandidates = args.maxCandidates === void 0 ? Number.POSITIVE_INFINITY : positiveInt(args.maxCandidates, "maxCandidates", op);
|
|
1545
|
+
if (maxCandidates < candidates) {
|
|
1546
|
+
throw new CyphraValidationError(`${op}: maxCandidates must be at least candidates.`);
|
|
1547
|
+
}
|
|
1548
|
+
const prop = q(field.name);
|
|
1549
|
+
const vec = ctx.param(vector);
|
|
1550
|
+
const limit = ctx.param(intParam(k));
|
|
1551
|
+
const scoreOk = minScore === void 0 ? null : `score >= ${ctx.param(minScore)}`;
|
|
1552
|
+
const { expr, shape } = compileProjection(ctx, model, "n", args);
|
|
1553
|
+
const decode = (rows) => rows.map((r) => ({ ...decodeRow(shape, r.row), $score: toScore(r.score) })).sort((a, b) => b.$score - a.$score).slice(0, k);
|
|
1554
|
+
if (args.exact === true) {
|
|
1555
|
+
const fn = index.similarity === "euclidean" ? "vector.similarity.euclidean" : "vector.similarity.cosine";
|
|
1556
|
+
const filters = [
|
|
1557
|
+
`n.${prop} IS NOT NULL`,
|
|
1558
|
+
`size(n.${prop}) = ${ctx.param(intParam(vector.length))}`
|
|
1559
|
+
];
|
|
1560
|
+
if (where) filters.push(`(${where})`);
|
|
1561
|
+
let text2 = `MATCH (n:${q(model.label)}) WHERE ${filters.join(" AND ")}`;
|
|
1562
|
+
text2 += ` WITH n, ${fn}(n.${prop}, ${vec}) AS score`;
|
|
1563
|
+
if (scoreOk) text2 += ` WHERE ${scoreOk}`;
|
|
1564
|
+
text2 += ` WITH n, score ORDER BY score DESC LIMIT ${limit}`;
|
|
1565
|
+
text2 += ` RETURN ${expr} AS row, score ORDER BY score DESC`;
|
|
1566
|
+
const rows = await exec(text2, ctx.params);
|
|
1567
|
+
return decode(rows);
|
|
1568
|
+
}
|
|
1569
|
+
const name = ctx.param(index.name);
|
|
1570
|
+
const call = (count2) => `CALL db.index.vector.queryNodes(${name}, ${count2}, ${vec}) YIELD node, score`;
|
|
1571
|
+
if (!where) {
|
|
1572
|
+
let text2 = `${call(ctx.param(intParam(candidates)))} WITH node AS n, score`;
|
|
1573
|
+
if (scoreOk) text2 += ` WHERE ${scoreOk}`;
|
|
1574
|
+
text2 += ` WITH n, score ORDER BY score DESC LIMIT ${limit}`;
|
|
1575
|
+
text2 += ` RETURN ${expr} AS row, score ORDER BY score DESC`;
|
|
1576
|
+
const rows = await exec(text2, ctx.params);
|
|
1577
|
+
return decode(rows);
|
|
1578
|
+
}
|
|
1579
|
+
const count = "$cyphraCandidates";
|
|
1580
|
+
const filter = [scoreOk, where].filter(Boolean).join(" AND ");
|
|
1581
|
+
const text = `${call(count)} WITH collect({n: node, s: score}) AS hits CALL { WITH hits UNWIND hits AS h WITH h.n AS n, h.s AS score WHERE ${filter} WITH n, score ORDER BY score DESC LIMIT ${limit} RETURN collect({row: ${expr}, score: score}) AS rows } RETURN size(hits) AS fetched, hits[-1].s AS lowest, rows`;
|
|
1582
|
+
let asked = Math.min(candidates, maxCandidates);
|
|
1583
|
+
for (; ; ) {
|
|
1584
|
+
const [res] = await exec(text, { ...ctx.params, cyphraCandidates: intParam(asked) });
|
|
1585
|
+
const rows = res?.rows ?? [];
|
|
1586
|
+
const fetched = decodeCount(res?.fetched);
|
|
1587
|
+
const lowest = res?.lowest;
|
|
1588
|
+
const exhausted = fetched < asked || asked >= maxCandidates || minScore !== void 0 && lowest !== null && lowest !== void 0 && toScore(lowest) < minScore;
|
|
1589
|
+
if (rows.length >= k || exhausted) return decode(rows);
|
|
1590
|
+
asked = Math.min(asked * CANDIDATE_GROWTH, maxCandidates);
|
|
1591
|
+
}
|
|
1592
|
+
}
|
|
1593
|
+
|
|
1594
|
+
// src/orm/fulltext.ts
|
|
1595
|
+
var ARG_KEYS4 = /* @__PURE__ */ new Set([
|
|
1596
|
+
"index",
|
|
1597
|
+
"query",
|
|
1598
|
+
"mode",
|
|
1599
|
+
"where",
|
|
1600
|
+
"minScore",
|
|
1601
|
+
"skip",
|
|
1602
|
+
"take",
|
|
1603
|
+
"select",
|
|
1604
|
+
"include"
|
|
1605
|
+
]);
|
|
1606
|
+
var MODES = ["lucene", "terms", "phrase"];
|
|
1607
|
+
var LUCENE_SPECIAL = /[+\-&|!(){}[\]^"~*?:\\/]/g;
|
|
1608
|
+
var LUCENE_OPERATORS = /\b(AND|OR|NOT)\b/g;
|
|
1609
|
+
function escapeLucene(text) {
|
|
1610
|
+
return text.replace(LUCENE_SPECIAL, "\\$&").replace(LUCENE_OPERATORS, "\\$1");
|
|
1611
|
+
}
|
|
1612
|
+
function luceneQuery(query, mode) {
|
|
1613
|
+
if (mode === "terms") return escapeLucene(query);
|
|
1614
|
+
if (mode === "phrase") return `"${escapeLucene(query)}"`;
|
|
1615
|
+
return query;
|
|
1616
|
+
}
|
|
1617
|
+
async function search(exec, ctxFactory, model, args) {
|
|
1618
|
+
const op = `${model.name}.search`;
|
|
1619
|
+
for (const key of Object.keys(args)) {
|
|
1620
|
+
if (!ARG_KEYS4.has(key)) throw new CyphraValidationError(`${op}: unknown argument "${key}".`);
|
|
1621
|
+
}
|
|
1622
|
+
const indexes = model.fulltextIndexes ?? [];
|
|
1623
|
+
const names = indexes.map((i) => i.name);
|
|
1624
|
+
if (typeof args.index !== "string") {
|
|
1625
|
+
throw new CyphraValidationError(
|
|
1626
|
+
`${op}: index is required (${names.join(", ") || `${model.name} has no @@fulltext index`}).`
|
|
1627
|
+
);
|
|
1628
|
+
}
|
|
1629
|
+
if (!names.includes(args.index)) {
|
|
1630
|
+
throw new CyphraValidationError(
|
|
1631
|
+
`${op}: ${JSON.stringify(args.index)} is not a full-text index of ${model.name} (${names.join(", ") || "declare one with @@fulltext"}).`
|
|
1632
|
+
);
|
|
1633
|
+
}
|
|
1634
|
+
if (typeof args.query !== "string") {
|
|
1635
|
+
throw new CyphraValidationError(`${op}: query must be a string.`);
|
|
1636
|
+
}
|
|
1637
|
+
const mode = args.mode ?? "lucene";
|
|
1638
|
+
if (!MODES.includes(mode)) {
|
|
1639
|
+
throw new CyphraValidationError(`${op}: mode must be ${MODES.join(", ")}.`);
|
|
1640
|
+
}
|
|
1641
|
+
const minScore = args.minScore;
|
|
1642
|
+
if (minScore !== void 0 && (typeof minScore !== "number" || !Number.isFinite(minScore))) {
|
|
1643
|
+
throw new CyphraValidationError(`${op}: minScore must be a finite number.`);
|
|
1644
|
+
}
|
|
1645
|
+
const skip = args.skip === void 0 ? void 0 : nonNegativeInt(args.skip, `${op}: skip`);
|
|
1646
|
+
const take = args.take === void 0 ? void 0 : nonNegativeInt(args.take, `${op}: take`);
|
|
1647
|
+
const ctx = ctxFactory();
|
|
1648
|
+
const where = compileWhere(ctx, model, "n", args.where);
|
|
1649
|
+
const { expr, shape } = compileProjection(ctx, model, "n", args);
|
|
1650
|
+
if (args.query.trim() === "" || take === 0) return [];
|
|
1651
|
+
const name = ctx.param(args.index);
|
|
1652
|
+
const query = ctx.param(luceneQuery(args.query, mode));
|
|
1653
|
+
const filters = [
|
|
1654
|
+
...minScore === void 0 ? [] : [`score >= ${ctx.param(minScore)}`],
|
|
1655
|
+
...where ? [`(${where})`] : []
|
|
1656
|
+
];
|
|
1657
|
+
const options = filters.length === 0 && take !== void 0 ? `, {limit: ${ctx.param(intParam((skip ?? 0) + take))}}` : "";
|
|
1658
|
+
let text = `CALL db.index.fulltext.queryNodes(${name}, ${query}${options}) YIELD node, score`;
|
|
1659
|
+
text += " WITH node AS n, score";
|
|
1660
|
+
if (filters.length) text += ` WHERE ${filters.join(" AND ")}`;
|
|
1661
|
+
text += " WITH n, score ORDER BY score DESC";
|
|
1662
|
+
if (skip !== void 0) text += ` SKIP ${ctx.param(intParam(skip))}`;
|
|
1663
|
+
if (take !== void 0) text += ` LIMIT ${ctx.param(intParam(take))}`;
|
|
1664
|
+
text += ` RETURN ${expr} AS row, score ORDER BY score DESC`;
|
|
1665
|
+
const rows = await exec(text, ctx.params);
|
|
1666
|
+
return rows.map((r) => ({
|
|
1667
|
+
...decodeRow(shape, r.row),
|
|
1668
|
+
$score: typeof r.score === "number" ? r.score : Number(r.score)
|
|
1669
|
+
}));
|
|
1670
|
+
}
|
|
1671
|
+
|
|
1432
1672
|
// src/orm/engine.ts
|
|
1433
1673
|
function isPlainObject5(v) {
|
|
1434
1674
|
return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
|
|
@@ -1593,6 +1833,21 @@ var ModelEngine = class _ModelEngine {
|
|
|
1593
1833
|
return c.decode(await exec(c.text, c.params));
|
|
1594
1834
|
});
|
|
1595
1835
|
}
|
|
1836
|
+
/** Nearest neighbours on a `@vectorIndex` field; see {@link findSimilar}. */
|
|
1837
|
+
findSimilar(args) {
|
|
1838
|
+
return this.runner.read(async (exec) => {
|
|
1839
|
+
if (!isPlainObject5(args))
|
|
1840
|
+
throw new CyphraValidationError("findSimilar args must be an object.");
|
|
1841
|
+
return findSimilar(exec, () => this.ctx(), this.model, args);
|
|
1842
|
+
});
|
|
1843
|
+
}
|
|
1844
|
+
/** Full-text search through a `@@fulltext` index; see {@link search}. */
|
|
1845
|
+
search(args) {
|
|
1846
|
+
return this.runner.read(async (exec) => {
|
|
1847
|
+
if (!isPlainObject5(args)) throw new CyphraValidationError("search args must be an object.");
|
|
1848
|
+
return search(exec, () => this.ctx(), this.model, args);
|
|
1849
|
+
});
|
|
1850
|
+
}
|
|
1596
1851
|
// -------------------------------------------------------------------------
|
|
1597
1852
|
// Write helpers
|
|
1598
1853
|
// -------------------------------------------------------------------------
|
|
@@ -2082,6 +2337,7 @@ export {
|
|
|
2082
2337
|
NotFoundError,
|
|
2083
2338
|
createCuid,
|
|
2084
2339
|
createOrm,
|
|
2340
|
+
escapeLucene,
|
|
2085
2341
|
toNative,
|
|
2086
2342
|
toPlainRecord,
|
|
2087
2343
|
toPlainRecords
|