@delali/narsil 0.3.0 → 0.3.1-next.102

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.
Files changed (165) hide show
  1. package/README.md +9 -8
  2. package/dist/adapters/filesystem.d.ts +1 -1
  3. package/dist/adapters/filesystem.mjs +1 -1
  4. package/dist/adapters/indexeddb.d.ts +1 -1
  5. package/dist/adapters/indexeddb.mjs +1 -1
  6. package/dist/adapters/memory.d.ts +1 -1
  7. package/dist/{adapters-79OIa4xm.d.ts → adapters-BQFQ4PRz.d.ts} +27 -1
  8. package/dist/browser/chunk-BDOSMEEP.mjs +493 -0
  9. package/dist/browser/chunk-EJDUFWSO.mjs +602 -0
  10. package/dist/browser/chunk-HOZW3PKP.mjs +9 -0
  11. package/dist/browser/chunk-JOVZ6HMT.mjs +4358 -0
  12. package/dist/browser/chunk-JPTQZWJQ.mjs +10 -0
  13. package/dist/browser/chunk-KPJMDPHG.mjs +24558 -0
  14. package/dist/browser/chunk-PGIM3HIM.mjs +2743 -0
  15. package/dist/browser/chunk-RHG4O77A.mjs +206 -0
  16. package/dist/browser/chunk-RIJSLY2I.mjs +360 -0
  17. package/dist/browser/durability-wiring-SRUYT3VV.mjs +3875 -0
  18. package/dist/browser/module-CBB2ETYP.mjs +3111 -0
  19. package/dist/browser/release-76MXRPGV.mjs +33 -0
  20. package/dist/browser/replace-RURXTGVG.mjs +57 -0
  21. package/dist/browser/restore-queue-EEZQO6RF.mjs +35 -0
  22. package/dist/browser/runtime-7ZAHCHWR.mjs +557 -0
  23. package/dist/browser/snapshot-OAAA5UJ7.mjs +1210 -0
  24. package/dist/browser/write-7D6VIK6O.mjs +208 -0
  25. package/dist/{capabilities-DSsOGz6F.d.ts → capabilities-ByQRMOx-.d.ts} +68 -7
  26. package/dist/chunk-2RIRGOUL.mjs +113 -0
  27. package/dist/chunk-37CD3OKS.mjs +87 -0
  28. package/dist/chunk-44W3CBNG.mjs +7 -0
  29. package/dist/chunk-46D6JQIG.mjs +426 -0
  30. package/dist/{chunk-VMRR3DQU.mjs → chunk-5JNA5SKS.mjs} +546 -35
  31. package/dist/chunk-747OHOUA.mjs +11 -0
  32. package/dist/chunk-75XIEF6H.mjs +126 -0
  33. package/dist/chunk-7X5JST5L.mjs +114 -0
  34. package/dist/chunk-BOFBLJFZ.mjs +209 -0
  35. package/dist/{chunk-USKFU7J5.mjs → chunk-BWJVNZPR.mjs} +8 -1
  36. package/dist/chunk-C7SLA6CM.mjs +19 -0
  37. package/dist/{chunk-POWOTUKJ.mjs → chunk-CQUMNIIG.mjs} +3 -6
  38. package/dist/chunk-CVXLLEQ3.mjs +1011 -0
  39. package/dist/chunk-DJHHF2L5.mjs +17 -0
  40. package/dist/chunk-E74YLAIG.mjs +24 -0
  41. package/dist/{chunk-UXNWQZST.mjs → chunk-EMRMGYRE.mjs} +236 -18
  42. package/dist/chunk-EWZLIYHV.mjs +57 -0
  43. package/dist/chunk-GBEEG5AN.mjs +35 -0
  44. package/dist/chunk-GES7U2PM.mjs +68 -0
  45. package/dist/chunk-HJSN7UYG.mjs +10 -0
  46. package/dist/chunk-HLPRHOSO.mjs +17 -0
  47. package/dist/chunk-HMFNFVP7.mjs +14 -0
  48. package/dist/chunk-J5QP52HA.mjs +1751 -0
  49. package/dist/{chunk-YNVIUGF5.mjs → chunk-JZVARCRZ.mjs} +3 -28
  50. package/dist/chunk-KOKM4PQN.mjs +52 -0
  51. package/dist/{chunk-B2TFROFX.mjs → chunk-KWTW6VTG.mjs} +465 -250
  52. package/dist/chunk-KZ3NX2P7.mjs +21 -0
  53. package/dist/chunk-L5ORED7V.mjs +25 -0
  54. package/dist/{chunk-THYRHHO2.mjs → chunk-LGAMKHA2.mjs} +2009 -2351
  55. package/dist/chunk-LKOB5COA.mjs +117 -0
  56. package/dist/chunk-LPQOEU5M.mjs +96 -0
  57. package/dist/{chunk-3LHGNRYE.mjs → chunk-LXWDQLTW.mjs} +7 -2
  58. package/dist/{chunk-L6TNPLAR.mjs → chunk-OEYI3KRB.mjs} +270 -108
  59. package/dist/chunk-OM362BRO.mjs +948 -0
  60. package/dist/chunk-OZDFA4WC.mjs +67 -0
  61. package/dist/chunk-P36MUFEJ.mjs +10 -0
  62. package/dist/chunk-PC2G76VW.mjs +2540 -0
  63. package/dist/{chunk-GCM3JFVA.mjs → chunk-PNEYIHA4.mjs} +11 -2
  64. package/dist/chunk-PNFKUCG3.mjs +1130 -0
  65. package/dist/chunk-Q6XWVUZX.mjs +44 -0
  66. package/dist/chunk-R27EMH5M.mjs +617 -0
  67. package/dist/{chunk-YMZCMH5M.mjs → chunk-R6A773WK.mjs} +19 -24
  68. package/dist/chunk-RF7PLG43.mjs +106 -0
  69. package/dist/chunk-RFBLQLLZ.mjs +16 -0
  70. package/dist/{chunk-Y3L5MDRV.mjs → chunk-RFVUDM5E.mjs} +17 -2
  71. package/dist/chunk-S7FL6UAH.mjs +521 -0
  72. package/dist/chunk-S7GNDRPS.mjs +651 -0
  73. package/dist/chunk-SP3NM3ZG.mjs +3537 -0
  74. package/dist/chunk-U476IXKQ.mjs +10 -0
  75. package/dist/chunk-UA3AUGNV.mjs +462 -0
  76. package/dist/chunk-UTG5YNXV.mjs +507 -0
  77. package/dist/chunk-VI4R6W25.mjs +8484 -0
  78. package/dist/chunk-WQBCBKY3.mjs +8 -0
  79. package/dist/{chunk-24RXHMEL.mjs → chunk-WVCOCKBU.mjs} +3794 -7570
  80. package/dist/chunk-X5CV2E2B.mjs +1 -0
  81. package/dist/chunk-XADZPPZI.mjs +614 -0
  82. package/dist/chunk-YEEQHT4V.mjs +212 -0
  83. package/dist/chunk-YTJCGKM4.mjs +56 -0
  84. package/dist/chunk-YYQIODMF.mjs +275 -0
  85. package/dist/chunk-ZI34TVOA.mjs +144 -0
  86. package/dist/{chunk-OOSIDHA3.mjs → chunk-ZKWYWW4Y.mjs} +1 -1
  87. package/dist/chunk-ZM7KU4YW.mjs +35 -0
  88. package/dist/{client-BQK6Tf6A.d.ts → client-BOStAkc5.d.ts} +160 -37
  89. package/dist/client.d.ts +11 -10
  90. package/dist/client.mjs +209 -45
  91. package/dist/{config-DmXULPa-.d.ts → config-Cjvzbs_j.d.ts} +51 -3
  92. package/dist/config-H6SGzbPH.d.ts +421 -0
  93. package/dist/direct-executor-ZD64PPEZ.mjs +24 -0
  94. package/dist/distribution/coordinator/etcd.d.ts +79 -18
  95. package/dist/distribution/coordinator/etcd.mjs +553 -109
  96. package/dist/distribution/coordinator/in-memory.d.ts +4 -3
  97. package/dist/distribution/coordinator/in-memory.mjs +22 -3
  98. package/dist/distribution/transport/grpc.d.ts +2 -2
  99. package/dist/distribution/transport/grpc.mjs +79 -14
  100. package/dist/distribution/transport/in-memory.d.ts +2 -2
  101. package/dist/distribution/transport/in-memory.mjs +12 -7
  102. package/dist/distribution/transport/tcp.d.ts +2 -2
  103. package/dist/distribution/transport/tcp.mjs +50 -28
  104. package/dist/distribution.d.ts +144 -23
  105. package/dist/distribution.mjs +14479 -8173
  106. package/dist/durability-wiring-FEUBR5BT.mjs +3330 -0
  107. package/dist/embeddings/openai.d.ts +2 -2
  108. package/dist/embeddings/openai.mjs +22 -133
  109. package/dist/{engine-CIOyFozK.d.ts → engine-rC0vjjY-.d.ts} +165 -141
  110. package/dist/{memory-yFaVn2xZ.d.ts → events-DqOIg5xa.d.ts} +645 -136
  111. package/dist/{types-DAK7mnUZ.d.ts → index-Bkdt8nDw.d.ts} +182 -45
  112. package/dist/index.browser.mjs +4 -32180
  113. package/dist/index.d.ts +91 -20
  114. package/dist/index.mjs +33 -16
  115. package/dist/invalidation/broadcast-channel.d.ts +1 -1
  116. package/dist/invalidation/filesystem.d.ts +1 -1
  117. package/dist/invalidation/filesystem.mjs +2 -1
  118. package/dist/invalidation/noop.d.ts +1 -1
  119. package/dist/module-3S65MVCM.mjs +2151 -0
  120. package/dist/partial-words-DTIHO8G4.d.ts +19 -0
  121. package/dist/partial-words.d.ts +22 -0
  122. package/dist/partial-words.mjs +17 -0
  123. package/dist/pattern-Cledccbl.d.ts +18 -0
  124. package/dist/pattern.d.ts +22 -0
  125. package/dist/pattern.mjs +12 -0
  126. package/dist/persistence/durability/checkpoint-worker.d.ts +119 -72
  127. package/dist/persistence/durability/checkpoint-worker.mjs +51 -18
  128. package/dist/react.d.ts +279 -183
  129. package/dist/react.mjs +201 -48
  130. package/dist/release-BH3DKW3T.mjs +33 -0
  131. package/dist/replace-CEO5KJJ3.mjs +57 -0
  132. package/dist/rerank-K7C4WZFG.mjs +60 -0
  133. package/dist/rerankers/http.d.ts +50 -0
  134. package/dist/rerankers/http.mjs +104 -0
  135. package/dist/restore-queue-KQHA7ZV2.mjs +35 -0
  136. package/dist/runtime-6Y4ZYXOG.mjs +177 -0
  137. package/dist/{schema-d5Afu03A.d.ts → schema-4W_7tk1f.d.ts} +81 -11
  138. package/dist/server.d.ts +13 -12
  139. package/dist/server.mjs +611 -80
  140. package/dist/snapshot-QGZPODM5.mjs +799 -0
  141. package/dist/synonyms-CpOAHPa-.d.ts +52 -0
  142. package/dist/synonyms.d.ts +22 -0
  143. package/dist/synonyms.mjs +12 -0
  144. package/dist/{tasks-CH2Dod8w.d.ts → tasks-CwPTz-tP.d.ts} +10 -3
  145. package/dist/thread-N3IUGUS3.mjs +697 -0
  146. package/dist/{types-BQDlIvfS.d.ts → types-2qoitTXg.d.ts} +1 -1
  147. package/dist/{types-D5OwhtsQ.d.ts → types-Cz5okLml.d.ts} +2 -2
  148. package/dist/vector/search-worker.d.ts +46 -4
  149. package/dist/vector/search-worker.mjs +21 -11
  150. package/dist/workers/entry.mjs +9 -6
  151. package/dist/write-U5RI7MAX.mjs +241 -0
  152. package/package.json +55 -9
  153. package/dist/chunk-3L4U6EJQ.mjs +0 -49
  154. package/dist/chunk-IFBKLBGB.mjs +0 -7
  155. package/dist/chunk-ORBLD3EL.mjs +0 -6
  156. package/dist/chunk-U7KYW4BA.mjs +0 -135
  157. package/dist/chunk-ZJ4CSAB2.mjs +0 -13
  158. package/dist/chunk-ZNZBXMP5.mjs +0 -2117
  159. package/dist/chunk-ZZT3EAUC.mjs +0 -11168
  160. package/dist/config-BhldZgaK.d.ts +0 -194
  161. package/dist/direct-executor-ALAVE7FC.mjs +0 -12
  162. package/dist/serialization/crc32-worker.d.ts +0 -20
  163. package/dist/serialization/crc32-worker.mjs +0 -62
  164. package/dist/simd-DW5AtJ6B.d.ts +0 -41
  165. package/dist/thread-DYHEQRVY.mjs +0 -402
@@ -1,4 +1,4 @@
1
- import { A as AnyDocument, S as SchemaDefinition, c as ScoringMode } from './schema-d5Afu03A.js';
1
+ import { A as AnyDocument, S as SchemaDefinition, d as ScoringMode } from './schema-4W_7tk1f.js';
2
2
 
3
3
  /**
4
4
  * Every code a {@link NarsilError} carries, grouped by the part of the engine
@@ -41,14 +41,18 @@ declare const ErrorCodes: {
41
41
  readonly SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE";
42
42
  readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
43
43
  readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
44
+ readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
44
45
  readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
45
46
  readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
46
47
  readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
47
48
  readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
49
+ readonly RESTORE_MEMORY_EXCEEDED: "RESTORE_MEMORY_EXCEEDED";
48
50
  readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
49
51
  readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
50
52
  readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
51
53
  readonly EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID";
54
+ readonly RERANK_FAILED: "RERANK_FAILED";
55
+ readonly RERANK_CONFIG_INVALID: "RERANK_CONFIG_INVALID";
52
56
  readonly DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD";
53
57
  readonly CONFIG_INVALID: "CONFIG_INVALID";
54
58
  readonly QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED";
@@ -56,6 +60,7 @@ declare const ErrorCodes: {
56
60
  readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
57
61
  readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
58
62
  readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
63
+ readonly CLUSTER_WRITE_BLOCKED: "CLUSTER_WRITE_BLOCKED";
59
64
  readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
60
65
  readonly ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG";
61
66
  readonly ALLOCATION_FAILED: "ALLOCATION_FAILED";
@@ -65,7 +70,10 @@ declare const ErrorCodes: {
65
70
  readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
66
71
  readonly NODE_NOT_READY: "NODE_NOT_READY";
67
72
  readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
73
+ readonly NODE_VERSION_INCOMPATIBLE: "NODE_VERSION_INCOMPATIBLE";
68
74
  readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
75
+ readonly COORDINATOR_AUTH_FAILED: "COORDINATOR_AUTH_FAILED";
76
+ readonly COORDINATOR_UNAVAILABLE: "COORDINATOR_UNAVAILABLE";
69
77
  readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
70
78
  readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
71
79
  readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
@@ -81,7 +89,6 @@ declare const ErrorCodes: {
81
89
  readonly SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED";
82
90
  readonly SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID";
83
91
  readonly SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND";
84
- readonly SNAPSHOT_SYNC_TOO_LARGE: "SNAPSHOT_SYNC_TOO_LARGE";
85
92
  readonly SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED";
86
93
  readonly SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED";
87
94
  readonly SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED";
@@ -424,6 +431,24 @@ interface BatchResult {
424
431
  error: NarsilError;
425
432
  }>;
426
433
  }
434
+ /**
435
+ * What {@link Narsil.importDocumentExport} returns. The engine continues past each
436
+ * refused line, so read the refusals to learn which documents it skipped.
437
+ *
438
+ * @public
439
+ */
440
+ interface DocumentImportResult {
441
+ /** The engine wrote this many documents, counting each one that it replaced. */
442
+ imported: number;
443
+ /** The engine refused this many lines in total. */
444
+ refusedCount: number;
445
+ /** These are the 1,000 refusals with the lowest line numbers. Each entry contains the line number, where the header is line 1, along with the error code and a message. */
446
+ refused: Array<{
447
+ line: number;
448
+ code: NarsilErrorCode;
449
+ message: string;
450
+ }>;
451
+ }
427
452
  /**
428
453
  * What {@link Narsil.getStats} returns about one index.
429
454
  *
@@ -577,9 +602,13 @@ interface ListResult<T = AnyDocument> {
577
602
  * @public
578
603
  */
579
604
  type ComparisonFilter = {
580
- /** This matches a field equal to the value. */
605
+ /** This matches a field equal to the value, or a list field where one element equals it. */
581
606
  eq?: number | string | boolean;
582
- /** This matches a field holding anything other than the value. */
607
+ /**
608
+ * This matches a document that holds the field with a value other than this
609
+ * one, or a list field where every element differs from it, which an empty
610
+ * list does.
611
+ */
583
612
  ne?: number | string | boolean;
584
613
  /** This matches a field greater than the number. */
585
614
  gt?: number;
@@ -593,36 +622,164 @@ type ComparisonFilter = {
593
622
  between?: [number, number];
594
623
  };
595
624
  /**
596
- * Everything {@link ComparisonFilter} offers, with the set and prefix tests a
597
- * string field also supports.
598
- *
599
- * On a `string[]` field, the engine compares each element of the list, so
600
- * `eq`, `in`, `startsWith`, and `endsWith` match a document where one element
601
- * matches, and `ne` and `nin` match a document where no element matches.
625
+ * The engine tests a text field against this filter for equality, for a text
626
+ * range, or with the set, prefix, and pattern tests.
627
+ *
628
+ * On a `string[]`, `verbatim[]`, or `enum[]` field, the engine tests each
629
+ * element of the list on its own. A document passes `eq`, `in`, `startsWith`,
630
+ * `endsWith`, `contains`, `wildcard`, or `regex` when one element passes the
631
+ * test. However, a document passes `ne` or `nin` only when every element
632
+ * differs from the values.
633
+ *
634
+ * The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
635
+ * to a single `string` or `verbatim` field whose type includes `sortable`. It
636
+ * throws `SEARCH_INVALID_FILTER` for a text range on any other field. It
637
+ * orders the values as a sort on the field does, so it compares their case
638
+ * folds first and compares their raw code points only where the folds are
639
+ * equal.
640
+ *
641
+ * A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
642
+ * `string[]` field whose type includes `pattern`. On a pattern field, the
643
+ * engine answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
644
+ * `contains`, `wildcard`, and `regex` from the field's pattern index, and
645
+ * `caseFold` applies to each of those tests. The engine compares the code
646
+ * points of each value as they are stored, with no Unicode normalisation.
647
+ *
648
+ * On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
649
+ * `startsWith`, and `endsWith` from the field's index of values. A `string` or
650
+ * `string[]` field whose type leaves out `pattern` keeps no index of whole
651
+ * values, so the engine throws `SEARCH_INVALID_FILTER` for those six tests,
652
+ * and for `matchesAny` and `containsAll`, on such a field.
653
+ *
654
+ * The engine also throws `SEARCH_INVALID_FILTER` in these cases:
655
+ *
656
+ * - The filter sets `contains`, `wildcard`, `regex`, or `caseFold` on a field
657
+ * that is not a pattern field.
658
+ * - The text or the pattern of a test on a pattern field holds more than 1,024
659
+ * code points.
660
+ * - A literal test under `caseFold` has a text whose case fold holds more than
661
+ * 2,048 code points.
662
+ * - A `wildcard` or `regex` pattern breaks its syntax or one of its limits.
602
663
  *
603
664
  * @public
604
665
  */
605
- type StringFilter = ComparisonFilter & {
606
- /** This matches a field equal to any value in the list. */
666
+ type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
667
+ /** This matches a value that comes after the text in sort order. */
668
+ gt?: string;
669
+ /** This matches a value that comes before the text in sort order. */
670
+ lt?: string;
671
+ /** This matches a value equal to the text or after it in sort order. */
672
+ gte?: string;
673
+ /** This matches a value equal to the text or before it in sort order. */
674
+ lte?: string;
675
+ /** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
676
+ between?: [string, string];
677
+ /** This matches a field equal to any value in the list, which holds at most 65,536 values. */
607
678
  in?: string[];
608
- /** This matches a field equal to none of the values in the list. */
679
+ /** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
609
680
  nin?: string[];
610
681
  /** This matches a field starting with the text. */
611
682
  startsWith?: string;
612
683
  /** This matches a field ending with the text. */
613
684
  endsWith?: string;
685
+ /** This matches a pattern field whose value holds the text anywhere in it. */
686
+ contains?: string;
687
+ /**
688
+ * This matches a pattern field when the whole value matches the wildcard
689
+ * pattern. For example, `INV-*-2024` matches `INV-0042-2024`.
690
+ *
691
+ * In the pattern, `*` matches any sequence of code points, including an
692
+ * empty one, and `?` matches exactly one code point. Write `\` before a code
693
+ * point to match that code point itself, so `\*` matches an asterisk.
694
+ *
695
+ * The engine throws `SEARCH_INVALID_FILTER` for a pattern that ends in a
696
+ * `\` with no code point after it. It throws the same error for a pattern
697
+ * with more than 2,048 positions. Each `*`, each `?`, and each other code
698
+ * point counts as one position, except that under `caseFold` a code point
699
+ * counts once for each code point of its case fold.
700
+ */
701
+ wildcard?: string;
702
+ /**
703
+ * This matches a pattern field when some part of the value matches the
704
+ * regular expression. `^` and `$` match only at the start and at the end of
705
+ * the whole value.
706
+ *
707
+ * The engine accepts literal code points, `.`, `\d`, `\w`, and `\s`, sets
708
+ * such as `[a-z]` and `[^0-9]`, groups, and `|`. It also accepts the repeats
709
+ * `*`, `+`, `?`, `{n}`, `{n,}`, and `{n,m}`, the anchors `^` and `$`, the
710
+ * word edge `\b`, and number ranges such as `<1-65535>`. A number range
711
+ * matches the digits of any whole number from its low end to its high end.
712
+ * Write `\` before an ASCII punctuation mark to match the mark itself. The
713
+ * `.` matches any code point, including a line break.
714
+ *
715
+ * The matcher never backtracks, so it checks a value in at most as many
716
+ * steps as the value's code points multiplied by the pattern's positions.
717
+ *
718
+ * The engine throws `SEARCH_INVALID_FILTER` for any construct outside that
719
+ * syntax, such as a back-reference, a lookaround, a lazy repeat, or an inline
720
+ * flag. It throws the same error when the groups of a pattern nest more than
721
+ * 32 deep, when a count is above 2,048, and when a pattern holds more than
722
+ * 2,048 positions. When the operator of an HTTP server sets its `allowRegex`
723
+ * option to false, the server refuses every `regex` test.
724
+ */
725
+ regex?: string;
726
+ /**
727
+ * When this is true, the engine compares the case fold of each value of a
728
+ * pattern field with the case fold of the text, so a test for `error`
729
+ * matches `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`,
730
+ * `endsWith`, `contains`, `wildcard`, and `regex`.
731
+ *
732
+ * Under `caseFold`, a set that does not open with `^` can also match a
733
+ * sequence of code points. When a member that the set holds on its own folds
734
+ * to several code points, the set matches that whole fold, so `[ß]` matches
735
+ * `ss`.
736
+ */
737
+ caseFold?: boolean;
738
+ /**
739
+ * This lets the `eq` test of a pattern field match a value within this many
740
+ * edits of the text, so a test for `INV-2O24` with a tolerance of 1 matches
741
+ * `INV-2024`. An edit inserts, deletes, or replaces one code point, so a
742
+ * swap of two neighbouring code points counts as two edits. With `caseFold`,
743
+ * the engine counts the edits between the case folds of the value and the
744
+ * text. The tolerance applies to `eq` alone, so the other tests of the field
745
+ * still compare exactly.
746
+ *
747
+ * The engine takes its candidates from the pattern index, so the case fold
748
+ * of the text has to hold enough distinct runs of three code points. For a
749
+ * tolerance of `k`, the engine needs `k × (2 + f) + 1` runs, where `f` is
750
+ * the number of code points in the longest case fold among the text's code
751
+ * points, which is 1 for most text. A tolerance of 1 on `INV-2O24`
752
+ * therefore needs 4 of its 6 runs, while a tolerance of 2 needs 7. Under
753
+ * `'auto'`, the engine uses 2 where the text holds enough runs for 2,
754
+ * otherwise 1 where it holds enough for 1, and otherwise 0.
755
+ *
756
+ * The engine throws `SEARCH_INVALID_FILTER` for a tolerance of 1 or 2 on a
757
+ * text with too few runs, stating how many runs that tolerance needs. It
758
+ * throws the same error for any other tolerance, for a tolerance on a field
759
+ * that is not a pattern field, and for a tolerance in a filter without an
760
+ * `eq` test. Towards the pattern work cap, it counts one unit for each cell
761
+ * that it fills in the table of edit distances between the text and a
762
+ * value.
763
+ */
764
+ tolerance?: 0 | 1 | 2 | 'auto';
614
765
  };
615
766
  /**
616
- * Tests the contents of an array field.
767
+ * Tests the contents of a list field, which is a `number[]`, `boolean[]`,
768
+ * `enum[]`, `verbatim[]`, or `string[]` field.
769
+ *
770
+ * The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
771
+ * field, for a value whose type differs from the type of the list's elements,
772
+ * and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
773
+ * out `pattern`.
617
774
  *
618
775
  * @public
619
776
  */
620
777
  type ArrayFilter = {
621
- /** This matches an array holding every one of the values. */
778
+ /** This matches a list holding every one of the values, at most 65,536 of them, so an empty set of values matches every list. */
622
779
  containsAll?: (string | number | boolean)[];
623
- /** This matches an array holding at least one of the values. */
780
+ /** This matches a list holding at least one of the values, at most 65,536 of them. */
624
781
  matchesAny?: (string | number | boolean)[];
625
- /** This compares the array's length. */
782
+ /** This compares the number of elements in the list. */
626
783
  size?: ComparisonFilter;
627
784
  };
628
785
  /**
@@ -632,13 +789,13 @@ type ArrayFilter = {
632
789
  * @public
633
790
  */
634
791
  type PresenceFilter = {
635
- /** This matches a document where the field is present. */
792
+ /** This matches a document where the field holds a value other than null. */
636
793
  exists?: boolean;
637
- /** This matches a document where the field is absent. */
794
+ /** This matches a document where the field is absent or null. */
638
795
  notExists?: boolean;
639
- /** This matches an empty string or an empty array. */
796
+ /** This matches a document where the field is absent, null, an empty string, or an empty list. */
640
797
  isEmpty?: boolean;
641
- /** This matches a string or array holding something. */
798
+ /** This matches a document where the field holds a value other than an empty string or an empty list. */
642
799
  isNotEmpty?: boolean;
643
800
  };
644
801
  /**
@@ -649,9 +806,9 @@ type PresenceFilter = {
649
806
  type GeoRadiusFilter = {
650
807
  /** The engine tests the field against this circle. */
651
808
  radius: {
652
- /** The centre has this latitude, in degrees. */
809
+ /** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
653
810
  lat: number;
654
- /** The centre has this longitude, in degrees. */
811
+ /** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
655
812
  lon: number;
656
813
  /** The circle has this radius, measured in `unit`. */
657
814
  distance: number;
@@ -684,9 +841,11 @@ type GeoPolygonFilter = {
684
841
  /**
685
842
  * The engine closes the ring through these corners in the order that you
686
843
  * list them, so you can leave the first point off the end. It throws
687
- * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, since
688
- * such a ring encloses no area. List the corners counter-clockwise around
689
- * the area, as in an exterior ring of GeoJSON. Where the corners
844
+ * `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
845
+ * encloses no area, and for a corner whose latitude is outside -90 to 90
846
+ * or whose longitude is outside -180 to 180. It also throws that error for
847
+ * a ring of more than 65,536 corners. List the corners counter-clockwise
848
+ * around the area, as in an exterior ring of GeoJSON. Where the corners
690
849
  * span 180 degrees of longitude or more, the engine matches the area on
691
850
  * the left of that path, so a ring listed that way can cross the
692
851
  * antimeridian or span more than half the globe.
@@ -713,11 +872,15 @@ type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
713
872
  */
714
873
  type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
715
874
  /**
716
- * The filter a query runs, built from per-field tests and the boolean
875
+ * The filter that a query runs, built from per-field tests and the boolean
717
876
  * operators that combine them.
718
877
  *
719
- * Nest the operators to whatever depth the query needs. The engine applies the
720
- * filter before scoring, so a narrow filter makes a search cheaper.
878
+ * The engine answers every test from an index that it keeps for the field. It
879
+ * applies the filter before scoring, so a narrow filter makes a search
880
+ * cheaper. A filter nests at most 30 levels deep and holds at most 1,024
881
+ * tests, counted across every field and nested expression. Past either limit,
882
+ * the engine throws `SEARCH_INVALID_FILTER`, while it throws
883
+ * `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
721
884
  *
722
885
  * @public
723
886
  */
@@ -732,6 +895,157 @@ type FilterExpression = {
732
895
  not?: FilterExpression;
733
896
  };
734
897
 
898
+ /**
899
+ * How a query reorders its top hits with a rerank adapter.
900
+ *
901
+ * The engine ranks the query as it would without this setting, passes the
902
+ * top `window` hits to the adapter, and orders them by the adapter's scores.
903
+ * The hits past the window follow in their first ranking, with their scores
904
+ * scaled below the lowest reranked score, so every page of one query comes
905
+ * from the same order.
906
+ *
907
+ * @public
908
+ */
909
+ interface RerankConfig {
910
+ /**
911
+ * The engine scores the hits with the rerank adapter registered under this
912
+ * key. It throws `RERANK_CONFIG_INVALID` for a key that it has not
913
+ * registered.
914
+ */
915
+ adapter: string;
916
+ /**
917
+ * The engine sends the adapter the values of these text fields, in this
918
+ * order and joined with newlines, as the text of each hit. Each member of a
919
+ * list field takes a line of its own. The engine throws
920
+ * `RERANK_CONFIG_INVALID` for an empty list, for a field that the schema
921
+ * does not declare as text, and for a field that the list gives twice.
922
+ */
923
+ fields: string[];
924
+ /**
925
+ * The adapter compares each hit with this text. Where you leave it out, the
926
+ * engine sends the query's `term`, or else its `vector.text`, and it throws
927
+ * `RERANK_CONFIG_INVALID` where the query carries neither.
928
+ */
929
+ query?: string;
930
+ /**
931
+ * The engine reranks this many of the top hits, from 1 to the engine's
932
+ * `maxRerankWindow`. Where you leave the window out, the engine reranks the
933
+ * smallest of 100 and `maxRerankWindow`, and no more than the `hybrid.depth`
934
+ * of a hybrid query that sets one. A hybrid query that sets `hybrid.depth`
935
+ * reranks its fused list at that depth, so the engine throws
936
+ * `RERANK_CONFIG_INVALID` when you set a window above that depth.
937
+ */
938
+ window?: number;
939
+ }
940
+
941
+ /**
942
+ * Vector-search inputs passed under `QueryParams.vector`.
943
+ *
944
+ * Supply either a raw `value` array or a `text` string for auto-embedding;
945
+ * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
946
+ * by the outer query's `limit`, not by any field on this object.
947
+ *
948
+ * @public
949
+ */
950
+ interface VectorQueryConfig {
951
+ /**
952
+ * Name of the schema field that holds the vector to compare against.
953
+ * Must reference a field declared as `vector[N]` in the index schema.
954
+ */
955
+ field: string;
956
+ /**
957
+ * Raw query vector, given as a number array or a `Float32Array`. Length
958
+ * must match the indexed field's dimension or the search rejects the
959
+ * request with `VECTOR_DIMENSION_MISMATCH`.
960
+ */
961
+ value?: number[] | Float32Array;
962
+ /**
963
+ * Text to embed at query time using the index or instance embedding
964
+ * adapter. Mutually exclusive with `value`; requires a configured adapter.
965
+ */
966
+ text?: string;
967
+ /**
968
+ * Score floor applied during ranking. Hits scoring below this value
969
+ * are dropped before `limit` is enforced, so the returned hit count
970
+ * can be smaller than `limit` even when more documents exist. The
971
+ * floor is interpreted in score space for every metric; for
972
+ * `euclidean`, distance is mapped to a similarity score of
973
+ * `1 / (1 + distance)` first. Defaults to no floor.
974
+ */
975
+ similarity?: number;
976
+ /**
977
+ * Similarity metric used for ranking. Defaults to `cosine`. Choose
978
+ * `dotProduct` for raw inner-product scoring on already-normalised
979
+ * vectors and `euclidean` for distance-based ordering.
980
+ */
981
+ metric?: 'cosine' | 'dotProduct' | 'euclidean';
982
+ /**
983
+ * The engine keeps this many candidates as it walks the HNSW graph, so a
984
+ * higher value can find more of the true neighbours, although each query
985
+ * takes longer. The engine applies it only once the field holds a graph.
986
+ * The engine fetches k hits, where k is one more than the number of hits up
987
+ * to the end of the page, so k is `limit` plus 1 on a first page. When a
988
+ * query leaves `efSearch` unset, the engine keeps the larger of 50 and k
989
+ * plus a margin, where the margin is 50 below 768 dimensions, 75 from 768
990
+ * to 1,023 dimensions, and 0 at 1,024 dimensions and above. Under a
991
+ * filter, the engine counts only the candidates that pass the filter.
992
+ */
993
+ efSearch?: number;
994
+ /**
995
+ * The engine re-scores this many times k candidates in a quantized field
996
+ * against the full-precision vectors before it returns the best `limit`,
997
+ * where k is one more than the number of hits up to the end of the page, so
998
+ * k is `limit` plus 1 on a first page. For a value below 1, or for a value
999
+ * that is not a finite number, the engine throws a `NarsilError` with code
1000
+ * `CONFIG_INVALID`. The engine ignores it on a field whose quantization is
1001
+ * `none`. When a query leaves it unset, the engine sets the number of
1002
+ * candidates that it re-scores from k and from the field's dimension. It
1003
+ * rounds that number up, and it re-scores at least 3k candidates under
1004
+ * `osq1` and `osq2`, and at least k under `osq4` and `osq8`. Below 768
1005
+ * dimensions, it re-scores 3.23k + 55.9√k under `osq1` and 2.6k + 22.5√k under
1006
+ * `osq2`. From 768 to 1,023 dimensions, it re-scores 2.2k + 27√k under
1007
+ * `osq1` and k + 16√k under `osq2`. At 1,024 dimensions and above, it
1008
+ * re-scores 3k under both. Under `osq4`, it re-scores 5k below 1,024
1009
+ * dimensions and 2k from 1,024 dimensions, while under `osq8` it re-scores
1010
+ * 2k at every dimension. Under a filter, the engine counts only the
1011
+ * candidates that pass the filter. On vectors spread evenly across every
1012
+ * dimension, a one-bit or two-bit code can find fewer than 95% of the true
1013
+ * nearest neighbours at these defaults, so raise `oversample` on a query that
1014
+ * needs more of them.
1015
+ */
1016
+ oversample?: number;
1017
+ }
1018
+ /**
1019
+ * How a hybrid query merges its keyword ranking with its vector ranking.
1020
+ *
1021
+ * `rrf` combines the two by rank alone, which needs no tuning and handles
1022
+ * scores that live on different scales. `linear` blends the scores directly,
1023
+ * which gives you control once you know what each side's scores look like.
1024
+ *
1025
+ * @public
1026
+ */
1027
+ interface HybridConfig {
1028
+ /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
1029
+ strategy?: 'rrf' | 'linear';
1030
+ /** The engine uses this rank-fusion constant under `rrf` alone, where a larger value reduces the lead of the top ranks. Set a whole number of at least 1, or leave it out for 60. The engine throws `CONFIG_INVALID` for any other value. */
1031
+ k?: number;
1032
+ /** The engine uses this weight of the vector score, from 0 to 1, under `linear` alone, and 0.5 where you leave it out. It throws `CONFIG_INVALID` for a value outside that range. */
1033
+ alpha?: number;
1034
+ /**
1035
+ * Set a depth to get the same fused order on every page of one query, and
1036
+ * a cursor that resumes it. The engine then fetches this many results from
1037
+ * the keyword search and from the vector search, fuses them, and pages
1038
+ * through the top `depth` of the fused list. The last page stops at this
1039
+ * depth, so it can hold fewer hits than the limit. Set a whole number from 1
1040
+ * to 10,000. The engine throws `CONFIG_INVALID` for any other value, and
1041
+ * `SEARCH_RESULT_WINDOW_EXCEEDED` for a page that starts at this depth or
1042
+ * beyond. Where you leave the depth out, each search fetches only enough
1043
+ * results to fill the page, so the fused order can change from one page to
1044
+ * the next, and a cluster refuses a cursor with `SEARCH_INVALID_CURSOR`.
1045
+ */
1046
+ depth?: number;
1047
+ }
1048
+
735
1049
  /**
736
1050
  * Everything {@link Narsil.suggest} accepts.
737
1051
  *
@@ -868,26 +1182,65 @@ interface QueryParams {
868
1182
  * query can reject every hit in another.
869
1183
  */
870
1184
  minScore?: number;
871
- /** The engine keeps a document only where it matches this many query terms, and one term is enough by default. */
1185
+ /**
1186
+ * The engine keeps a document only where the document matches this many
1187
+ * query terms, under the same `tolerance` and `prefixLength` that the search
1188
+ * uses. One term is enough by default.
1189
+ */
872
1190
  termMatch?: TermMatchPolicy;
873
- /** The engine matches an indexed term within this edit distance of a query term, so a query with a typo still finds its document. */
1191
+ /**
1192
+ * The engine matches an indexed term within this edit distance of a query
1193
+ * term, so it finds a document for a query with a typo. It counts each
1194
+ * Unicode code point as one character. Set an integer from 0 to 10.
1195
+ */
874
1196
  tolerance?: number;
875
- /** The engine applies `tolerance` only to indexed terms that share this many leading characters with the query term, 2 by default. */
1197
+ /**
1198
+ * The engine applies `tolerance` only to the indexed terms that share this
1199
+ * many leading characters with the query term, or to the terms that start
1200
+ * with the whole query term when the query term is shorter. Set an integer
1201
+ * from 0 to 1,024; the default is 2.
1202
+ */
876
1203
  prefixLength?: number;
877
1204
  /**
878
- * Setting this makes the engine treat the last query term as an unfinished
879
- * word, so `secur` matches `security`. The earlier terms must match whole,
880
- * and `tolerance` applies to them alone. The engine scores completions
881
- * against a shared document frequency and ranks them below whole-word
882
- * matches. It ignores this setting where `exact` is true, and the setting
883
- * defaults to false.
1205
+ * With this set, the engine treats the last query term as an unfinished
1206
+ * word, so `secur` matches `security`. The engine matches that last term by
1207
+ * its stem or by completing it, while `tolerance` applies only to the earlier
1208
+ * terms, which have to match whole. The engine scores completions against a
1209
+ * shared document frequency. It also ranks them below whole-word matches.
1210
+ * The engine ignores this setting where `exact` is true, and the setting is
1211
+ * false by default.
884
1212
  */
885
1213
  prefix?: boolean;
886
1214
  /**
887
- * Setting this makes the engine match each query term only against an equal
888
- * indexed term, which turns off fuzzy matching and prefix completion. The
889
- * engine still stems the query, because the index stores stemmed terms, so
890
- * `running` matches a document that holds `runs` through their shared stem.
1215
+ * With this set, the engine also matches each query word of three or more
1216
+ * characters inside the longer words of every field whose type includes
1217
+ * `partial`, so a search for `proof` matches a document with `waterproof`
1218
+ * in such a field. The engine counts each Unicode code point as one
1219
+ * character. It looks for the query word, before stemming, inside each word
1220
+ * exactly as that word appears in a document.
1221
+ *
1222
+ * The engine adds at most 50 such words to a query, which it divides as
1223
+ * evenly as it can among the query words. Within the share of each query
1224
+ * word, it adds first the words that the most documents contain. It scores
1225
+ * a match inside a longer word in proportion to the part of that word that
1226
+ * the query word makes up, so it scores such a match below a whole-word
1227
+ * match at the same frequency in a field of the same length. With
1228
+ * `highlight`, it tags each whole word that contains a query word in a
1229
+ * searched `partial` field.
1230
+ *
1231
+ * The engine applies no `tolerance` to these matches. It ignores this
1232
+ * setting where `exact` is true or where the searched fields include no
1233
+ * `partial` field. Where the setting is absent, the engine treats it as
1234
+ * false, while it throws `CONFIG_INVALID` for any value other than `true`
1235
+ * or `false`.
1236
+ */
1237
+ partialWords?: boolean;
1238
+ /**
1239
+ * With this set, the engine matches each query term only against an equal
1240
+ * indexed term, so it turns off fuzzy matching, prefix completion,
1241
+ * partial-word matching, and synonyms. The engine still stems the query, because the
1242
+ * index stores stemmed terms, so a search for `running` matches a document
1243
+ * that contains `runs` through the stem that both words share.
891
1244
  */
892
1245
  exact?: boolean;
893
1246
  /**
@@ -901,15 +1254,16 @@ interface QueryParams {
901
1254
  /**
902
1255
  * The engine sorts the hits by the values of these fields, in place of the
903
1256
  * relevance ranking. Pass an object keyed by field, or a list of fields in
904
- * the order that the engine compares them. A sort can name a `number`,
905
- * `boolean`, `enum`, or `string:sortable` field, or a list field, which the
906
- * engine reduces to one value by the entry's `mode`. The engine throws
907
- * `SEARCH_INVALID_FIELD` for a sort on a plain `string`, a `geopoint`, or a
908
- * vector field, because ordering a plain string takes far more memory per
909
- * document than ordering a number, while the other two types have no order.
910
- * The engine orders hybrid results by fusion, so it throws
911
- * `SEARCH_INVALID_MODE` for a hybrid query that sets a sort, and it throws
912
- * the same code for a direction other than `asc` and `desc`.
1257
+ * the order that the engine compares them. The engine sorts by a `number`,
1258
+ * `boolean`, or `enum` field, by a text field whose type includes
1259
+ * `sortable`, or by a list of any of these, which it reduces to one value by
1260
+ * the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
1261
+ * `geopoint` or a vector field, because neither type has an order. It throws
1262
+ * the same code for a sort on any other text field, since the engine keeps
1263
+ * up to the first 512 code points of every document's value in memory to
1264
+ * sort by a text field. The engine orders hybrid results by fusion, so it
1265
+ * throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
1266
+ * that code for a direction other than `asc` and `desc`.
913
1267
  */
914
1268
  sort?: SortSpec;
915
1269
  /** These settings collapse the hits into groups by field value. */
@@ -938,6 +1292,16 @@ interface QueryParams {
938
1292
  vector?: VectorQueryConfig;
939
1293
  /** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
940
1294
  hybrid?: HybridConfig;
1295
+ /**
1296
+ * These settings reorder the top hits with a rerank adapter, such as a
1297
+ * cross-encoder, after the keyword, vector, or hybrid ranking. The count
1298
+ * matches the count of the same query without `rerank`, while the facets
1299
+ * and the groups come from the first ranking. The engine throws
1300
+ * `SEARCH_INVALID_MODE` for a query that also sets a sort, and
1301
+ * `RERANK_FAILED` where the adapter fails or outlasts the engine's
1302
+ * `rerankTimeout`.
1303
+ */
1304
+ rerank?: RerankConfig;
941
1305
  /**
942
1306
  * Setting this returns relevance scores on a sorted query. A query that
943
1307
  * names a sort ranks by sort values alone and computes no scores, so its
@@ -972,82 +1336,6 @@ type DocumentProjection = boolean | {
972
1336
  /** Names the fields to drop, so every other field is kept. */
973
1337
  exclude?: string[];
974
1338
  };
975
- /**
976
- * Vector-search inputs passed under `QueryParams.vector`.
977
- *
978
- * Supply either a raw `value` array or a `text` string for auto-embedding;
979
- * passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
980
- * by the outer query's `limit`, not by any field on this object.
981
- *
982
- * @public
983
- */
984
- interface VectorQueryConfig {
985
- /**
986
- * Name of the schema field that holds the vector to compare against.
987
- * Must reference a field declared as `vector[N]` in the index schema.
988
- */
989
- field: string;
990
- /**
991
- * Raw query vector, given as a number array or a `Float32Array`. Length
992
- * must match the indexed field's dimension or the search rejects the
993
- * request with `VECTOR_DIMENSION_MISMATCH`.
994
- */
995
- value?: number[] | Float32Array;
996
- /**
997
- * Text to embed at query time using the index or instance embedding
998
- * adapter. Mutually exclusive with `value`; requires a configured adapter.
999
- */
1000
- text?: string;
1001
- /**
1002
- * Score floor applied during ranking. Hits scoring below this value
1003
- * are dropped before `limit` is enforced, so the returned hit count
1004
- * can be smaller than `limit` even when more documents exist. The
1005
- * floor is interpreted in score space for every metric; for
1006
- * `euclidean`, distance is mapped to a similarity score of
1007
- * `1 / (1 + distance)` first. Defaults to no floor.
1008
- */
1009
- similarity?: number;
1010
- /**
1011
- * Similarity metric used for ranking. Defaults to `cosine`. Choose
1012
- * `dotProduct` for raw inner-product scoring on already-normalised
1013
- * vectors and `euclidean` for distance-based ordering.
1014
- */
1015
- metric?: 'cosine' | 'dotProduct' | 'euclidean';
1016
- /**
1017
- * HNSW exploration factor for approximate search. Higher values raise
1018
- * recall at the cost of latency. Ignored while the field is still
1019
- * served by the brute-force backend. Defaults to the engine's built-in
1020
- * value when omitted.
1021
- */
1022
- efSearch?: number;
1023
- /**
1024
- * How many times `limit` a quantized field re-scores against its
1025
- * full-precision vectors before it returns the best `limit`. A value below
1026
- * 1 or one that is not a finite number fails with `CONFIG_INVALID`. The
1027
- * engine ignores this on a field whose quantization is `none`. When a query
1028
- * omits it, the engine takes 3 for `osq1` and `osq2`, 2 for `osq8`, and 2
1029
- * for `osq4` at 1,024 dimensions and above, but 5 for `osq4` below 1,024,
1030
- * where a four-bit code ranks the true neighbours less reliably.
1031
- */
1032
- oversample?: number;
1033
- }
1034
- /**
1035
- * How a hybrid query merges its keyword ranking with its vector ranking.
1036
- *
1037
- * `rrf` combines the two by rank alone, which needs no tuning and handles
1038
- * scores that live on different scales. `linear` blends the scores directly,
1039
- * which gives you control once you know what each side's scores look like.
1040
- *
1041
- * @public
1042
- */
1043
- interface HybridConfig {
1044
- /** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
1045
- strategy?: 'rrf' | 'linear';
1046
- /** The engine uses this rank-fusion constant under `rrf` alone, where a larger value reduces the lead of the top ranks. Set a whole number of at least 1, or leave it out for 60. The engine throws `CONFIG_INVALID` for any other value. */
1047
- k?: number;
1048
- /** The engine uses this weight of the vector score, from 0 to 1, under `linear` alone, and 0.5 where you leave it out. It throws `CONFIG_INVALID` for a value outside that range. */
1049
- alpha?: number;
1050
- }
1051
1339
  /**
1052
1340
  * Fields a query counts values for, keyed by field name.
1053
1341
  *
@@ -1106,15 +1394,15 @@ type GroupReducer = {
1106
1394
  initialValue: () => unknown;
1107
1395
  };
1108
1396
  /**
1109
- * Which fields a query returns highlighted snippets for, and how those
1110
- * snippets are marked up.
1397
+ * This configuration names the fields that receive highlighted snippets. It
1398
+ * also sets how the engine marks those snippets up.
1111
1399
  *
1112
- * The engine analyses the text of each returned field again and marks every
1113
- * word that the query matches. That covers a word whose stem equals a query
1114
- * stem, a word within the query's `tolerance` of a query stem, and, for a
1115
- * `prefix` query, a word that completes the last query term. The engine
1116
- * therefore marks the same words whatever the index's `trackPositions`
1117
- * setting is.
1400
+ * The engine analyses the text of each returned field again to tag every word
1401
+ * that it matched, so it tags the same words whatever the index's
1402
+ * `trackPositions` setting is. It tags a word whose stem equals a query stem,
1403
+ * and a word within the query's `tolerance` of a query stem. For a `prefix`
1404
+ * query, it tags a word for the last query term only when that word completes
1405
+ * the term or shares its stem.
1118
1406
  *
1119
1407
  * @public
1120
1408
  */
@@ -1173,6 +1461,26 @@ interface WorkerCopyReport {
1173
1461
  /** The index has loaded its copies again this many times after an idle spell dropped them. */
1174
1462
  reloadCount: number;
1175
1463
  }
1464
+ /**
1465
+ * An index whose checkpoints wait until a failed partition recovers, as
1466
+ * {@link Narsil.getMemoryStats} reports it. The engine holds these
1467
+ * checkpoints only for an index with a vector field, because each vector file
1468
+ * mixes every partition's vectors, so a checkpoint would save the failed
1469
+ * partition's vectors from memory. The write-ahead log of the index grows
1470
+ * until the partition recovers or you restore the index from a snapshot.
1471
+ *
1472
+ * @public
1473
+ */
1474
+ interface HeldCheckpointReport {
1475
+ /** This is the index whose checkpoints wait. */
1476
+ indexName: string;
1477
+ /** These are the partitions of that index whose copy failed. */
1478
+ partitionIds: number[];
1479
+ /** This many write-ahead log records of the index wait for a checkpoint. */
1480
+ recordsSinceCheckpoint: number;
1481
+ /** The documents in those records hold about this many bytes. */
1482
+ documentBytesSinceCheckpoint: number;
1483
+ }
1176
1484
  /**
1177
1485
  * What {@link Narsil.getMemoryStats} returns, which is what you size a host
1178
1486
  * from.
@@ -1202,6 +1510,8 @@ interface MemoryStats {
1202
1510
  reopenCount: number;
1203
1511
  /** One entry per index, saying whether it holds worker copies now and how many times it has reloaded them. */
1204
1512
  workerCopies: WorkerCopyReport[];
1513
+ /** One entry per index whose checkpoints wait until a failed partition recovers. */
1514
+ heldCheckpoints: HeldCheckpointReport[];
1205
1515
  /**
1206
1516
  * Per-worker V8 heap usage once the engine has started its worker pool.
1207
1517
  * Empty while no worker is running.
@@ -1220,4 +1530,203 @@ interface MemoryStats {
1220
1530
  }>;
1221
1531
  }
1222
1532
 
1223
- export { type ArrayFilter as A, type BatchResult as B, type ClientErrorCode as C, type DocumentProjection as D, type ErrorCode as E, type FacetConfig as F, type GeoFilter as G, type HighlightConfig as H, type IndexInfo as I, type QueryCoverage as J, type ScoreComponents as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type SearchMode as O, type PartitionStatsResult as P, type QueryParams as Q, type SortField as R, type ServerErrorCode as S, type SortSpec as T, type StringFilter as U, type VectorMaintenanceResult as V, type TermMatchPolicy as W, type VectorQueryConfig as X, type WorkerCopyReport as Y, ClientErrorCodes as a, ErrorCodes as b, type NarsilErrorCode as c, ServerErrorCodes as d, type QueryResult as e, type IndexStats as f, type ListResult as g, type PreflightResult as h, isNarsilError as i, type SuggestParams as j, type SuggestResult as k, type ComparisonFilter as l, type FacetResult as m, type FieldFilter as n, type FilterExpression as o, type GeoPolygonFilter as p, type GeoRadiusFilter as q, type GroupConfig as r, type GroupReducer as s, type GroupResult as t, type HighlightMatch as u, type Hit as v, type HybridConfig as w, type ListedDocument as x, type PresenceFilter as y, type ProcessMemoryReport as z };
1533
+ /**
1534
+ * This map lists every event that the engine emits, with the payload of each
1535
+ * one.
1536
+ *
1537
+ * {@link Narsil.on} registers a listener under a key from this map, so that the
1538
+ * engine can pass the matching payload to that listener. Most of these events
1539
+ * report work that the engine does in the background, away from the call that
1540
+ * started it, so a failure that such an event reports never rejects a promise
1541
+ * that you are holding.
1542
+ *
1543
+ * @public
1544
+ */
1545
+ type NarsilEventMap = {
1546
+ /**
1547
+ * The engine emits this event after a call changes what a read returns from
1548
+ * an index. The calls are the inserts, updates, and removals, singly or in a
1549
+ * batch, together with `clear`, `restore`, `rebalance`, `rebuildAnalysis`,
1550
+ * `compactVectors`, `optimizeVectors`, `createIndex`, and `dropIndex`. The
1551
+ * engine emits the event after a call that throws as well, because a call can
1552
+ * change the index before it throws. It also emits the event after it reloads
1553
+ * an index, once a shared invalidation adapter reports that another instance
1554
+ * saved that index. The engine emits one event per batch, however many
1555
+ * documents the batch holds.
1556
+ *
1557
+ * The engine emits the event once a query can see the change, which means
1558
+ * after every worker copy applies the change and after any rebalance in
1559
+ * progress replays it. A query that a listener sends from its handler
1560
+ * therefore returns results that include the change. The engine waits for the
1561
+ * change to become visible only while a listener is registered for the event.
1562
+ */
1563
+ write: {
1564
+ /** This is the name of the index that changed. */
1565
+ indexName: string;
1566
+ };
1567
+ /**
1568
+ * A worker thread exited unexpectedly. The pool removes the thread and fails
1569
+ * the requests that the thread was serving with `WORKER_CRASHED`. The engine
1570
+ * then sends each of those queries again on the main thread, so the caller
1571
+ * receives a result with no error. The remaining workers keep serving
1572
+ * queries, because each of them holds a full worker copy of every promoted
1573
+ * index.
1574
+ *
1575
+ * After a delay, the engine spawns a replacement and loads every copy onto
1576
+ * it before it sends queries to the replacement. Once no worker is left, the
1577
+ * main thread serves every query, because it holds every document. The first
1578
+ * request after the delay then starts a new pool. The delay starts at one
1579
+ * second and doubles up to a minute while replacements keep failing.
1580
+ */
1581
+ workerCrash: {
1582
+ /** This is the id of the worker that exited. */
1583
+ workerId: number;
1584
+ /** These are the indexes that the worker held. */
1585
+ indexNames: string[];
1586
+ /** This is the error that ended the worker. */
1587
+ error: Error;
1588
+ };
1589
+ /** An index gained worker copies, either because it reached the copy
1590
+ * threshold or because a request loaded its copies again after an idle
1591
+ * spell. */
1592
+ workerPromote: {
1593
+ /** This is the number of workers in the pool. */
1594
+ workerCount: number;
1595
+ /** This is the reason that the index gained its copies, such as the copy
1596
+ * threshold that it reached. */
1597
+ reason: string;
1598
+ };
1599
+ /** An index could not gain worker copies, so the main thread keeps serving
1600
+ * its queries. */
1601
+ workerPromoteFailure: {
1602
+ /** This is the reason that the engine tried to load the copies. */
1603
+ reason: string;
1604
+ /** This is the error that stopped the load. */
1605
+ error: Error;
1606
+ /** This is true when the engine will try again at a later threshold. */
1607
+ retryable: boolean;
1608
+ };
1609
+ /** An index finished spreading its documents across a new number of
1610
+ * partitions. */
1611
+ partitionRebalance: {
1612
+ /** This is the name of the index that the engine rebalanced. */
1613
+ indexName: string;
1614
+ /** This is the number of partitions before the rebalance. */
1615
+ oldCount: number;
1616
+ /** This is the number of partitions after the rebalance. */
1617
+ newCount: number;
1618
+ };
1619
+ /**
1620
+ * An index passed its watermark, so its partitions are close to their
1621
+ * capacity. On a cluster node, the engine reports the document count and the
1622
+ * capacity of the one partition that `partitionId` identifies, which this
1623
+ * node leads.
1624
+ */
1625
+ partitionWatermark: {
1626
+ /** This is the name of the index that crossed the mark. */
1627
+ indexName: string;
1628
+ /** This is the number of documents in the index, or in the partition on a
1629
+ * cluster node. */
1630
+ documentCount: number;
1631
+ /** This is the number of documents that the current partitions of the
1632
+ * index can hold, or that the partition can hold on a cluster node. */
1633
+ capacity: number;
1634
+ /** This is the number of partitions in the index. */
1635
+ partitionCount: number;
1636
+ /** On a cluster node, this is the partition that crossed the mark, while
1637
+ * outside a cluster the field is absent. */
1638
+ partitionId?: number;
1639
+ };
1640
+ /**
1641
+ * The process uses nine tenths of its heap, as measured during a write or a
1642
+ * load, so the next large index can end the process with an out-of-memory
1643
+ * error.
1644
+ *
1645
+ * Where `--max-old-space-size` or `--max-old-space-size-percentage` sets a
1646
+ * limit, on the command line or in `NODE_OPTIONS`, the engine measures the
1647
+ * used bytes against that limit, which `heapLimit` then reports. Where
1648
+ * neither flag sets a limit, the engine measures the share of the heap that
1649
+ * V8 reports as no longer available. V8 reports a limit about 192 MB above
1650
+ * the true ceiling, so a process on a default heap below about 2 GB can end before
1651
+ * this event fires.
1652
+ *
1653
+ * The engine emits the event once per crossing, then arms it again once the
1654
+ * free share of the heap recovers to two tenths. Raise the limit with
1655
+ * `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
1656
+ * idle index; see {@link ProcessMemoryReport.heapLimit}.
1657
+ */
1658
+ heapPressure: {
1659
+ /** This is the index that a write or a load was touching when the heap
1660
+ * reached that point. */
1661
+ indexName: string;
1662
+ /** This is the heap that the process uses, in bytes. */
1663
+ heapUsed: number;
1664
+ /** This is the size in bytes that the heap can grow to. */
1665
+ heapLimit: number;
1666
+ /** This is the estimate of the bytes that the index holds. */
1667
+ estimatedMemoryBytes: number;
1668
+ };
1669
+ /** The engine started, completed, or failed a rebuild that brings the terms
1670
+ * of an index up to the current analysis of its language module. */
1671
+ analysisRebuild: {
1672
+ /** This is the name of the index under rebuild. */
1673
+ indexName: string;
1674
+ /** This is the stage that the rebuild has reached. */
1675
+ status: 'started' | 'completed' | 'failed';
1676
+ /** This is the number of partitions that the rebuild has covered so far. */
1677
+ partitionsRebuilt: number;
1678
+ /** This is the number of partitions that the rebuild covers in total. */
1679
+ partitionCount: number;
1680
+ /** This is the error that stopped the rebuild, which only a `failed`
1681
+ * status includes. */
1682
+ error?: Error;
1683
+ };
1684
+ /** The engine started, completed, or failed the rewrite of an index that you
1685
+ * saved with an earlier release. The engine rewrites the index as it
1686
+ * recovers it, before it serves the index's first request. Because the
1687
+ * engine writes the new manifest last, the earlier files stay intact through
1688
+ * a failed rewrite. The engine then starts the rewrite again the next time
1689
+ * it recovers the index. Without index lifecycle settings, the engine
1690
+ * recovers every index before {@link createNarsil} returns, so pass the
1691
+ * listener in the `events` setting of {@link createNarsil}. */
1692
+ layoutUpgrade: {
1693
+ /** This is the name of the index under rewrite. */
1694
+ indexName: string;
1695
+ /** This is the stage that the rewrite has reached. */
1696
+ status: 'started' | 'completed' | 'failed';
1697
+ /** This is `manifest` where the earlier index is a segment manifest with
1698
+ * its files, and `bundle` where it is a single snapshot bundle. */
1699
+ layout: 'manifest' | 'bundle';
1700
+ /** This is the error that stopped the rewrite, which only a `failed`
1701
+ * status includes. */
1702
+ error?: Error;
1703
+ };
1704
+ /** The engine stopped taking checkpoints of an index with a vector field,
1705
+ * because one of its partitions failed and each vector file mixes every
1706
+ * partition's vectors. The write-ahead log of the index grows until the
1707
+ * partition recovers; {@link MemoryStats.heldCheckpoints} reports how far. */
1708
+ checkpointHeld: HeldCheckpointReport;
1709
+ /** A write to the write-ahead log or a checkpoint failed, so the writes since
1710
+ * the last checkpoint are at risk. */
1711
+ durabilityError: {
1712
+ /** This is the error that the durability layer threw. */
1713
+ error: Error;
1714
+ };
1715
+ /** The invalidation channel failed, so this instance can serve partitions
1716
+ * that another instance has since changed. */
1717
+ invalidationError: {
1718
+ /** This is the error that the adapter threw. */
1719
+ error: Error;
1720
+ };
1721
+ };
1722
+ /**
1723
+ * This map holds a listener for any event of {@link NarsilEventMap}, so that
1724
+ * the engine can register each listener before it starts.
1725
+ *
1726
+ * @public
1727
+ */
1728
+ type NarsilEventHandlers = {
1729
+ [K in keyof NarsilEventMap]?: (payload: NarsilEventMap[K]) => void;
1730
+ };
1731
+
1732
+ export { type TermMatchPolicy as $, type ArrayFilter as A, type BatchResult as B, type ClientErrorCode as C, type DocumentImportResult as D, type ErrorCode as E, type FacetConfig as F, type GeoFilter as G, type HeldCheckpointReport as H, type IndexInfo as I, type HybridConfig as J, type ListedDocument as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type PresenceFilter as O, type PreflightResult as P, type QueryParams as Q, type ProcessMemoryReport as R, type ServerErrorCode as S, type QueryCoverage as T, type RerankConfig as U, type VectorMaintenanceResult as V, type ScoreComponents as W, type SearchMode as X, type SortField as Y, type SortSpec as Z, type StringFilter as _, ClientErrorCodes as a, type VectorQueryConfig as a0, type WorkerCopyReport as a1, ErrorCodes as b, type NarsilErrorCode as c, ServerErrorCodes as d, type QueryResult as e, type NarsilEventHandlers as f, type ListResult as g, type SuggestParams as h, isNarsilError as i, type SuggestResult as j, type IndexStats as k, type PartitionStatsResult as l, type NarsilEventMap as m, type ComparisonFilter as n, type DocumentProjection as o, type FacetResult as p, type FieldFilter as q, type FilterExpression as r, type GeoPolygonFilter as s, type GeoRadiusFilter as t, type GroupConfig as u, type GroupReducer as v, type GroupResult as w, type HighlightConfig as x, type HighlightMatch as y, type Hit as z };