@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 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>]?: SortOrder;
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