@delali/narsil 0.3.1-next.99 → 0.4.1-next.211
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/NOTICE +45 -0
- package/README.md +30 -11
- package/dist/adapters/filesystem.d.ts +1 -1
- package/dist/adapters/filesystem.mjs +101 -13
- package/dist/adapters/gcs.d.ts +49 -0
- package/dist/adapters/gcs.mjs +213 -0
- package/dist/adapters/indexeddb.d.ts +1 -1
- package/dist/adapters/indexeddb.mjs +2 -7
- package/dist/adapters/memory.d.ts +1 -1
- package/dist/adapters/memory.mjs +5 -0
- package/dist/adapters/s3.d.ts +53 -0
- package/dist/adapters/s3.mjs +263 -0
- package/dist/{adapters-BQFQ4PRz.d.ts → adapters-pljAqmrC.d.ts} +33 -0
- package/dist/browser/chunk-4E5APHTM.mjs +1459 -0
- package/dist/browser/chunk-NDYADQ4Y.mjs +23426 -0
- package/dist/browser/chunk-QAOVAYAG.mjs +564 -0
- package/dist/browser/chunk-WC2DEXWU.mjs +29 -0
- package/dist/browser/chunk-YINZFPLT.mjs +1239 -0
- package/dist/browser/chunk-YJHGOJAC.mjs +15 -0
- package/dist/browser/{chunk-Z7QH2XHB.mjs → core-leaf-HWAXCEWX.mjs} +3987 -2103
- package/dist/browser/custom-token-results-R5BIX7SL.mjs +59 -0
- package/dist/browser/digest-leaf-64IPRPZD.mjs +151 -0
- package/dist/browser/durability-config-75NSFCQN.mjs +97 -0
- package/dist/browser/embed-GG6PS3EA.mjs +264 -0
- package/dist/browser/geo-index-GNHY4PUB.mjs +1484 -0
- package/dist/browser/gzip-JF3S6PPT.mjs +31 -0
- package/dist/browser/module-ZZTNG5JZ.mjs +5762 -0
- package/dist/browser/msgpack-leaf-44XNWSSY.mjs +302 -0
- package/dist/browser/optional-reads-XMVPG6HG.mjs +3230 -0
- package/dist/browser/optional-writes-76DWMRQH.mjs +3603 -0
- package/dist/browser/phrase-module-6UGFVW5J.mjs +617 -0
- package/dist/browser/resolve-vector-text-XRR2OVHE.mjs +85 -0
- package/dist/browser/restore-queue-SG5O735W.mjs +196 -0
- package/dist/browser/{runtime-NYE5TB6O.mjs → runtime-OMKE7DF4.mjs} +83 -25
- package/dist/browser/segment-codec-leaf-A427QJUX.mjs +554 -0
- package/dist/browser/segment-merge-leaf-7BZ54JPI.mjs +1636 -0
- package/dist/browser/storage-leaf-5UTR5K7J.mjs +19829 -0
- package/dist/browser/store-leaf-3L33V35P.mjs +2070 -0
- package/dist/browser/suggestions-leaf-UBNDVKBD.mjs +1430 -0
- package/dist/browser/worker-copies-JXSGYR5X.mjs +2951 -0
- package/dist/{capabilities-BTTIs96E.d.ts → capabilities-DMte5K9_.d.ts} +162 -18
- package/dist/chunk-2AFZE7Y3.mjs +72 -0
- package/dist/chunk-2CKDCC65.mjs +47 -0
- package/dist/chunk-3ECIRFS5.mjs +61 -0
- package/dist/chunk-44W3CBNG.mjs +7 -0
- package/dist/chunk-4H4RG2FR.mjs +13 -0
- package/dist/chunk-4PY4JYMY.mjs +11 -0
- package/dist/chunk-4ZPVAHWF.mjs +1289 -0
- package/dist/chunk-5EI5CXO6.mjs +197 -0
- package/dist/chunk-5F5MXWS5.mjs +283 -0
- package/dist/{chunk-OHP7QR33.mjs → chunk-5FLRXF73.mjs} +25 -4
- package/dist/chunk-6FOENO4E.mjs +273 -0
- package/dist/chunk-6GHX35ZM.mjs +108 -0
- package/dist/chunk-6MSZ543Y.mjs +32 -0
- package/dist/chunk-6N6HHBCQ.mjs +4596 -0
- package/dist/{chunk-LXPIXDUJ.mjs → chunk-7P5YWDRQ.mjs} +403 -169
- package/dist/{chunk-TGP5M5R7.mjs → chunk-7T4LAYT4.mjs} +1 -1
- package/dist/{chunk-GGSH6KBQ.mjs → chunk-ASZLNVWW.mjs} +23 -3
- package/dist/chunk-AVBPB3MI.mjs +602 -0
- package/dist/{chunk-UCDF35PU.mjs → chunk-AVGUEEQ3.mjs} +494 -245
- package/dist/chunk-BUMREPLU.mjs +15 -0
- package/dist/chunk-BY6NALRK.mjs +31921 -0
- package/dist/chunk-C4ZMXXTL.mjs +92 -0
- package/dist/{chunk-2WYMG3OZ.mjs → chunk-C74KPRR7.mjs} +274 -19
- package/dist/{chunk-RSRVGAIQ.mjs → chunk-D456ZFPQ.mjs} +3 -2
- package/dist/chunk-DXZ6JDWG.mjs +797 -0
- package/dist/chunk-FJXJZUWF.mjs +209 -0
- package/dist/chunk-FS3HPPSC.mjs +212 -0
- package/dist/chunk-FT4KLZXW.mjs +1164 -0
- package/dist/chunk-GR5GMFJJ.mjs +104 -0
- package/dist/chunk-GXCDWLQI.mjs +193 -0
- package/dist/chunk-GXED6R3Q.mjs +271 -0
- package/dist/chunk-HLPRHOSO.mjs +17 -0
- package/dist/chunk-IL5DRCNU.mjs +3041 -0
- package/dist/{chunk-P36MUFEJ.mjs → chunk-JDDXV6UF.mjs} +2 -1
- package/dist/chunk-K5HSUPYS.mjs +11 -0
- package/dist/chunk-KYIRXTCA.mjs +100 -0
- package/dist/chunk-LFXS6OF7.mjs +289 -0
- package/dist/chunk-LNGE7SLY.mjs +151 -0
- package/dist/chunk-M2Z5WVWW.mjs +194 -0
- package/dist/{chunk-45AVKHMJ.mjs → chunk-M3B7SGJB.mjs} +63 -50
- package/dist/chunk-M3OW2XSP.mjs +40 -0
- package/dist/chunk-MFPSQZ6P.mjs +127 -0
- package/dist/chunk-MRCJBWJZ.mjs +1292 -0
- package/dist/chunk-MSIN4NM3.mjs +25 -0
- package/dist/chunk-MW3CJVGP.mjs +219 -0
- package/dist/chunk-MYM6CAVK.mjs +76 -0
- package/dist/chunk-NJJN4FMM.mjs +84 -0
- package/dist/chunk-NM7I3BM7.mjs +59 -0
- package/dist/chunk-OIJ64LGT.mjs +19 -0
- package/dist/{chunk-K7D4ZTSW.mjs → chunk-P4F4UWLC.mjs} +1 -1
- package/dist/chunk-Q2AP2FSN.mjs +15 -0
- package/dist/chunk-R2PJKSNL.mjs +54 -0
- package/dist/{chunk-HXJBSHXF.mjs → chunk-R724DJSG.mjs} +5056 -2619
- package/dist/chunk-S2POFTLN.mjs +10 -0
- package/dist/chunk-S5QMWECL.mjs +7 -0
- package/dist/chunk-SLAC5PAB.mjs +5008 -0
- package/dist/chunk-T4HMSZCX.mjs +5 -0
- package/dist/chunk-TACP6VK6.mjs +111 -0
- package/dist/chunk-TGPKS2UM.mjs +125 -0
- package/dist/chunk-TKKXPKEO.mjs +979 -0
- package/dist/chunk-V6EUBAIT.mjs +19 -0
- package/dist/chunk-XL56L4IR.mjs +228 -0
- package/dist/chunk-XQIAMDAG.mjs +3076 -0
- package/dist/chunk-YTUZ4R22.mjs +1063 -0
- package/dist/{chunk-KV3AZFT3.mjs → chunk-ZKOQR7EA.mjs} +45 -1
- package/dist/chunk-ZPJFGGGI.mjs +638 -0
- package/dist/chunk-ZXX5GZEX.mjs +17 -0
- package/dist/{client-i9eLJrw5.d.ts → client-BKqtl0_V.d.ts} +442 -22
- package/dist/client.d.ts +11 -10
- package/dist/client.mjs +8 -898
- package/dist/config-Bnl7L-0H.d.ts +608 -0
- package/dist/{config-P__Diiy4.d.ts → config-CJ-jfI0a.d.ts} +119 -9
- package/dist/core-leaf-6JVHEVFB.mjs +8 -0
- package/dist/custom-token-results-NXHBVY7U.mjs +59 -0
- package/dist/digest-leaf-KXBGKYHZ.mjs +1 -0
- package/dist/direct-executor-V3WOYU2Y.mjs +17 -0
- package/dist/distribution/coordinator/etcd.d.ts +63 -7
- package/dist/distribution/coordinator/etcd.mjs +725 -81
- package/dist/distribution/coordinator/in-memory.d.ts +3 -3
- package/dist/distribution/coordinator/in-memory.mjs +65 -10
- package/dist/distribution/transport/grpc.d.ts +2 -2
- package/dist/distribution/transport/grpc.mjs +39 -10
- package/dist/distribution/transport/in-memory.d.ts +2 -2
- package/dist/distribution/transport/in-memory.mjs +9 -6
- package/dist/distribution/transport/tcp.d.ts +2 -2
- package/dist/distribution/transport/tcp.mjs +20 -15
- package/dist/distribution.d.ts +267 -56
- package/dist/distribution.mjs +23156 -11362
- package/dist/durability-config-VWS2K24E.mjs +96 -0
- package/dist/embed-4PHHKGBK.mjs +263 -0
- package/dist/embeddings/openai.d.ts +1 -1
- package/dist/embeddings/openai.mjs +2 -2
- package/dist/{memory-CUEDwr-F.d.ts → engine-qjAxJSKk.d.ts} +2254 -1123
- package/dist/geo-index-2ZMMWWSK.mjs +1484 -0
- package/dist/gzip-2UCZW2MM.mjs +31 -0
- package/dist/{index-lcdGLyJH.d.ts → index-B_vmxpgW.d.ts} +260 -102
- package/dist/index.browser.mjs +4 -4
- package/dist/index.d.ts +2133 -57
- package/dist/index.mjs +16 -32
- package/dist/index.react-native.mjs +12 -0
- package/dist/invalidation/broadcast-channel.d.ts +1 -1
- package/dist/invalidation/filesystem.d.ts +1 -1
- package/dist/invalidation/filesystem.mjs +1 -2
- package/dist/invalidation/noop.d.ts +1 -1
- package/dist/languages/albanian.mjs +1 -1
- package/dist/languages/amharic.mjs +1 -1
- package/dist/languages/arabic.mjs +1 -1
- package/dist/languages/armenian.mjs +1 -1
- package/dist/languages/azerbaijani.mjs +1 -1
- package/dist/languages/bambara.mjs +1 -1
- package/dist/languages/basque.mjs +1 -1
- package/dist/languages/belarusian.mjs +1 -1
- package/dist/languages/bengali.mjs +1 -1
- package/dist/languages/bosnian.mjs +1 -1
- package/dist/languages/breton.mjs +1 -1
- package/dist/languages/bulgarian.mjs +1 -1
- package/dist/languages/burmese.mjs +1 -1
- package/dist/languages/catalan.mjs +1 -1
- package/dist/languages/chinese.mjs +1 -1
- package/dist/languages/croatian.mjs +1 -1
- package/dist/languages/czech.mjs +1 -1
- package/dist/languages/dagbani.mjs +1 -1
- package/dist/languages/danish.mjs +1 -1
- package/dist/languages/dutch.mjs +1 -1
- package/dist/languages/english.mjs +1 -1
- package/dist/languages/esperanto.mjs +1 -1
- package/dist/languages/estonian.mjs +1 -1
- package/dist/languages/ewe.mjs +1 -1
- package/dist/languages/faroese.mjs +1 -1
- package/dist/languages/fijian.mjs +1 -1
- package/dist/languages/finnish.mjs +1 -1
- package/dist/languages/french.mjs +1 -1
- package/dist/languages/ga.mjs +1 -1
- package/dist/languages/galician.mjs +1 -1
- package/dist/languages/georgian.mjs +1 -1
- package/dist/languages/german.mjs +1 -1
- package/dist/languages/greek.mjs +1 -1
- package/dist/languages/guarani.mjs +1 -1
- package/dist/languages/gujarati.mjs +1 -1
- package/dist/languages/haitian-creole.mjs +1 -1
- package/dist/languages/hausa.mjs +1 -1
- package/dist/languages/hawaiian.mjs +1 -1
- package/dist/languages/hebrew.mjs +1 -1
- package/dist/languages/hindi.mjs +1 -1
- package/dist/languages/hungarian.mjs +1 -1
- package/dist/languages/icelandic.mjs +1 -1
- package/dist/languages/igbo.mjs +1 -1
- package/dist/languages/indonesian.mjs +1 -1
- package/dist/languages/irish.mjs +1 -1
- package/dist/languages/italian.mjs +1 -1
- package/dist/languages/japanese.mjs +1 -1
- package/dist/languages/kannada.mjs +1 -1
- package/dist/languages/kazakh.mjs +1 -1
- package/dist/languages/khmer.mjs +1 -1
- package/dist/languages/kinyarwanda.mjs +1 -1
- package/dist/languages/kirundi.mjs +1 -1
- package/dist/languages/korean.mjs +1 -1
- package/dist/languages/kurmanji.mjs +1 -1
- package/dist/languages/kyrgyz.mjs +1 -1
- package/dist/languages/lao.mjs +1 -1
- package/dist/languages/latin.mjs +1 -1
- package/dist/languages/latvian.mjs +1 -1
- package/dist/languages/lingala.mjs +1 -1
- package/dist/languages/lithuanian.mjs +1 -1
- package/dist/languages/luxembourgish.mjs +1 -1
- package/dist/languages/macedonian.mjs +1 -1
- package/dist/languages/malagasy.mjs +1 -1
- package/dist/languages/malay.mjs +1 -1
- package/dist/languages/malayalam.mjs +1 -1
- package/dist/languages/maltese.mjs +1 -1
- package/dist/languages/maori.mjs +1 -1
- package/dist/languages/marathi.mjs +1 -1
- package/dist/languages/nepali.mjs +1 -1
- package/dist/languages/norwegian.mjs +1 -1
- package/dist/languages/oromo.mjs +1 -1
- package/dist/languages/persian.mjs +1 -1
- package/dist/languages/polish.mjs +1 -1
- package/dist/languages/portuguese.mjs +1 -1
- package/dist/languages/punjabi.mjs +1 -1
- package/dist/languages/romanian.mjs +1 -1
- package/dist/languages/russian.mjs +1 -1
- package/dist/languages/samoan.mjs +1 -1
- package/dist/languages/sanskrit.mjs +1 -1
- package/dist/languages/scottish-gaelic.mjs +1 -1
- package/dist/languages/serbian.mjs +1 -1
- package/dist/languages/shona.mjs +1 -1
- package/dist/languages/sinhala.mjs +1 -1
- package/dist/languages/slovak.mjs +1 -1
- package/dist/languages/slovenian.mjs +1 -1
- package/dist/languages/sorani.mjs +1 -1
- package/dist/languages/spanish.mjs +1 -1
- package/dist/languages/swahili.mjs +1 -1
- package/dist/languages/swedish.mjs +1 -1
- package/dist/languages/tagalog.mjs +1 -1
- package/dist/languages/tamil.mjs +1 -1
- package/dist/languages/tatar.mjs +1 -1
- package/dist/languages/telugu.mjs +1 -1
- package/dist/languages/thai.mjs +1 -1
- package/dist/languages/tibetan.mjs +1 -1
- package/dist/languages/tigrinya.mjs +1 -1
- package/dist/languages/tongan.mjs +1 -1
- package/dist/languages/turkish.mjs +1 -1
- package/dist/languages/twi.mjs +1 -1
- package/dist/languages/ukrainian.mjs +1 -1
- package/dist/languages/urdu.mjs +1 -1
- package/dist/languages/vietnamese.mjs +1 -1
- package/dist/languages/welsh.mjs +1 -1
- package/dist/languages/wolof.mjs +1 -1
- package/dist/languages/xhosa.mjs +1 -1
- package/dist/languages/yoruba.mjs +1 -1
- package/dist/languages/zulu.mjs +1 -1
- package/dist/long-query-thread-UCRK7MSI.mjs +154 -0
- package/dist/module-5ZSLUQII.mjs +3729 -0
- package/dist/msgpack-leaf-H5ZYW7S7.mjs +9 -0
- package/dist/optional-reads-5HFMF2QZ.mjs +3373 -0
- package/dist/optional-writes-4UOQKETU.mjs +247 -0
- package/dist/paged-partition-archive-BBRLZCIF.mjs +253 -0
- package/dist/partial-words.browser.mjs +1650 -0
- package/dist/partial-words.mjs +17 -11
- package/dist/{chunk-ASY5PHYI.mjs → pattern.browser.mjs} +253 -311
- package/dist/pattern.mjs +6 -7
- package/dist/persistence/durability/checkpoint-worker.d.ts +93 -25
- package/dist/persistence/durability/checkpoint-worker.mjs +51 -41
- package/dist/phrase-module-EFESWOCR.mjs +635 -0
- package/dist/query-actions-HMJUVWGT.mjs +119 -0
- package/dist/query-suggestions/merge-worker.d.ts +55 -0
- package/dist/query-suggestions/merge-worker.mjs +53 -0
- package/dist/query-suggestions-CBYkrQ5T.d.ts +311 -0
- package/dist/query-suggestions.browser.mjs +47 -0
- package/dist/query-suggestions.d.ts +20 -0
- package/dist/query-suggestions.mjs +19 -0
- package/dist/react-native/chunks/chunk-3OEFSHVV.mjs +970 -0
- package/dist/{browser/chunk-RELZRJNR.mjs → react-native/chunks/chunk-43R4GCM7.mjs} +49 -50
- package/dist/react-native/chunks/chunk-AKRYHAVG.mjs +6729 -0
- package/dist/react-native/chunks/chunk-CW2ZFXSE.mjs +14 -0
- package/dist/react-native/chunks/chunk-G3WCDTOF.mjs +29640 -0
- package/dist/react-native/chunks/chunk-GXXHHA2T.mjs +212 -0
- package/dist/react-native/chunks/chunk-H3MDVPBO.mjs +151 -0
- package/dist/react-native/chunks/chunk-HQEVQEDJ.mjs +52 -0
- package/dist/react-native/chunks/chunk-HRDMIQ63.mjs +131 -0
- package/dist/react-native/chunks/chunk-HTBY4GON.mjs +565 -0
- package/dist/react-native/chunks/chunk-LX62Y4B5.mjs +61 -0
- package/dist/react-native/chunks/chunk-MRH36RN3.mjs +902 -0
- package/dist/react-native/chunks/chunk-Q32DDFKX.mjs +19 -0
- package/dist/react-native/chunks/chunk-UE4ANHSX.mjs +127 -0
- package/dist/react-native/chunks/chunk-UNZPWLVL.mjs +1063 -0
- package/dist/react-native/chunks/chunk-UO44MA5M.mjs +232 -0
- package/dist/react-native/chunks/chunk-UYKIV2KT.mjs +42 -0
- package/dist/react-native/chunks/chunk-VUJCSQG5.mjs +11 -0
- package/dist/react-native/chunks/chunk-WVHF4ZAK.mjs +802 -0
- package/dist/react-native/chunks/chunk-ZUJCUPVS.mjs +54 -0
- package/dist/react-native/chunks/core-leaf-S2KNBWDY.mjs +7 -0
- package/dist/react-native/chunks/custom-token-results-3OZEMRE7.mjs +59 -0
- package/dist/react-native/chunks/digest-leaf-X6OIFDIU.mjs +1 -0
- package/dist/react-native/chunks/durability-config-FCSD4MXY.mjs +96 -0
- package/dist/react-native/chunks/embed-HA2I7RCF.mjs +263 -0
- package/dist/react-native/chunks/geo-index-QEYKEVPH.mjs +1484 -0
- package/dist/react-native/chunks/gzip.react-native-CVM4NQG2.mjs +12 -0
- package/dist/react-native/chunks/module-FMBX75GP.mjs +5209 -0
- package/dist/react-native/chunks/msgpack-leaf-JMNGSTRW.mjs +7 -0
- package/dist/react-native/chunks/optional-reads-AFPO2FEB.mjs +3364 -0
- package/dist/react-native/chunks/optional-writes-XOH25XZI.mjs +296 -0
- package/dist/react-native/chunks/phrase-module-IGYBK7XH.mjs +636 -0
- package/dist/react-native/chunks/replace-IMZUVUOE.mjs +57 -0
- package/dist/react-native/chunks/resolve-vector-text-GE2CRJKI.mjs +84 -0
- package/dist/react-native/chunks/restore-queue-LLNMYB4Z.mjs +187 -0
- package/dist/react-native/chunks/runtime-UOHD2XUJ.mjs +615 -0
- package/dist/react-native/chunks/segment-codec-leaf-VR6O5GLC.mjs +13 -0
- package/dist/react-native/chunks/segment-merge-leaf-LLMWU4EW.mjs +14 -0
- package/dist/react-native/chunks/storage-leaf-JD7PIDO4.mjs +19633 -0
- package/dist/react-native/chunks/store-leaf-4UVCMYGN.mjs +15 -0
- package/dist/react-native/chunks/suggestions-leaf-J5VT5RHY.mjs +1321 -0
- package/dist/react-native/chunks/worker-copies-ZYHY7FKJ.mjs +2831 -0
- package/dist/react-native/partial-words.mjs +1658 -0
- package/dist/react-native/pattern.mjs +2570 -0
- package/dist/react-native/query-suggestions.mjs +55 -0
- package/dist/react-native/sync.mjs +2759 -0
- package/dist/react-native/synonyms.mjs +676 -0
- package/dist/react.d.ts +12 -8
- package/dist/react.mjs +45 -1
- package/dist/{rerank-NWTKK636.mjs → rerank-RI2PMNOD.mjs} +22 -12
- package/dist/rerankers/http.d.ts +1 -1
- package/dist/rerankers/http.mjs +2 -2
- package/dist/resolve-vector-text-OD4J3WHF.mjs +3 -0
- package/dist/restore-queue-PCKWDAKQ.mjs +192 -0
- package/dist/runtime-USQYKN3I.mjs +615 -0
- package/dist/{schema-4W_7tk1f.d.ts → schema-CzG9OUw5.d.ts} +70 -30
- package/dist/segment-codec-leaf-QJM7I6QG.mjs +18 -0
- package/dist/segment-merge-leaf-4BJGIJHY.mjs +18 -0
- package/dist/server.d.ts +348 -22
- package/dist/server.mjs +2211 -327
- package/dist/storage-leaf-GRRRI7UV.mjs +5962 -0
- package/dist/store-leaf-6VMMSVBE.mjs +20 -0
- package/dist/stored-values-BWIMpiT_.d.ts +25 -0
- package/dist/suggestions-leaf-4KPTMPTL.mjs +54 -0
- package/dist/sync/filesystem.d.ts +30 -0
- package/dist/sync/filesystem.mjs +288 -0
- package/dist/sync/indexeddb.browser.mjs +287 -0
- package/dist/sync/indexeddb.d.ts +30 -0
- package/dist/sync/indexeddb.mjs +242 -0
- package/dist/sync.browser.mjs +1271 -0
- package/dist/sync.d.ts +23 -0
- package/dist/sync.mjs +2712 -0
- package/dist/synonyms.browser.mjs +658 -0
- package/dist/synonyms.mjs +17 -7
- package/dist/tasks-65b6t6lk.d.ts +782 -0
- package/dist/thread-UJ3W5LVI.mjs +31 -0
- package/dist/{types-B3b68nfF.d.ts → types-Ck97nB3D.d.ts} +1 -1
- package/dist/types-CpCg-Gq-.d.ts +227 -0
- package/dist/{types-Cb9kiY5P.d.ts → types-DvncmvuQ.d.ts} +12 -1
- package/dist/vector/search-worker.d.ts +10 -2
- package/dist/vector/search-worker.mjs +11 -11
- package/dist/worker-copies-YSXZXIGC.mjs +2232 -0
- package/dist/workers/entry.mjs +75 -15
- package/openapi.json +6840 -0
- package/package.json +404 -19
- package/dist/browser/chunk-CN4I4FZU.mjs +0 -602
- package/dist/browser/chunk-HOZW3PKP.mjs +0 -9
- package/dist/browser/chunk-JPTQZWJQ.mjs +0 -10
- package/dist/browser/chunk-LD55ZGU3.mjs +0 -347
- package/dist/browser/chunk-NAFT3K6X.mjs +0 -24546
- package/dist/browser/chunk-NNG3EEB6.mjs +0 -2728
- package/dist/browser/chunk-QWES44AW.mjs +0 -473
- package/dist/browser/durability-wiring-PY3L7DES.mjs +0 -3679
- package/dist/browser/module-PDXYHT75.mjs +0 -2822
- package/dist/browser/release-76MXRPGV.mjs +0 -33
- package/dist/browser/restore-queue-DVIYJ7RU.mjs +0 -35
- package/dist/browser/snapshot-J57MZK6L.mjs +0 -1207
- package/dist/browser/write-L7FAQA47.mjs +0 -208
- package/dist/chunk-37CD3OKS.mjs +0 -87
- package/dist/chunk-5XNIRLFC.mjs +0 -96
- package/dist/chunk-7X5JST5L.mjs +0 -114
- package/dist/chunk-AV4IJKD2.mjs +0 -35
- package/dist/chunk-AY3AQ3UH.mjs +0 -73
- package/dist/chunk-BKB3XTMI.mjs +0 -707
- package/dist/chunk-C7SLA6CM.mjs +0 -19
- package/dist/chunk-COVCQ73F.mjs +0 -587
- package/dist/chunk-DJHHF2L5.mjs +0 -17
- package/dist/chunk-E74YLAIG.mjs +0 -24
- package/dist/chunk-FMWRCP2C.mjs +0 -57
- package/dist/chunk-GES7U2PM.mjs +0 -68
- package/dist/chunk-HJSN7UYG.mjs +0 -10
- package/dist/chunk-JFRNNBOM.mjs +0 -35
- package/dist/chunk-K25LZA54.mjs +0 -8484
- package/dist/chunk-KEHK2O6P.mjs +0 -13
- package/dist/chunk-KOKM4PQN.mjs +0 -52
- package/dist/chunk-KZ3NX2P7.mjs +0 -21
- package/dist/chunk-L3L5YFXC.mjs +0 -614
- package/dist/chunk-L5ORED7V.mjs +0 -25
- package/dist/chunk-LH4NZNJJ.mjs +0 -1731
- package/dist/chunk-LU2CE5AE.mjs +0 -507
- package/dist/chunk-LXWDQLTW.mjs +0 -30
- package/dist/chunk-MHOSCQCQ.mjs +0 -948
- package/dist/chunk-NKRBEGJZ.mjs +0 -1705
- package/dist/chunk-NTRMFARG.mjs +0 -462
- package/dist/chunk-NW4XDSP2.mjs +0 -212
- package/dist/chunk-OOEXLUGR.mjs +0 -117
- package/dist/chunk-ORBLD3EL.mjs +0 -6
- package/dist/chunk-OWNZYMRE.mjs +0 -3591
- package/dist/chunk-PPY2GSIB.mjs +0 -44
- package/dist/chunk-QY7GC2MW.mjs +0 -33
- package/dist/chunk-R6A773WK.mjs +0 -226
- package/dist/chunk-R6PR4WYZ.mjs +0 -68
- package/dist/chunk-R7EEKAJE.mjs +0 -593
- package/dist/chunk-RONEOEON.mjs +0 -426
- package/dist/chunk-VWULPWRJ.mjs +0 -7469
- package/dist/chunk-WCJKUGHB.mjs +0 -262
- package/dist/chunk-WQBCBKY3.mjs +0 -8
- package/dist/chunk-X5CV2E2B.mjs +0 -1
- package/dist/chunk-YA7XLE2R.mjs +0 -1256
- package/dist/chunk-YTJCGKM4.mjs +0 -56
- package/dist/chunk-ZG477IPV.mjs +0 -526
- package/dist/chunk-ZYNAMIYX.mjs +0 -113
- package/dist/config-BGB_fDtq.d.ts +0 -237
- package/dist/direct-executor-CXZ66ACP.mjs +0 -22
- package/dist/durability-wiring-QTHOGFMZ.mjs +0 -3229
- package/dist/engine-BGCEm9E_.d.ts +0 -577
- package/dist/module-3NONKBZX.mjs +0 -1860
- package/dist/release-BH3DKW3T.mjs +0 -33
- package/dist/restore-queue-JPRBUYII.mjs +0 -35
- package/dist/runtime-ZKYZFJJC.mjs +0 -177
- package/dist/snapshot-HOGXNO5W.mjs +0 -793
- package/dist/tasks-HG3rlxx6.d.ts +0 -302
- package/dist/thread-B657LQXK.mjs +0 -692
- package/dist/write-XLIGTXBU.mjs +0 -238
|
@@ -1,4 +1,867 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { E as EmbeddingAdapter, R as RerankAdapter } from './adapters-pljAqmrC.js';
|
|
2
|
+
import { A as AnyDocument, B as BM25Params, d as ScoringMode, S as SchemaDefinition, a as InsertOptions, W as WriteOptions, I as IndexConfig, P as PartitionConfig } from './schema-CzG9OUw5.js';
|
|
3
|
+
import { h as QuerySuggestionsBuildEvent, j as QuerySuggestionsWarningEvent } from './query-suggestions-CBYkrQ5T.js';
|
|
4
|
+
import { a as SynonymRule } from './synonyms-CpOAHPa-.js';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Compares one field against a value. Setting several keys narrows the match,
|
|
8
|
+
* because a document has to satisfy all of them.
|
|
9
|
+
*
|
|
10
|
+
* @public
|
|
11
|
+
*/
|
|
12
|
+
type ComparisonFilter = {
|
|
13
|
+
/** This matches a field equal to the value, or a list field where one element equals it. */
|
|
14
|
+
eq?: number | string | boolean;
|
|
15
|
+
/**
|
|
16
|
+
* This matches a document that holds the field with a value other than this
|
|
17
|
+
* one, or a list field where every element differs from it, which an empty
|
|
18
|
+
* list does.
|
|
19
|
+
*/
|
|
20
|
+
ne?: number | string | boolean;
|
|
21
|
+
/** This matches a field greater than the number. */
|
|
22
|
+
gt?: number;
|
|
23
|
+
/** This matches a field less than the number. */
|
|
24
|
+
lt?: number;
|
|
25
|
+
/** This matches a field greater than or equal to the number. */
|
|
26
|
+
gte?: number;
|
|
27
|
+
/** This matches a field less than or equal to the number. */
|
|
28
|
+
lte?: number;
|
|
29
|
+
/** This matches a field inside the inclusive range, given as `[low, high]`. */
|
|
30
|
+
between?: [number, number];
|
|
31
|
+
};
|
|
32
|
+
/**
|
|
33
|
+
* The engine tests a text field against this filter for equality, for a text
|
|
34
|
+
* range, or with the set, prefix, and pattern tests.
|
|
35
|
+
*
|
|
36
|
+
* On a `string[]`, `verbatim[]`, or `enum[]` field, the engine tests each
|
|
37
|
+
* element of the list on its own. A document passes `eq`, `in`, `startsWith`,
|
|
38
|
+
* `endsWith`, `contains`, `wildcard`, or `regex` when one element passes the
|
|
39
|
+
* test. However, a document passes `ne` or `nin` only when every element
|
|
40
|
+
* differs from the values.
|
|
41
|
+
*
|
|
42
|
+
* The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
|
|
43
|
+
* to a single `string` or `verbatim` field whose type includes `sortable`. It
|
|
44
|
+
* throws `SEARCH_INVALID_FILTER` for a text range on any other field. It
|
|
45
|
+
* orders the values as a sort on the field does, so it compares their case
|
|
46
|
+
* folds first and compares their raw code points only where the folds are
|
|
47
|
+
* equal.
|
|
48
|
+
*
|
|
49
|
+
* A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
|
|
50
|
+
* `string[]` field whose type includes `pattern`. On a pattern field, the
|
|
51
|
+
* engine answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
|
|
52
|
+
* `contains`, `wildcard`, and `regex` from the field's pattern index, and
|
|
53
|
+
* `caseFold` applies to each of those tests. The engine compares the code
|
|
54
|
+
* points of each value as they are stored, with no Unicode normalisation.
|
|
55
|
+
*
|
|
56
|
+
* On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
|
|
57
|
+
* `startsWith`, and `endsWith` from the field's index of values. A `string` or
|
|
58
|
+
* `string[]` field whose type leaves out `pattern` keeps no index of whole
|
|
59
|
+
* values, so the engine throws `SEARCH_INVALID_FILTER` for those six tests,
|
|
60
|
+
* and for `matchesAny` and `containsAll`, on such a field.
|
|
61
|
+
*
|
|
62
|
+
* The engine also throws `SEARCH_INVALID_FILTER` in these cases:
|
|
63
|
+
*
|
|
64
|
+
* - The filter sets `contains`, `wildcard`, `regex`, or `caseFold` on a field
|
|
65
|
+
* that is not a pattern field.
|
|
66
|
+
* - The text or the pattern of a test on a pattern field holds more than 1,024
|
|
67
|
+
* code points.
|
|
68
|
+
* - A literal test under `caseFold` has a text whose case fold holds more than
|
|
69
|
+
* 2,048 code points.
|
|
70
|
+
* - A `wildcard` or `regex` pattern breaks its syntax or one of its limits.
|
|
71
|
+
*
|
|
72
|
+
* @public
|
|
73
|
+
*/
|
|
74
|
+
type StringFilter = Pick<ComparisonFilter, 'eq' | 'ne'> & {
|
|
75
|
+
/** This matches a value that comes after the text in sort order. */
|
|
76
|
+
gt?: string;
|
|
77
|
+
/** This matches a value that comes before the text in sort order. */
|
|
78
|
+
lt?: string;
|
|
79
|
+
/** This matches a value equal to the text or after it in sort order. */
|
|
80
|
+
gte?: string;
|
|
81
|
+
/** This matches a value equal to the text or before it in sort order. */
|
|
82
|
+
lte?: string;
|
|
83
|
+
/** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
|
|
84
|
+
between?: [string, string];
|
|
85
|
+
/** This matches a field equal to any value in the list, which holds at most 65,536 values. */
|
|
86
|
+
in?: string[];
|
|
87
|
+
/** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
|
|
88
|
+
nin?: string[];
|
|
89
|
+
/** This matches a field starting with the text. */
|
|
90
|
+
startsWith?: string;
|
|
91
|
+
/** This matches a field ending with the text. */
|
|
92
|
+
endsWith?: string;
|
|
93
|
+
/** This matches a pattern field whose value holds the text anywhere in it. */
|
|
94
|
+
contains?: string;
|
|
95
|
+
/**
|
|
96
|
+
* This matches a pattern field when the whole value matches the wildcard
|
|
97
|
+
* pattern. For example, `INV-*-2024` matches `INV-0042-2024`.
|
|
98
|
+
*
|
|
99
|
+
* In the pattern, `*` matches any sequence of code points, including an
|
|
100
|
+
* empty one, and `?` matches exactly one code point. Write `\` before a code
|
|
101
|
+
* point to match that code point itself, so `\*` matches an asterisk.
|
|
102
|
+
*
|
|
103
|
+
* The engine throws `SEARCH_INVALID_FILTER` for a pattern that ends in a
|
|
104
|
+
* `\` with no code point after it. It throws the same error for a pattern
|
|
105
|
+
* with more than 2,048 positions. Each `*`, each `?`, and each other code
|
|
106
|
+
* point counts as one position, except that under `caseFold` a code point
|
|
107
|
+
* counts once for each code point of its case fold.
|
|
108
|
+
*/
|
|
109
|
+
wildcard?: string;
|
|
110
|
+
/**
|
|
111
|
+
* This matches a pattern field when some part of the value matches the
|
|
112
|
+
* regular expression. `^` and `$` match only at the start and at the end of
|
|
113
|
+
* the whole value.
|
|
114
|
+
*
|
|
115
|
+
* The engine accepts literal code points, `.`, `\d`, `\w`, and `\s`, sets
|
|
116
|
+
* such as `[a-z]` and `[^0-9]`, groups, and `|`. It also accepts the repeats
|
|
117
|
+
* `*`, `+`, `?`, `{n}`, `{n,}`, and `{n,m}`, the anchors `^` and `$`, the
|
|
118
|
+
* word edge `\b`, and number ranges such as `<1-65535>`. A number range
|
|
119
|
+
* matches the digits of any whole number from its low end to its high end.
|
|
120
|
+
* Write `\` before an ASCII punctuation mark to match the mark itself. The
|
|
121
|
+
* `.` matches any code point, including a line break.
|
|
122
|
+
*
|
|
123
|
+
* The matcher never backtracks, so it checks a value in at most as many
|
|
124
|
+
* steps as the value's code points multiplied by the pattern's positions.
|
|
125
|
+
*
|
|
126
|
+
* The engine throws `SEARCH_INVALID_FILTER` for any construct outside that
|
|
127
|
+
* syntax, such as a back-reference, a lookaround, a lazy repeat, or an inline
|
|
128
|
+
* flag. It throws the same error when the groups of a pattern nest more than
|
|
129
|
+
* 32 deep, when a count is above 2,048, and when a pattern holds more than
|
|
130
|
+
* 2,048 positions. When the operator of an HTTP server sets its `allowRegex`
|
|
131
|
+
* option to false, the server refuses every `regex` test.
|
|
132
|
+
*/
|
|
133
|
+
regex?: string;
|
|
134
|
+
/**
|
|
135
|
+
* When this is true, the engine compares the case fold of each value of a
|
|
136
|
+
* pattern field with the case fold of the text, so a test for `error`
|
|
137
|
+
* matches `ERROR`. It applies to `eq`, `ne`, `in`, `nin`, `startsWith`,
|
|
138
|
+
* `endsWith`, `contains`, `wildcard`, and `regex`.
|
|
139
|
+
*
|
|
140
|
+
* Under `caseFold`, a set that does not open with `^` can also match a
|
|
141
|
+
* sequence of code points. When a member that the set holds on its own folds
|
|
142
|
+
* to several code points, the set matches that whole fold, so `[ß]` matches
|
|
143
|
+
* `ss`.
|
|
144
|
+
*/
|
|
145
|
+
caseFold?: boolean;
|
|
146
|
+
/**
|
|
147
|
+
* This lets the `eq` test of a pattern field match a value within this many
|
|
148
|
+
* edits of the text, so a test for `INV-2O24` with a tolerance of 1 matches
|
|
149
|
+
* `INV-2024`. An edit inserts, deletes, or replaces one code point, so a
|
|
150
|
+
* swap of two neighbouring code points counts as two edits. With `caseFold`,
|
|
151
|
+
* the engine counts the edits between the case folds of the value and the
|
|
152
|
+
* text. The tolerance applies to `eq` alone, so the other tests of the field
|
|
153
|
+
* still compare exactly.
|
|
154
|
+
*
|
|
155
|
+
* The engine takes its candidates from the pattern index, so the case fold
|
|
156
|
+
* of the text has to hold enough distinct runs of three code points. For a
|
|
157
|
+
* tolerance of `k`, the engine needs `k × (2 + f) + 1` runs, where `f` is
|
|
158
|
+
* the number of code points in the longest case fold among the text's code
|
|
159
|
+
* points, which is 1 for most text. A tolerance of 1 on `INV-2O24`
|
|
160
|
+
* therefore needs 4 of its 6 runs, while a tolerance of 2 needs 7. Under
|
|
161
|
+
* `'auto'`, the engine uses 2 where the text holds enough runs for 2,
|
|
162
|
+
* otherwise 1 where it holds enough for 1, and otherwise 0.
|
|
163
|
+
*
|
|
164
|
+
* The engine throws `SEARCH_INVALID_FILTER` for a tolerance of 1 or 2 on a
|
|
165
|
+
* text with too few runs, stating how many runs that tolerance needs. It
|
|
166
|
+
* throws the same error for any other tolerance, for a tolerance on a field
|
|
167
|
+
* that is not a pattern field, and for a tolerance in a filter without an
|
|
168
|
+
* `eq` test. Towards the pattern work cap, it counts one unit for each cell
|
|
169
|
+
* that it fills in the table of edit distances between the text and a
|
|
170
|
+
* value.
|
|
171
|
+
*/
|
|
172
|
+
tolerance?: 0 | 1 | 2 | 'auto';
|
|
173
|
+
};
|
|
174
|
+
/**
|
|
175
|
+
* Tests the contents of a list field, which is a `number[]`, `boolean[]`,
|
|
176
|
+
* `enum[]`, `verbatim[]`, or `string[]` field.
|
|
177
|
+
*
|
|
178
|
+
* The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
|
|
179
|
+
* field, for a value whose type differs from the type of the list's elements,
|
|
180
|
+
* and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
|
|
181
|
+
* out `pattern`.
|
|
182
|
+
*
|
|
183
|
+
* @public
|
|
184
|
+
*/
|
|
185
|
+
type ArrayFilter = {
|
|
186
|
+
/** 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. */
|
|
187
|
+
containsAll?: (string | number | boolean)[];
|
|
188
|
+
/** This matches a list holding at least one of the values, at most 65,536 of them. */
|
|
189
|
+
matchesAny?: (string | number | boolean)[];
|
|
190
|
+
/** This compares the number of elements in the list. */
|
|
191
|
+
size?: ComparisonFilter;
|
|
192
|
+
};
|
|
193
|
+
/**
|
|
194
|
+
* Tests whether a field carries a value at all, without looking at what it
|
|
195
|
+
* holds.
|
|
196
|
+
*
|
|
197
|
+
* @public
|
|
198
|
+
*/
|
|
199
|
+
type PresenceFilter = {
|
|
200
|
+
/** This matches a document where the field holds a value other than null. */
|
|
201
|
+
exists?: boolean;
|
|
202
|
+
/** This matches a document where the field is absent or null. */
|
|
203
|
+
notExists?: boolean;
|
|
204
|
+
/** This matches a document where the field is absent, null, an empty string, or an empty list. */
|
|
205
|
+
isEmpty?: boolean;
|
|
206
|
+
/** This matches a document where the field holds a value other than an empty string or an empty list. */
|
|
207
|
+
isNotEmpty?: boolean;
|
|
208
|
+
};
|
|
209
|
+
/**
|
|
210
|
+
* Matches a `geopoint` field against a circle drawn on the earth.
|
|
211
|
+
*
|
|
212
|
+
* @public
|
|
213
|
+
*/
|
|
214
|
+
type GeoRadiusFilter = {
|
|
215
|
+
/** The engine tests the field against this circle. */
|
|
216
|
+
radius: {
|
|
217
|
+
/** The centre has this latitude, in degrees from -90 to 90. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
|
|
218
|
+
lat: number;
|
|
219
|
+
/** The centre has this longitude, in degrees from -180 to 180. For any other value, the engine throws `SEARCH_INVALID_FILTER`. */
|
|
220
|
+
lon: number;
|
|
221
|
+
/** The circle has this radius, measured in `unit`. */
|
|
222
|
+
distance: number;
|
|
223
|
+
/**
|
|
224
|
+
* The engine measures `distance` in kilometres under `'km'`, in miles
|
|
225
|
+
* under `'mi'`, and in metres under `'m'`. For any other unit, it throws
|
|
226
|
+
* `SEARCH_INVALID_FILTER`.
|
|
227
|
+
*/
|
|
228
|
+
unit: 'km' | 'mi' | 'm';
|
|
229
|
+
/** The engine matches the points inside the circle while this is true, which is the default, and the points outside it while this is false. */
|
|
230
|
+
inside?: boolean;
|
|
231
|
+
/**
|
|
232
|
+
* The engine measures each distance with the Haversine formula on a sphere
|
|
233
|
+
* by default, and with Vincenty's formula on the WGS-84 ellipsoid while
|
|
234
|
+
* this is true. Vincenty's formula iterates, so the engine takes longer
|
|
235
|
+
* to compute each distance. The two formulas differ by less than 0.3% under about
|
|
236
|
+
* 100 km, while across a continent they can differ by up to 0.5%.
|
|
237
|
+
*/
|
|
238
|
+
highPrecision?: boolean;
|
|
239
|
+
};
|
|
240
|
+
};
|
|
241
|
+
/**
|
|
242
|
+
* Matches a `geopoint` field against a polygon drawn on the earth.
|
|
243
|
+
*
|
|
244
|
+
* @public
|
|
245
|
+
*/
|
|
246
|
+
type GeoPolygonFilter = {
|
|
247
|
+
/** The engine tests the field against this polygon. */
|
|
248
|
+
polygon: {
|
|
249
|
+
/**
|
|
250
|
+
* The engine closes the ring through these corners in the order that you
|
|
251
|
+
* list them, so you can leave the first point off the end. It throws
|
|
252
|
+
* `SEARCH_INVALID_FILTER` for a ring of fewer than three corners, which
|
|
253
|
+
* encloses no area, and for a corner whose latitude is outside -90 to 90
|
|
254
|
+
* or whose longitude is outside -180 to 180. It also throws that error for
|
|
255
|
+
* a ring of more than 65,536 corners. List the corners counter-clockwise
|
|
256
|
+
* around the area, as in an exterior ring of GeoJSON. Where the corners
|
|
257
|
+
* span 180 degrees of longitude or more, the engine matches the area on
|
|
258
|
+
* the left of that path, so a ring listed that way can cross the
|
|
259
|
+
* antimeridian or span more than half the globe.
|
|
260
|
+
*/
|
|
261
|
+
points: Array<{
|
|
262
|
+
/** The corner has this latitude, in degrees. */
|
|
263
|
+
lat: number;
|
|
264
|
+
/** The corner has this longitude, in degrees. */
|
|
265
|
+
lon: number;
|
|
266
|
+
}>;
|
|
267
|
+
/** The engine matches the points inside the polygon while this is true, which is the default, and the points outside it while this is false. */
|
|
268
|
+
inside?: boolean;
|
|
269
|
+
};
|
|
270
|
+
};
|
|
271
|
+
/**
|
|
272
|
+
* Either shape a `geopoint` field is matched against.
|
|
273
|
+
*
|
|
274
|
+
* @public
|
|
275
|
+
*/
|
|
276
|
+
type GeoFilter = GeoRadiusFilter | GeoPolygonFilter;
|
|
277
|
+
/**
|
|
278
|
+
* The filter one field accepts. Which of these forms applies follows from the
|
|
279
|
+
* field's declared type.
|
|
280
|
+
*
|
|
281
|
+
* @public
|
|
282
|
+
*/
|
|
283
|
+
type FieldFilter = ComparisonFilter | StringFilter | ArrayFilter | PresenceFilter | GeoFilter;
|
|
284
|
+
/**
|
|
285
|
+
* The filter that a query runs, built from per-field tests and the boolean
|
|
286
|
+
* operators that combine them.
|
|
287
|
+
*
|
|
288
|
+
* The engine answers every test from an index that it keeps for the field. It
|
|
289
|
+
* applies the filter before scoring, so a narrow filter makes a search
|
|
290
|
+
* cheaper. A filter nests at most 30 levels deep and holds at most 1,024
|
|
291
|
+
* tests, counted across every field and nested expression. Past either limit,
|
|
292
|
+
* the engine throws `SEARCH_INVALID_FILTER`, while it throws
|
|
293
|
+
* `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
|
|
294
|
+
*
|
|
295
|
+
* @public
|
|
296
|
+
*/
|
|
297
|
+
type FilterExpression = {
|
|
298
|
+
/** These per-field tests are keyed by field name, and a document has to satisfy every entry. */
|
|
299
|
+
fields?: Record<string, FieldFilter>;
|
|
300
|
+
/** Every nested expression has to match. */
|
|
301
|
+
and?: FilterExpression[];
|
|
302
|
+
/** At least one nested expression has to match. */
|
|
303
|
+
or?: FilterExpression[];
|
|
304
|
+
/** The nested expression has to fail. */
|
|
305
|
+
not?: FilterExpression;
|
|
306
|
+
};
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* How a query reorders its top hits with a rerank adapter.
|
|
310
|
+
*
|
|
311
|
+
* The engine ranks the query as it would without this setting, passes the
|
|
312
|
+
* top `window` hits to the adapter, and orders them by the adapter's scores.
|
|
313
|
+
* The hits past the window follow in their first ranking, with their scores
|
|
314
|
+
* scaled below the lowest reranked score, so every page of one query comes
|
|
315
|
+
* from the same order.
|
|
316
|
+
*
|
|
317
|
+
* @public
|
|
318
|
+
*/
|
|
319
|
+
interface RerankConfig {
|
|
320
|
+
/**
|
|
321
|
+
* The engine scores the hits with the rerank adapter registered under this
|
|
322
|
+
* key. It throws `RERANK_CONFIG_INVALID` for a key that it has not
|
|
323
|
+
* registered.
|
|
324
|
+
*/
|
|
325
|
+
adapter: string;
|
|
326
|
+
/**
|
|
327
|
+
* The engine sends the adapter the values of these text fields, in this
|
|
328
|
+
* order and joined with newlines, as the text of each hit. Each member of a
|
|
329
|
+
* list field takes a line of its own. The engine throws
|
|
330
|
+
* `RERANK_CONFIG_INVALID` for an empty list, for a field that the schema
|
|
331
|
+
* does not declare as text, and for a field that the list gives twice.
|
|
332
|
+
*/
|
|
333
|
+
fields: string[];
|
|
334
|
+
/**
|
|
335
|
+
* The adapter compares each hit with this text. Where you leave it out, the
|
|
336
|
+
* engine sends the query's `term`, or else its `vector.text`, and it throws
|
|
337
|
+
* `RERANK_CONFIG_INVALID` where the query carries neither.
|
|
338
|
+
*/
|
|
339
|
+
query?: string;
|
|
340
|
+
/**
|
|
341
|
+
* The engine reranks this many of the top hits, from 1 to the engine's
|
|
342
|
+
* `maxRerankWindow`. Where you leave the window out, the engine reranks the
|
|
343
|
+
* smallest of 100 and `maxRerankWindow`, and no more than the `hybrid.depth`
|
|
344
|
+
* of a hybrid query that sets one. A hybrid query that sets `hybrid.depth`
|
|
345
|
+
* reranks its fused list at that depth, so the engine throws
|
|
346
|
+
* `RERANK_CONFIG_INVALID` when you set a window above that depth.
|
|
347
|
+
*/
|
|
348
|
+
window?: number;
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
/**
|
|
352
|
+
* Vector-search inputs passed under `QueryParams.vector`.
|
|
353
|
+
*
|
|
354
|
+
* Supply either a raw `value` array or a `text` string for auto-embedding;
|
|
355
|
+
* passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
|
|
356
|
+
* by the outer query's `limit`, not by any field on this object.
|
|
357
|
+
*
|
|
358
|
+
* @public
|
|
359
|
+
*/
|
|
360
|
+
interface VectorQueryConfig {
|
|
361
|
+
/**
|
|
362
|
+
* Name of the schema field that holds the vector to compare against.
|
|
363
|
+
* Must reference a field declared as `vector[N]` in the index schema.
|
|
364
|
+
*/
|
|
365
|
+
field: string;
|
|
366
|
+
/**
|
|
367
|
+
* Raw query vector, given as a number array or a `Float32Array`. Length
|
|
368
|
+
* must match the indexed field's dimension or the search rejects the
|
|
369
|
+
* request with `VECTOR_DIMENSION_MISMATCH`.
|
|
370
|
+
*/
|
|
371
|
+
value?: number[] | Float32Array;
|
|
372
|
+
/**
|
|
373
|
+
* Text to embed at query time using the index or instance embedding
|
|
374
|
+
* adapter. Mutually exclusive with `value`; requires a configured adapter.
|
|
375
|
+
*/
|
|
376
|
+
text?: string;
|
|
377
|
+
/**
|
|
378
|
+
* Score floor applied during ranking. Hits scoring below this value
|
|
379
|
+
* are dropped before `limit` is enforced, so the returned hit count
|
|
380
|
+
* can be smaller than `limit` even when more documents exist. The
|
|
381
|
+
* floor is interpreted in score space for every metric; for
|
|
382
|
+
* `euclidean`, distance is mapped to a similarity score of
|
|
383
|
+
* `1 / (1 + distance)` first. Defaults to no floor.
|
|
384
|
+
*/
|
|
385
|
+
similarity?: number;
|
|
386
|
+
/**
|
|
387
|
+
* Similarity metric used for ranking. Defaults to `cosine`. Choose
|
|
388
|
+
* `dotProduct` for raw inner-product scoring on already-normalised
|
|
389
|
+
* vectors and `euclidean` for distance-based ordering.
|
|
390
|
+
*/
|
|
391
|
+
metric?: 'cosine' | 'dotProduct' | 'euclidean';
|
|
392
|
+
/**
|
|
393
|
+
* The engine keeps this many candidates as it walks the HNSW graph, so a
|
|
394
|
+
* higher value can find more of the true neighbours, although each query
|
|
395
|
+
* takes longer. The engine applies it only once the field holds a graph.
|
|
396
|
+
* The engine fetches k hits, where k is one more than the number of hits up
|
|
397
|
+
* to the end of the page, so k is `limit` plus 1 on a first page. When a
|
|
398
|
+
* query leaves `efSearch` unset, the engine keeps the larger of 50 and k
|
|
399
|
+
* plus a margin, where the margin is 50 below 768 dimensions, 75 from 768
|
|
400
|
+
* to 1,023 dimensions, and 0 at 1,024 dimensions and above. Under a
|
|
401
|
+
* filter, the engine counts only the candidates that pass the filter.
|
|
402
|
+
* A vector or hybrid query throws a `NarsilError` with `CONFIG_INVALID`
|
|
403
|
+
* before it searches when `efSearch` is not a whole number from 1 to
|
|
404
|
+
* 10,000, whether or not the field holds a graph yet and whether or not
|
|
405
|
+
* its filter matches a document.
|
|
406
|
+
*/
|
|
407
|
+
efSearch?: number;
|
|
408
|
+
/**
|
|
409
|
+
* The engine re-scores this many times k candidates in a quantized field
|
|
410
|
+
* against the full-precision vectors before it returns the best `limit`,
|
|
411
|
+
* where k is one more than the number of hits up to the end of the page, so
|
|
412
|
+
* k is `limit` plus 1 on a first page. For a value below 1, or for a value
|
|
413
|
+
* that is not a finite number, the engine throws a `NarsilError` with code
|
|
414
|
+
* `CONFIG_INVALID`. The engine ignores it on a field whose quantization is
|
|
415
|
+
* `none`. When a query leaves it unset, the engine sets the number of
|
|
416
|
+
* candidates that it re-scores from k and from the field's dimension. It
|
|
417
|
+
* rounds that number up, and it re-scores at least 3k candidates under
|
|
418
|
+
* `osq1` and `osq2`, and at least k under `osq4` and `osq8`. Below 768
|
|
419
|
+
* dimensions, it re-scores 3.23k + 55.9√k under `osq1` and 2.6k + 22.5√k under
|
|
420
|
+
* `osq2`. From 768 to 1,023 dimensions, it re-scores 2.2k + 27√k under
|
|
421
|
+
* `osq1` and k + 16√k under `osq2`, and under `osq2` it re-scores at least
|
|
422
|
+
* the smaller of k + 75 and k + 18√k. At 1,024 dimensions and above, it
|
|
423
|
+
* re-scores 3k under both. Under `osq4`, it re-scores 5k below 1,024
|
|
424
|
+
* dimensions and 2k from 1,024 dimensions, while under `osq8` it re-scores
|
|
425
|
+
* 2k at every dimension. Under a filter, the engine counts only the
|
|
426
|
+
* candidates that pass the filter. On vectors spread evenly across every
|
|
427
|
+
* dimension, a one-bit or two-bit code can find fewer than 95% of the true
|
|
428
|
+
* nearest neighbours at these defaults, so raise `oversample` on a query that
|
|
429
|
+
* needs more of them. The engine re-scores at most the larger of 10,000 and
|
|
430
|
+
* the default depth, so a larger `oversample` can't lengthen the walk past
|
|
431
|
+
* that. A vector or hybrid query throws a `NarsilError` with
|
|
432
|
+
* `CONFIG_INVALID` before it searches when `oversample` is not a finite
|
|
433
|
+
* number of at least 1.
|
|
434
|
+
*/
|
|
435
|
+
oversample?: number;
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* How a hybrid query merges its keyword ranking with its vector ranking.
|
|
439
|
+
*
|
|
440
|
+
* `rrf` combines the two by rank alone, which needs no tuning and handles
|
|
441
|
+
* scores that live on different scales. `linear` blends the scores directly,
|
|
442
|
+
* which gives you control once you know what each side's scores look like.
|
|
443
|
+
*
|
|
444
|
+
* @public
|
|
445
|
+
*/
|
|
446
|
+
interface HybridConfig {
|
|
447
|
+
/** The engine merges the rankings this way, and by rank fusion by default. It throws `CONFIG_INVALID` for any other value. */
|
|
448
|
+
strategy?: 'rrf' | 'linear';
|
|
449
|
+
/** 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. */
|
|
450
|
+
k?: number;
|
|
451
|
+
/** 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. */
|
|
452
|
+
alpha?: number;
|
|
453
|
+
/**
|
|
454
|
+
* Set a depth to get the same fused order on every page of one query, and
|
|
455
|
+
* a cursor that resumes it. The engine then fetches this many results from
|
|
456
|
+
* the keyword search and from the vector search, fuses them, and pages
|
|
457
|
+
* through the top `depth` of the fused list. The last page stops at this
|
|
458
|
+
* depth, so it can hold fewer hits than the limit. Set a whole number from 1
|
|
459
|
+
* to 10,000. The engine throws `CONFIG_INVALID` for any other value, and
|
|
460
|
+
* `SEARCH_RESULT_WINDOW_EXCEEDED` for a page that starts at this depth or
|
|
461
|
+
* beyond. Where you leave the depth out, each search fetches only enough
|
|
462
|
+
* results to fill the page, so the fused order can change from one page to
|
|
463
|
+
* the next, and a cluster refuses a cursor with `SEARCH_INVALID_CURSOR`.
|
|
464
|
+
*/
|
|
465
|
+
depth?: number;
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
/**
|
|
469
|
+
* Everything {@link Narsil.suggest} accepts.
|
|
470
|
+
*
|
|
471
|
+
* @public
|
|
472
|
+
*/
|
|
473
|
+
interface SuggestParams {
|
|
474
|
+
/** The returned terms complete this text. */
|
|
475
|
+
prefix: string;
|
|
476
|
+
/** The lookup returns this many completions, most widely used first, and 10 by default. */
|
|
477
|
+
limit?: number;
|
|
478
|
+
}
|
|
479
|
+
/**
|
|
480
|
+
* Everything {@link Narsil.listDocuments} accepts.
|
|
481
|
+
*
|
|
482
|
+
* {@link Narsil.listDocuments} reads the stored documents without ranking them,
|
|
483
|
+
* which is how you page through a whole index. Leave `cursor` out to start at
|
|
484
|
+
* the first document, then pass back the cursor each result carries until it
|
|
485
|
+
* comes back null.
|
|
486
|
+
*
|
|
487
|
+
* A cursor belongs to the sort it was made under, so pass the same `sort` back
|
|
488
|
+
* with it. Changing `sort` invalidates the cursor, and the engine then throws
|
|
489
|
+
* `SEARCH_INVALID_CURSOR` rather than returning a page from the wrong order.
|
|
490
|
+
*
|
|
491
|
+
* @public
|
|
492
|
+
*/
|
|
493
|
+
interface ListParams {
|
|
494
|
+
/**
|
|
495
|
+
* This cursor comes from a previous result, and continues where it stopped.
|
|
496
|
+
* The engine ties a cursor to the sort that produced it, and it throws
|
|
497
|
+
* `SEARCH_INVALID_CURSOR` for a cursor sent back under a different sort.
|
|
498
|
+
*/
|
|
499
|
+
cursor?: string;
|
|
500
|
+
/** The page carries this many documents, and 10 by default. The engine raises a value below one to one. */
|
|
501
|
+
limit?: number;
|
|
502
|
+
/** This narrows the listing to the documents the filter accepts. */
|
|
503
|
+
filters?: FilterExpression;
|
|
504
|
+
/**
|
|
505
|
+
* This orders the listing by field value rather than by document id, and the
|
|
506
|
+
* engine applies the fields in the order they are listed. Pass an object
|
|
507
|
+
* keyed by field, or a list of fields in the order they apply. It breaks a
|
|
508
|
+
* tie on document id, and it sorts by at most eight fields. The engine uses
|
|
509
|
+
* document-id order when you leave this out.
|
|
510
|
+
*
|
|
511
|
+
* The engine reads every document the listing covers to build a sorted page,
|
|
512
|
+
* so a sorted listing costs more than the default order on a large index.
|
|
513
|
+
*/
|
|
514
|
+
sort?: SortSpec;
|
|
515
|
+
/** This chooses how much of each stored document comes back, and the whole document by default. */
|
|
516
|
+
document?: DocumentProjection;
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
/**
|
|
520
|
+
* Which engine answers a query: keyword matching, vector similarity, or both
|
|
521
|
+
* merged into one ranking.
|
|
522
|
+
*
|
|
523
|
+
* @public
|
|
524
|
+
*/
|
|
525
|
+
type SearchMode = 'fulltext' | 'vector' | 'hybrid';
|
|
526
|
+
/**
|
|
527
|
+
* How many of a query's terms a document has to carry. `all` demands every
|
|
528
|
+
* term, `any` accepts one, and a number demands that many.
|
|
529
|
+
*
|
|
530
|
+
* @public
|
|
531
|
+
*/
|
|
532
|
+
type TermMatchPolicy = 'all' | 'any' | number;
|
|
533
|
+
/**
|
|
534
|
+
* One field of a sort, and the direction that field orders by.
|
|
535
|
+
*
|
|
536
|
+
* @public
|
|
537
|
+
*/
|
|
538
|
+
interface SortField {
|
|
539
|
+
/** The field the engine reads, which may name a nested field with dots. */
|
|
540
|
+
field: string;
|
|
541
|
+
/** Ascending or descending order for this field. */
|
|
542
|
+
direction: 'asc' | 'desc';
|
|
543
|
+
/**
|
|
544
|
+
* Where a document's field holds a list, the engine sorts that document by
|
|
545
|
+
* one value from the list: the smallest under `'min'`, the largest under
|
|
546
|
+
* `'max'`, and the mean or the median of the list's numbers under `'avg'`
|
|
547
|
+
* or `'median'`. Where you leave this out, the engine uses `'min'` for an
|
|
548
|
+
* ascending sort and `'max'` for a descending one. It sorts by a field that
|
|
549
|
+
* holds a single value as that value stands, under every mode. It throws
|
|
550
|
+
* `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
|
|
551
|
+
* schema declares as anything other than `number` or `number[]`.
|
|
552
|
+
*/
|
|
553
|
+
mode?: 'min' | 'max' | 'avg' | 'median';
|
|
554
|
+
}
|
|
555
|
+
/**
|
|
556
|
+
* A sort, either as an object keyed by field or as a list of fields in the
|
|
557
|
+
* order they apply.
|
|
558
|
+
*
|
|
559
|
+
* Both forms order by the first field, break a tie on the second, and carry on
|
|
560
|
+
* that way. Prefer the list where the order of the fields matters, because
|
|
561
|
+
* JavaScript moves an all-digit key such as `2024` to the front of an object
|
|
562
|
+
* and the list keeps the order you wrote.
|
|
563
|
+
*
|
|
564
|
+
* @public
|
|
565
|
+
*/
|
|
566
|
+
type SortSpec = Record<string, 'asc' | 'desc'> | readonly SortField[];
|
|
567
|
+
/**
|
|
568
|
+
* Everything {@link Narsil.query} accepts.
|
|
569
|
+
*
|
|
570
|
+
* Set `term` for keyword search, `vector` for similarity search, and `mode`
|
|
571
|
+
* when you want both. The engine matches nothing for a query carrying neither
|
|
572
|
+
* of them, so page through an index with {@link Narsil.listDocuments}
|
|
573
|
+
* instead.
|
|
574
|
+
*
|
|
575
|
+
* @public
|
|
576
|
+
*/
|
|
577
|
+
interface QueryParams {
|
|
578
|
+
/**
|
|
579
|
+
* The engine analyses this text with the index's language module and searches
|
|
580
|
+
* for the terms that result. Words inside double quotes form a phrase, which
|
|
581
|
+
* a document has to hold side by side and in that order inside one field. The
|
|
582
|
+
* engine throws `SEARCH_INVALID_PHRASE` for a phrase of more than 32 words, for
|
|
583
|
+
* more than 32 phrases, and for a phrase on an index with `trackPositions` off.
|
|
584
|
+
* It throws `SEARCH_PHRASE_NOT_READY` while an index with a `string[]` field
|
|
585
|
+
* waits for a rebuild.
|
|
586
|
+
*/
|
|
587
|
+
term?: string;
|
|
588
|
+
/** The engine searches the term in these fields, and in every text field in the schema by default. */
|
|
589
|
+
fields?: string[];
|
|
590
|
+
/**
|
|
591
|
+
* The engine scores only the documents that pass this filter. It throws
|
|
592
|
+
* `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
|
|
593
|
+
* operator on a field of another type, such as `startsWith` on a number
|
|
594
|
+
* field.
|
|
595
|
+
*/
|
|
596
|
+
filters?: FilterExpression;
|
|
597
|
+
/**
|
|
598
|
+
* The engine multiplies the score from each named field by its weight. It
|
|
599
|
+
* throws `SEARCH_INVALID_FIELD` for any field other than a text field that
|
|
600
|
+
* the schema declares, and `CONFIG_INVALID` for a weight that is not a
|
|
601
|
+
* finite number.
|
|
602
|
+
*/
|
|
603
|
+
boost?: Record<string, number>;
|
|
604
|
+
/**
|
|
605
|
+
* These BM25 parameters score this search alone, and they override the
|
|
606
|
+
* index's parameters, so a `k1` here also overrides a `k1` that the index
|
|
607
|
+
* sets for a field. The engine validates them on every search, and it throws
|
|
608
|
+
* the same errors as {@link IndexConfig.bm25}, except `SEARCH_INVALID_FIELD`
|
|
609
|
+
* for a name in `fields` that is not a text field. They change no score on a
|
|
610
|
+
* vector search, and on a hybrid search they apply to the keyword ranking
|
|
611
|
+
* alone. A cursor pages only a search with the same parameters.
|
|
612
|
+
*/
|
|
613
|
+
bm25?: BM25Params;
|
|
614
|
+
/** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
|
|
615
|
+
scoring?: ScoringMode;
|
|
616
|
+
/**
|
|
617
|
+
* The engine drops any hit scoring below this value. It ranks with BM25,
|
|
618
|
+
* which has no fixed upper bound, so a floor that suits one index and one
|
|
619
|
+
* query can reject every hit in another.
|
|
620
|
+
*/
|
|
621
|
+
minScore?: number;
|
|
622
|
+
/**
|
|
623
|
+
* The engine keeps a document only where the document matches this many
|
|
624
|
+
* query terms, under the same `tolerance` and `prefixLength` that the search
|
|
625
|
+
* uses. One term is enough by default.
|
|
626
|
+
*/
|
|
627
|
+
termMatch?: TermMatchPolicy;
|
|
628
|
+
/**
|
|
629
|
+
* The engine matches an indexed term within this edit distance of a query
|
|
630
|
+
* term, so it finds a document for a query with a typo. It counts each
|
|
631
|
+
* Unicode code point as one character. Set an integer from 0 to 10.
|
|
632
|
+
*/
|
|
633
|
+
tolerance?: number;
|
|
634
|
+
/**
|
|
635
|
+
* The engine applies `tolerance` only to the indexed terms that share this
|
|
636
|
+
* many leading characters with the query term, or to the terms that start
|
|
637
|
+
* with the whole query term when the query term is shorter. Set an integer
|
|
638
|
+
* from 0 to 1,024; the default is 2.
|
|
639
|
+
*/
|
|
640
|
+
prefixLength?: number;
|
|
641
|
+
/**
|
|
642
|
+
* With this set, the engine treats the last query term as an unfinished
|
|
643
|
+
* word, so `secur` matches `security`. The engine matches that last term by
|
|
644
|
+
* its stem or by completing it, while `tolerance` applies only to the earlier
|
|
645
|
+
* terms, which have to match whole. The engine scores completions against a
|
|
646
|
+
* shared document frequency. It also ranks them below whole-word matches.
|
|
647
|
+
* The engine ignores this setting where `exact` is true, and the setting is
|
|
648
|
+
* false by default.
|
|
649
|
+
*/
|
|
650
|
+
prefix?: boolean;
|
|
651
|
+
/**
|
|
652
|
+
* With this set, the engine also matches each query word of three or more
|
|
653
|
+
* characters inside the longer words of every field whose type includes
|
|
654
|
+
* `partial`, so a search for `proof` matches a document with `waterproof`
|
|
655
|
+
* in such a field. The engine counts each Unicode code point as one
|
|
656
|
+
* character. It looks for the query word, before stemming, inside each word
|
|
657
|
+
* exactly as that word appears in a document.
|
|
658
|
+
*
|
|
659
|
+
* The engine adds at most 50 such words to a query, which it divides as
|
|
660
|
+
* evenly as it can among the query words. Within the share of each query
|
|
661
|
+
* word, it adds first the words that the most documents contain. It scores
|
|
662
|
+
* a match inside a longer word in proportion to the part of that word that
|
|
663
|
+
* the query word makes up, so it scores such a match below a whole-word
|
|
664
|
+
* match at the same frequency in a field of the same length. With
|
|
665
|
+
* `highlight`, it tags each whole word that contains a query word in a
|
|
666
|
+
* searched `partial` field.
|
|
667
|
+
*
|
|
668
|
+
* The engine applies no `tolerance` to these matches. It ignores this
|
|
669
|
+
* setting where `exact` is true or where the searched fields include no
|
|
670
|
+
* `partial` field. Where the setting is absent, the engine treats it as
|
|
671
|
+
* false, while it throws `CONFIG_INVALID` for any value other than `true`
|
|
672
|
+
* or `false`.
|
|
673
|
+
*/
|
|
674
|
+
partialWords?: boolean;
|
|
675
|
+
/**
|
|
676
|
+
* With this set, the engine matches each query term only against an equal
|
|
677
|
+
* indexed term, so it turns off fuzzy matching, prefix completion,
|
|
678
|
+
* partial-word matching, and synonyms. The engine still stems the query, because the
|
|
679
|
+
* index stores stemmed terms, so a search for `running` matches a document
|
|
680
|
+
* that contains `runs` through the stem that both words share.
|
|
681
|
+
*/
|
|
682
|
+
exact?: boolean;
|
|
683
|
+
/**
|
|
684
|
+
* The engine counts the values of these fields across the matching
|
|
685
|
+
* documents, and each entry sets how it cuts and sorts that field's counts.
|
|
686
|
+
* For a field outside the schema, it counts the values that the documents
|
|
687
|
+
* store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
|
|
688
|
+
* field.
|
|
689
|
+
*/
|
|
690
|
+
facets?: FacetConfig;
|
|
691
|
+
/**
|
|
692
|
+
* The engine sorts the hits by the values of these fields, in place of the
|
|
693
|
+
* relevance ranking. Pass an object keyed by field, or a list of fields in
|
|
694
|
+
* the order that the engine compares them. The engine sorts by a `number`,
|
|
695
|
+
* `boolean`, or `enum` field, by a text field whose type includes
|
|
696
|
+
* `sortable`, or by a list of any of these, which it reduces to one value by
|
|
697
|
+
* the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
|
|
698
|
+
* `geopoint` or a vector field, because neither type has an order. It throws
|
|
699
|
+
* the same code for a sort on any other text field, since the engine keeps
|
|
700
|
+
* up to the first 512 code points of every document's value in memory to
|
|
701
|
+
* sort by a text field. The engine orders hybrid results by fusion, so it
|
|
702
|
+
* throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
|
|
703
|
+
* that code for a direction other than `asc` and `desc`.
|
|
704
|
+
*/
|
|
705
|
+
sort?: SortSpec;
|
|
706
|
+
/** These settings collapse the hits into groups by field value. */
|
|
707
|
+
group?: GroupConfig;
|
|
708
|
+
/**
|
|
709
|
+
* The query returns this many hits, and 10 by default. Pass 0 to read the
|
|
710
|
+
* match count with no hits. The engine reads a value below 0 as 0. It falls
|
|
711
|
+
* back to the default for `NaN` and for an infinite value, so a page size
|
|
712
|
+
* that you compute from user input never fails the query.
|
|
713
|
+
*/
|
|
714
|
+
limit?: number;
|
|
715
|
+
/** The query skips this many hits before returning. A deep offset costs more than a cursor. */
|
|
716
|
+
offset?: number;
|
|
717
|
+
/** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
|
|
718
|
+
searchAfter?: string;
|
|
719
|
+
/** These settings name the fields that come back with highlighted snippets. */
|
|
720
|
+
highlight?: HighlightConfig;
|
|
721
|
+
/** These documents take fixed positions, ahead of the ranking. */
|
|
722
|
+
pinned?: Array<{
|
|
723
|
+
/** The engine places the document with this id. */
|
|
724
|
+
docId: string;
|
|
725
|
+
/** The document takes this place in the results, counting from zero. */
|
|
726
|
+
position: number;
|
|
727
|
+
}>;
|
|
728
|
+
/** This picks which engine answers the query. Keyword search runs by default. */
|
|
729
|
+
mode?: SearchMode;
|
|
730
|
+
/** These vector-search inputs are required in `vector` and `hybrid` mode. */
|
|
731
|
+
vector?: VectorQueryConfig;
|
|
732
|
+
/** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
|
|
733
|
+
hybrid?: HybridConfig;
|
|
734
|
+
/**
|
|
735
|
+
* These settings reorder the top hits with a rerank adapter, such as a
|
|
736
|
+
* cross-encoder, after the keyword, vector, or hybrid ranking. The count
|
|
737
|
+
* matches the count of the same query without `rerank`, while the facets
|
|
738
|
+
* and the groups come from the first ranking. The engine throws
|
|
739
|
+
* `SEARCH_INVALID_MODE` for a query that also sets a sort, and
|
|
740
|
+
* `RERANK_FAILED` where the adapter fails or outlasts the engine's
|
|
741
|
+
* `rerankTimeout`.
|
|
742
|
+
*/
|
|
743
|
+
rerank?: RerankConfig;
|
|
744
|
+
/**
|
|
745
|
+
* Setting this returns relevance scores on a sorted query. A query that
|
|
746
|
+
* names a sort ranks by sort values alone and computes no scores, so its
|
|
747
|
+
* hits carry none until this restores them. A query without a sort ignores
|
|
748
|
+
* this and always carries scores.
|
|
749
|
+
*/
|
|
750
|
+
includeScores?: boolean;
|
|
751
|
+
/** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
|
|
752
|
+
includeScoreComponents?: boolean;
|
|
753
|
+
/** This chooses how much of each stored document comes back, and the whole document by default. */
|
|
754
|
+
document?: DocumentProjection;
|
|
755
|
+
}
|
|
756
|
+
/**
|
|
757
|
+
* How much of a stored document each hit carries back.
|
|
758
|
+
*
|
|
759
|
+
* Pass `false` when the ids and scores are all you need, and every hit's
|
|
760
|
+
* `document` is then an empty object. Pass `include` to keep named fields
|
|
761
|
+
* alone, or `exclude` to drop named fields and keep the rest; naming both
|
|
762
|
+
* keeps the included fields and then drops the excluded ones from those. Use
|
|
763
|
+
* dots to name a nested field, so `author.name` addresses the `name` inside
|
|
764
|
+
* `author`, and a name that matches no field changes nothing.
|
|
765
|
+
*
|
|
766
|
+
* Drop a vector field on a similarity search, because the engine otherwise
|
|
767
|
+
* reads every hit's vector back out of the index and writes it into the
|
|
768
|
+
* response.
|
|
769
|
+
*
|
|
770
|
+
* @public
|
|
771
|
+
*/
|
|
772
|
+
type DocumentProjection = boolean | {
|
|
773
|
+
/** Names the fields to keep, so every field left out of this list is dropped. */
|
|
774
|
+
include?: string[];
|
|
775
|
+
/** Names the fields to drop, so every other field is kept. */
|
|
776
|
+
exclude?: string[];
|
|
777
|
+
};
|
|
778
|
+
/**
|
|
779
|
+
* Fields a query counts values for, keyed by field name.
|
|
780
|
+
*
|
|
781
|
+
* @public
|
|
782
|
+
*/
|
|
783
|
+
interface FacetConfig {
|
|
784
|
+
/** Each key names a field the query counts values for. */
|
|
785
|
+
[field: string]: {
|
|
786
|
+
/** The engine returns this many values for the field, in the order of `sort`. An engine returns every value where you leave this out, while a cluster returns 10, or every range of a field that sets `ranges`. */
|
|
787
|
+
limit?: number;
|
|
788
|
+
/** The engine orders the returned values by their count, putting the highest first under `'desc'`, which is the default, and the lowest first under `'asc'`. Under `'asc'`, each cluster node sends the count of up to 10,000 values of the field, so the lowest counts are exact wherever no node holds more values than that. */
|
|
789
|
+
sort?: 'asc' | 'desc';
|
|
790
|
+
/** The engine counts a numeric field's matches into these ranges, with one count for each range. A cluster search counts up to 1,000 ranges on a field and throws `CONFIG_INVALID` for more. */
|
|
791
|
+
ranges?: Array<{
|
|
792
|
+
/** The range starts at this value. */
|
|
793
|
+
from: number;
|
|
794
|
+
/** The range ends at this value. */
|
|
795
|
+
to: number;
|
|
796
|
+
}>;
|
|
797
|
+
};
|
|
798
|
+
}
|
|
799
|
+
/**
|
|
800
|
+
* How a query collapses its hits into groups.
|
|
801
|
+
*
|
|
802
|
+
* @public
|
|
803
|
+
*/
|
|
804
|
+
interface GroupConfig {
|
|
805
|
+
/** The values of these fields define a group, and several fields group by their combination. */
|
|
806
|
+
fields: string[];
|
|
807
|
+
/** The engine returns this many hits from each group, best first, and one hit where you leave this out. */
|
|
808
|
+
maxPerGroup?: number;
|
|
809
|
+
/** The engine returns this many groups, best first, and every group where you leave this out. */
|
|
810
|
+
limit?: number;
|
|
811
|
+
/**
|
|
812
|
+
* The engine folds every hit of each group into one value, such as a sum or
|
|
813
|
+
* an average, including the hits beyond `maxPerGroup`. In cluster mode the
|
|
814
|
+
* coordinator fetches up to 10,000 hits of each group to fold.
|
|
815
|
+
*/
|
|
816
|
+
reduce?: GroupReducer;
|
|
817
|
+
}
|
|
818
|
+
/**
|
|
819
|
+
* Folds the hits of one group into a single value.
|
|
820
|
+
*
|
|
821
|
+
* @public
|
|
822
|
+
*/
|
|
823
|
+
type GroupReducer = {
|
|
824
|
+
/**
|
|
825
|
+
* Folds one hit into the running value.
|
|
826
|
+
*
|
|
827
|
+
* @param accumulator - What the previous call returned, or what
|
|
828
|
+
* `initialValue` produced for the first hit.
|
|
829
|
+
* @param doc - The hit's stored document.
|
|
830
|
+
* @param score - The hit's relevance score.
|
|
831
|
+
* @returns The new running value.
|
|
832
|
+
*/
|
|
833
|
+
reducer: (accumulator: unknown, doc: AnyDocument, score: number) => unknown;
|
|
834
|
+
/** Produces the starting value for each group. The engine calls it once per group. */
|
|
835
|
+
initialValue: () => unknown;
|
|
836
|
+
};
|
|
837
|
+
/**
|
|
838
|
+
* This configuration names the fields that receive highlighted snippets. It
|
|
839
|
+
* also sets how the engine marks those snippets up.
|
|
840
|
+
*
|
|
841
|
+
* The engine analyses the text of each returned field again to tag every word
|
|
842
|
+
* that it matched, so it tags the same words whatever the index's
|
|
843
|
+
* `trackPositions` setting is. It tags a word whose stem equals a query stem,
|
|
844
|
+
* and a word within the query's `tolerance` of a query stem. For a `prefix`
|
|
845
|
+
* query, it tags a word for the last query term only when that word completes
|
|
846
|
+
* the term or shares its stem.
|
|
847
|
+
*
|
|
848
|
+
* @public
|
|
849
|
+
*/
|
|
850
|
+
interface HighlightConfig {
|
|
851
|
+
/** The engine highlights these fields. */
|
|
852
|
+
fields: string[];
|
|
853
|
+
/** The engine writes this before each match, and writes `<mark>` by default. */
|
|
854
|
+
preTag?: string;
|
|
855
|
+
/** The engine writes this after each match, and writes `</mark>` by default. */
|
|
856
|
+
postTag?: string;
|
|
857
|
+
/**
|
|
858
|
+
* The engine takes this many characters of the field around the densest run
|
|
859
|
+
* of matches, 200 by default. It returns a snippet longer than that number,
|
|
860
|
+
* because it then adds the opening and closing tags, and an ellipsis at each
|
|
861
|
+
* end where it cuts the field.
|
|
862
|
+
*/
|
|
863
|
+
maxSnippetLength?: number;
|
|
864
|
+
}
|
|
2
865
|
|
|
3
866
|
/**
|
|
4
867
|
* Every code a {@link NarsilError} carries, grouped by the part of the engine
|
|
@@ -35,6 +898,28 @@ declare const ErrorCodes: {
|
|
|
35
898
|
readonly PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH";
|
|
36
899
|
readonly PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT";
|
|
37
900
|
readonly PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED";
|
|
901
|
+
readonly PERSISTENCE_DEPENDENCY_MISSING: "PERSISTENCE_DEPENDENCY_MISSING";
|
|
902
|
+
readonly BACKUP_NOT_FOUND: "BACKUP_NOT_FOUND";
|
|
903
|
+
readonly BACKUP_ALREADY_EXISTS: "BACKUP_ALREADY_EXISTS";
|
|
904
|
+
readonly BACKUP_DAMAGED: "BACKUP_DAMAGED";
|
|
905
|
+
readonly BACKUP_DURABILITY_REQUIRED: "BACKUP_DURABILITY_REQUIRED";
|
|
906
|
+
readonly BACKUP_IN_PROGRESS: "BACKUP_IN_PROGRESS";
|
|
907
|
+
readonly BACKUP_STORE_CLAIMED: "BACKUP_STORE_CLAIMED";
|
|
908
|
+
readonly BACKUP_STORE_NOT_CONFIGURED: "BACKUP_STORE_NOT_CONFIGURED";
|
|
909
|
+
readonly BACKUP_NOT_READY: "BACKUP_NOT_READY";
|
|
910
|
+
readonly SYNC_DURABILITY_REQUIRED: "SYNC_DURABILITY_REQUIRED";
|
|
911
|
+
readonly SYNC_BACKUP_STORE_REQUIRED: "SYNC_BACKUP_STORE_REQUIRED";
|
|
912
|
+
readonly SYNC_NOT_READY: "SYNC_NOT_READY";
|
|
913
|
+
readonly SYNC_NOT_ENABLED: "SYNC_NOT_ENABLED";
|
|
914
|
+
readonly SYNC_SNAPSHOT_PREPARING: "SYNC_SNAPSHOT_PREPARING";
|
|
915
|
+
readonly CHANGES_DURABILITY_REQUIRED: "CHANGES_DURABILITY_REQUIRED";
|
|
916
|
+
readonly CHANGES_BACKUP_STORE_REQUIRED: "CHANGES_BACKUP_STORE_REQUIRED";
|
|
917
|
+
readonly CHANGES_NOT_READY: "CHANGES_NOT_READY";
|
|
918
|
+
readonly CHANGES_NOT_ENABLED: "CHANGES_NOT_ENABLED";
|
|
919
|
+
readonly CHANGES_PREVIOUS_DOCUMENT_REQUIRED: "CHANGES_PREVIOUS_DOCUMENT_REQUIRED";
|
|
920
|
+
readonly CHANGES_EXPORT_PREPARING: "CHANGES_EXPORT_PREPARING";
|
|
921
|
+
readonly CHANGES_INVALID_POSITIONS: "CHANGES_INVALID_POSITIONS";
|
|
922
|
+
readonly QUERY_SUGGESTIONS_NOT_ENABLED: "QUERY_SUGGESTIONS_NOT_ENABLED";
|
|
38
923
|
readonly SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD";
|
|
39
924
|
readonly VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH";
|
|
40
925
|
readonly SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER";
|
|
@@ -42,11 +927,25 @@ declare const ErrorCodes: {
|
|
|
42
927
|
readonly SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR";
|
|
43
928
|
readonly SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED";
|
|
44
929
|
readonly SEARCH_WORK_CAP_EXCEEDED: "SEARCH_WORK_CAP_EXCEEDED";
|
|
930
|
+
/**
|
|
931
|
+
* An engine fault: a write changed the index during a search that held every
|
|
932
|
+
* write, so the search could not answer from one state. A correct engine
|
|
933
|
+
* never raises it, and retrying the request does not help.
|
|
934
|
+
*/
|
|
935
|
+
readonly SEARCH_STATE_MOVED: "SEARCH_STATE_MOVED";
|
|
936
|
+
readonly SEARCH_INVALID_PHRASE: "SEARCH_INVALID_PHRASE";
|
|
937
|
+
readonly SEARCH_PHRASE_NOT_READY: "SEARCH_PHRASE_NOT_READY";
|
|
938
|
+
readonly BM25_NOT_READY: "BM25_NOT_READY";
|
|
45
939
|
readonly LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED";
|
|
46
940
|
readonly ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH";
|
|
47
941
|
readonly ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC";
|
|
48
942
|
readonly PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED";
|
|
49
943
|
readonly RESTORE_MEMORY_EXCEEDED: "RESTORE_MEMORY_EXCEEDED";
|
|
944
|
+
readonly MEMORY_WRITE_BLOCKED: "MEMORY_WRITE_BLOCKED";
|
|
945
|
+
readonly ANALYSIS_CHANGE_REPLACED: "ANALYSIS_CHANGE_REPLACED";
|
|
946
|
+
readonly ANALYSIS_CHANGE_NOT_READY: "ANALYSIS_CHANGE_NOT_READY";
|
|
947
|
+
readonly ANALYSIS_GENERATION_MISSING: "ANALYSIS_GENERATION_MISSING";
|
|
948
|
+
readonly ANALYSIS_REBUILD_MEMORY_EXCEEDED: "ANALYSIS_REBUILD_MEMORY_EXCEEDED";
|
|
50
949
|
readonly EMBEDDING_FAILED: "EMBEDDING_FAILED";
|
|
51
950
|
readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
|
|
52
951
|
readonly EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE";
|
|
@@ -59,6 +958,7 @@ declare const ErrorCodes: {
|
|
|
59
958
|
readonly QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE";
|
|
60
959
|
readonly QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT";
|
|
61
960
|
readonly QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA";
|
|
961
|
+
readonly SEARCH_CONTEXT_MISSING: "SEARCH_CONTEXT_MISSING";
|
|
62
962
|
readonly CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED";
|
|
63
963
|
readonly CLUSTER_WRITE_BLOCKED: "CLUSTER_WRITE_BLOCKED";
|
|
64
964
|
readonly ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES";
|
|
@@ -70,11 +970,17 @@ declare const ErrorCodes: {
|
|
|
70
970
|
readonly NODE_NOT_JOINED: "NODE_NOT_JOINED";
|
|
71
971
|
readonly NODE_NOT_READY: "NODE_NOT_READY";
|
|
72
972
|
readonly NODE_NOT_CONTROLLER: "NODE_NOT_CONTROLLER";
|
|
973
|
+
readonly NODE_VERSION_INCOMPATIBLE: "NODE_VERSION_INCOMPATIBLE";
|
|
73
974
|
readonly COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING";
|
|
975
|
+
readonly COORDINATOR_AUTH_FAILED: "COORDINATOR_AUTH_FAILED";
|
|
976
|
+
readonly COORDINATOR_UNAVAILABLE: "COORDINATOR_UNAVAILABLE";
|
|
74
977
|
readonly TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING";
|
|
978
|
+
readonly NATIVE_DEPENDENCY_MISSING: "NATIVE_DEPENDENCY_MISSING";
|
|
75
979
|
readonly REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID";
|
|
76
980
|
readonly REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED";
|
|
77
981
|
readonly REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED";
|
|
982
|
+
readonly REPLICATION_OUTCOME_UNKNOWN: "REPLICATION_OUTCOME_UNKNOWN";
|
|
983
|
+
readonly REPLICATION_WRITE_CONFLICT: "REPLICATION_WRITE_CONFLICT";
|
|
78
984
|
readonly REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL";
|
|
79
985
|
readonly REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT";
|
|
80
986
|
readonly REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT";
|
|
@@ -150,8 +1056,10 @@ type ServerErrorCode = (typeof ServerErrorCodes)[keyof typeof ServerErrorCodes];
|
|
|
150
1056
|
* a server, or where the caller cannot read the answer.
|
|
151
1057
|
*
|
|
152
1058
|
* The HTTP client raises the first five. The React bindings raise
|
|
153
|
-
* `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook.
|
|
154
|
-
*
|
|
1059
|
+
* `CLIENT_UNEXPECTED_ERROR` alone, which reports a fault inside a hook. A
|
|
1060
|
+
* synced device raises `SYNC_ANALYSIS_UNAVAILABLE` before it downloads a
|
|
1061
|
+
* snapshot whose language, tokeniser, or stop words it has not registered,
|
|
1062
|
+
* and it keeps its copy of the index. No server sends any of them, so a failure under one means the exchange broke
|
|
155
1063
|
* before the operation ran. `STATUS_BY_CODE` in `src/server/errors.ts`
|
|
156
1064
|
* therefore maps none of them, because no request can arrive under one and no
|
|
157
1065
|
* HTTP status belongs to one.
|
|
@@ -165,6 +1073,7 @@ declare const ClientErrorCodes: {
|
|
|
165
1073
|
readonly CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE";
|
|
166
1074
|
readonly CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT";
|
|
167
1075
|
readonly CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR";
|
|
1076
|
+
readonly SYNC_ANALYSIS_UNAVAILABLE: "SYNC_ANALYSIS_UNAVAILABLE";
|
|
168
1077
|
};
|
|
169
1078
|
/**
|
|
170
1079
|
* Any one of the codes in {@link ClientErrorCodes}.
|
|
@@ -222,230 +1131,13 @@ declare class NarsilError extends Error {
|
|
|
222
1131
|
* that the constructor writes, so it returns true for an error from any entry
|
|
223
1132
|
* point.
|
|
224
1133
|
*
|
|
225
|
-
* @param value - The value that a `catch` block receives.
|
|
226
|
-
* @returns True where the value holds a code in {@link NarsilError.code}.
|
|
227
|
-
*
|
|
228
|
-
* @public
|
|
229
|
-
*/
|
|
230
|
-
declare function isNarsilError(value: unknown): value is NarsilError;
|
|
231
|
-
|
|
232
|
-
/**
|
|
233
|
-
* What {@link Narsil.query} returns: the ranked hits and everything the query
|
|
234
|
-
* asked for alongside them.
|
|
235
|
-
*
|
|
236
|
-
* @typeParam T - Shape of the stored documents, which flows through to each
|
|
237
|
-
* hit's `document`.
|
|
238
|
-
*
|
|
239
|
-
* @public
|
|
240
|
-
*/
|
|
241
|
-
interface QueryResult<T = AnyDocument> {
|
|
242
|
-
/** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
|
|
243
|
-
hits: Array<Hit<T>>;
|
|
244
|
-
/**
|
|
245
|
-
* This many documents match in total, before the engine applies `limit`
|
|
246
|
-
* and `offset`. For a keyword search the engine counts every match. For a
|
|
247
|
-
* vector search it counts every vector that passes the query's filter and
|
|
248
|
-
* its `similarity` floor, which is every vector in the field where the query
|
|
249
|
-
* sets neither of them. The engine also counts each pinned document that
|
|
250
|
-
* the query does not match, since it places that document among the hits.
|
|
251
|
-
*/
|
|
252
|
-
count: number;
|
|
253
|
-
/**
|
|
254
|
-
* `count` holds the exact number of matches where this is true, and a
|
|
255
|
-
* number at or below the true total where it is false. Where a query sets a
|
|
256
|
-
* `similarity` floor on a vector field that holds a graph, the engine
|
|
257
|
-
* counts only the vectors that it fetches, because it compares the query
|
|
258
|
-
* with only a fraction of that field's vectors. For a hybrid query the
|
|
259
|
-
* engine fuses two rankings, so the count is exact only where each of those
|
|
260
|
-
* rankings contains every matching document. Where you pin a document from
|
|
261
|
-
* outside the hits that the engine fetches, the engine reports true only
|
|
262
|
-
* where it holds every match of the query, because only then can it test
|
|
263
|
-
* whether the query matches that document.
|
|
264
|
-
*/
|
|
265
|
-
countExact: boolean;
|
|
266
|
-
/** The engine spent this many milliseconds on the search. */
|
|
267
|
-
elapsed: number;
|
|
268
|
-
/** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
|
|
269
|
-
cursor?: string;
|
|
270
|
-
/** These facet counts are keyed by the field each facet was asked for. */
|
|
271
|
-
facets?: Record<string, FacetResult>;
|
|
272
|
-
/** These groups arrive when the query asked for grouping. */
|
|
273
|
-
groups?: GroupResult[];
|
|
274
|
-
/** This turns true when the index's terms came from an older analysis than its language module produces now. */
|
|
275
|
-
analysisStale?: boolean;
|
|
276
|
-
/** The search read this much of the index, which is how you spot a degraded answer. */
|
|
277
|
-
coverage: QueryCoverage;
|
|
278
|
-
}
|
|
279
|
-
/**
|
|
280
|
-
* How much of an index one search read, which is what you check before you
|
|
281
|
-
* trust a count or a ranking.
|
|
282
|
-
*
|
|
283
|
-
* An embedded engine reads every partition it holds, so `queriedPartitions`
|
|
284
|
-
* matches `totalPartitions` there and the other two stay zero. A search across
|
|
285
|
-
* a cluster may find a node slow or unreachable, which it counts here while
|
|
286
|
-
* still returning the hits the other nodes gave it.
|
|
287
|
-
*
|
|
288
|
-
* @public
|
|
289
|
-
*/
|
|
290
|
-
interface QueryCoverage {
|
|
291
|
-
/** The search should have read this many partitions. */
|
|
292
|
-
totalPartitions: number;
|
|
293
|
-
/** The search read this many of them. */
|
|
294
|
-
queriedPartitions: number;
|
|
295
|
-
/** The search counts a partition here when the node holding it took longer than the query allowed. */
|
|
296
|
-
timedOutPartitions: number;
|
|
297
|
-
/** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
|
|
298
|
-
failedPartitions: number;
|
|
299
|
-
}
|
|
300
|
-
/**
|
|
301
|
-
* One matching document, with the score that ranked it.
|
|
302
|
-
*
|
|
303
|
-
* @typeParam T - Shape of the stored document.
|
|
304
|
-
*
|
|
305
|
-
* @public
|
|
306
|
-
*/
|
|
307
|
-
interface Hit<T = AnyDocument> {
|
|
308
|
-
/** The document is stored under this id. */
|
|
309
|
-
id: string;
|
|
310
|
-
/**
|
|
311
|
-
* This score ranked the hit. Scores compare within one result set, never
|
|
312
|
-
* across searches. A sorted query ranks by sort values instead and carries
|
|
313
|
-
* no score unless it sets `includeScores`.
|
|
314
|
-
*/
|
|
315
|
-
score?: number;
|
|
316
|
-
/** This is the stored document. */
|
|
317
|
-
document: T;
|
|
318
|
-
/** These are the parts the score was built from, which arrive when the query asked for them. */
|
|
319
|
-
scoreComponents?: ScoreComponents;
|
|
320
|
-
/** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
|
|
321
|
-
highlights?: Record<string, HighlightMatch>;
|
|
322
|
-
}
|
|
323
|
-
/**
|
|
324
|
-
* The numbers BM25 combined into one hit's score, which is what you read when
|
|
325
|
-
* a ranking surprises you.
|
|
326
|
-
*
|
|
327
|
-
* @public
|
|
328
|
-
*/
|
|
329
|
-
interface ScoreComponents {
|
|
330
|
-
/**
|
|
331
|
-
* Each query term appears in one field of this document this many times,
|
|
332
|
-
* under a key of `field:term`. A term that appears in two fields therefore
|
|
333
|
-
* has two entries here, while the keys of {@link ScoreComponents.idf} hold
|
|
334
|
-
* the bare term.
|
|
335
|
-
*/
|
|
336
|
-
termFrequencies: Record<string, number>;
|
|
337
|
-
/** Each field the query searched holds this many tokens, keyed by field. */
|
|
338
|
-
fieldLengths: Record<string, number>;
|
|
339
|
-
/** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
|
|
340
|
-
idf: Record<string, number>;
|
|
341
|
-
}
|
|
342
|
-
/**
|
|
343
|
-
* A highlighted field, ready to render.
|
|
344
|
-
*
|
|
345
|
-
* @public
|
|
346
|
-
*/
|
|
347
|
-
interface HighlightMatch {
|
|
348
|
-
/** This is the field's text around the match, wrapped in the query's tags. */
|
|
349
|
-
snippet: string;
|
|
350
|
-
/**
|
|
351
|
-
* Each range gives the start and the end of one match in the original field,
|
|
352
|
-
* so you can render the highlight yourself. Where the snippet covers part of
|
|
353
|
-
* the field alone, the engine lists only the matches that the snippet
|
|
354
|
-
* displays. Every offset is a character count from the start of the original
|
|
355
|
-
* field, whatever the snippet contains.
|
|
356
|
-
*/
|
|
357
|
-
positions: Array<{
|
|
358
|
-
start: number;
|
|
359
|
-
end: number;
|
|
360
|
-
}>;
|
|
361
|
-
}
|
|
362
|
-
/**
|
|
363
|
-
* Counts for one faceted field.
|
|
364
|
-
*
|
|
365
|
-
* @public
|
|
366
|
-
*/
|
|
367
|
-
interface FacetResult {
|
|
368
|
-
/** This many documents match per value, keyed by value. */
|
|
369
|
-
values: Record<string, number>;
|
|
370
|
-
/** This is the number of entries in `values`, which is at most the facet's `limit`. */
|
|
371
|
-
count: number;
|
|
372
|
-
/**
|
|
373
|
-
* Every count in `values` is at most this far below its true count. A value
|
|
374
|
-
* that the engine leaves out of `values` because of `limit` has a true
|
|
375
|
-
* count of at most this figure too. Where the engine counts a field on one
|
|
376
|
-
* thread, it counts every value exactly, so this figure is the largest
|
|
377
|
-
* count that it leaves out. Where it splits the count across worker copies
|
|
378
|
-
* or cluster nodes, each of them returns only its own top values, so the
|
|
379
|
-
* merged count of a value that is common overall but rare on one of them
|
|
380
|
-
* can lack the matches on that one. A bound of 0 means that `values` holds
|
|
381
|
-
* every matching value, each with its exact count.
|
|
382
|
-
*/
|
|
383
|
-
errorBound: number;
|
|
384
|
-
}
|
|
385
|
-
/**
|
|
386
|
-
* One group of hits, produced by a query that grouped its results.
|
|
387
|
-
*
|
|
388
|
-
* @public
|
|
389
|
-
*/
|
|
390
|
-
interface GroupResult {
|
|
391
|
-
/** Each grouping field holds this value for the group, keyed by field. */
|
|
392
|
-
values: Record<string, unknown>;
|
|
393
|
-
/** These hits fall in the group, cut to the query's `maxPerGroup`. */
|
|
394
|
-
hits: Array<Hit>;
|
|
395
|
-
/** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
|
|
396
|
-
reduced?: unknown;
|
|
397
|
-
/** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
|
|
398
|
-
reducerError?: string;
|
|
399
|
-
}
|
|
400
|
-
/**
|
|
401
|
-
* What {@link Narsil.preflight} returns: how many documents a query matches,
|
|
402
|
-
* without building or ranking a single hit.
|
|
403
|
-
*
|
|
404
|
-
* @public
|
|
405
|
-
*/
|
|
406
|
-
interface PreflightResult {
|
|
407
|
-
/** The query matches this many documents. */
|
|
408
|
-
count: number;
|
|
409
|
-
/** `count` holds the exact number of matches where this is true, and a number at or below the true total where it is false, under the rule in {@link QueryResult.countExact}. */
|
|
410
|
-
countExact: boolean;
|
|
411
|
-
/** The count took this many milliseconds. */
|
|
412
|
-
elapsed: number;
|
|
413
|
-
/** This turns true when the index's terms came from an older analysis than its language module produces now. */
|
|
414
|
-
analysisStale?: boolean;
|
|
415
|
-
}
|
|
416
|
-
/**
|
|
417
|
-
* What a batch write returns. One bad document never abandons the rest, so
|
|
418
|
-
* read both lists.
|
|
419
|
-
*
|
|
420
|
-
* @public
|
|
421
|
-
*/
|
|
422
|
-
interface BatchResult {
|
|
423
|
-
/** The engine wrote the documents under these ids. */
|
|
424
|
-
succeeded: string[];
|
|
425
|
-
/** The engine rejected each of these documents, and each entry carries the error that rejected it. */
|
|
426
|
-
failed: Array<{
|
|
427
|
-
docId: string;
|
|
428
|
-
error: NarsilError;
|
|
429
|
-
}>;
|
|
430
|
-
}
|
|
431
|
-
/**
|
|
432
|
-
* What {@link Narsil.importDocumentExport} returns. The engine continues past each
|
|
433
|
-
* refused line, so read the refusals to learn which documents it skipped.
|
|
434
|
-
*
|
|
435
|
-
* @public
|
|
436
|
-
*/
|
|
437
|
-
interface DocumentImportResult {
|
|
438
|
-
/** The engine wrote this many documents, counting each one that it replaced. */
|
|
439
|
-
imported: number;
|
|
440
|
-
/** The engine refused this many lines in total. */
|
|
441
|
-
refusedCount: number;
|
|
442
|
-
/** 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. */
|
|
443
|
-
refused: Array<{
|
|
444
|
-
line: number;
|
|
445
|
-
code: NarsilErrorCode;
|
|
446
|
-
message: string;
|
|
447
|
-
}>;
|
|
448
|
-
}
|
|
1134
|
+
* @param value - The value that a `catch` block receives.
|
|
1135
|
+
* @returns True where the value holds a code in {@link NarsilError.code}.
|
|
1136
|
+
*
|
|
1137
|
+
* @public
|
|
1138
|
+
*/
|
|
1139
|
+
declare function isNarsilError(value: unknown): value is NarsilError;
|
|
1140
|
+
|
|
449
1141
|
/**
|
|
450
1142
|
* What {@link Narsil.getStats} returns about one index.
|
|
451
1143
|
*
|
|
@@ -466,10 +1158,47 @@ interface IndexStats {
|
|
|
466
1158
|
* when sizing host memory.
|
|
467
1159
|
*/
|
|
468
1160
|
estimatedMemoryBytes: number;
|
|
1161
|
+
/**
|
|
1162
|
+
* The files that the index's current checkpoint lists hold this many bytes:
|
|
1163
|
+
* the segment files of every partition, the vector files, and the graph
|
|
1164
|
+
* parts. The figure changes only when a checkpoint commits, so an unchanged
|
|
1165
|
+
* index reports the same size before and after a restart. A closed index
|
|
1166
|
+
* reports the size that its last checkpoint recorded, and an index that
|
|
1167
|
+
* saves nothing reports no figure. In a cluster, the figure covers the copy
|
|
1168
|
+
* of each partition that the stats call read.
|
|
1169
|
+
*/
|
|
1170
|
+
savedBytes?: number;
|
|
1171
|
+
/**
|
|
1172
|
+
* The index's write-ahead log and the history that it keeps for device sync
|
|
1173
|
+
* hold this many bytes. The figure grows with every write, and it falls when
|
|
1174
|
+
* the engine deletes log or history files. A closed index reports no figure,
|
|
1175
|
+
* and neither does an index that saves nothing.
|
|
1176
|
+
*/
|
|
1177
|
+
logBytes?: number;
|
|
1178
|
+
/**
|
|
1179
|
+
* A cluster adds up {@link IndexStats.savedBytes} over every copy of every
|
|
1180
|
+
* partition, which shows the disk space that the index takes across all of
|
|
1181
|
+
* its nodes. The figure is absent outside a cluster, and it is absent
|
|
1182
|
+
* whenever a copy fails to answer or reports no saved size.
|
|
1183
|
+
*/
|
|
1184
|
+
savedBytesOfEveryCopy?: number;
|
|
1185
|
+
/**
|
|
1186
|
+
* A cluster adds up {@link IndexStats.logBytes} over every copy of every
|
|
1187
|
+
* partition. The figure is absent outside a cluster, and it is absent
|
|
1188
|
+
* whenever a copy fails to answer or reports no log size.
|
|
1189
|
+
*/
|
|
1190
|
+
logBytesOfEveryCopy?: number;
|
|
469
1191
|
/** The index analyses text with this language module. */
|
|
470
1192
|
language: string;
|
|
471
1193
|
/** The index was created with this field layout. */
|
|
472
1194
|
schema: SchemaDefinition;
|
|
1195
|
+
/**
|
|
1196
|
+
* This many searches on this instance's main copy hold a state of the index
|
|
1197
|
+
* open right now. Each search holds one state from its start until it
|
|
1198
|
+
* answers, fails, or is cancelled, so the figure falls back to 0 once every
|
|
1199
|
+
* search has finished. A cluster reports no figure.
|
|
1200
|
+
*/
|
|
1201
|
+
heldSearchStates?: number;
|
|
473
1202
|
}
|
|
474
1203
|
/**
|
|
475
1204
|
* A summary of one index, as {@link Narsil.listIndexes} reports it.
|
|
@@ -510,913 +1239,636 @@ interface PartitionStatsResult {
|
|
|
510
1239
|
* include per-object overhead. Treat as an estimate, not a measurement.
|
|
511
1240
|
*/
|
|
512
1241
|
estimatedMemoryBytes: number;
|
|
513
|
-
}
|
|
514
|
-
/**
|
|
515
|
-
* What {@link Narsil.suggest} returns: the indexed terms that complete a
|
|
516
|
-
* prefix, ready to offer as you-type suggestions.
|
|
517
|
-
*
|
|
518
|
-
* @public
|
|
519
|
-
*/
|
|
520
|
-
interface SuggestResult {
|
|
521
|
-
/** These completions run most widely used first. */
|
|
522
|
-
terms: Array<{
|
|
523
|
-
/** This is the completed term, as the index holds it. */
|
|
524
|
-
term: string;
|
|
525
|
-
/** The term appears in this many documents, which is what ordered the list. */
|
|
526
|
-
documentFrequency: number;
|
|
527
|
-
}>;
|
|
528
|
-
/** The lookup took this many milliseconds. */
|
|
529
|
-
elapsed: number;
|
|
530
|
-
/** This turns true when the index's terms came from an older analysis than its language module produces now. */
|
|
531
|
-
analysisStale?: boolean;
|
|
532
|
-
}
|
|
533
|
-
/**
|
|
534
|
-
* The state of one vector field, and what maintenance would cost, as
|
|
535
|
-
* {@link Narsil.vectorMaintenanceStatus} reports it.
|
|
536
|
-
*
|
|
537
|
-
* Removing a vector leaves a tombstone in the graph, and enough of them slow a
|
|
538
|
-
* search down. Read this to decide when compaction earns its cost.
|
|
539
|
-
*
|
|
540
|
-
* @public
|
|
541
|
-
*/
|
|
542
|
-
interface VectorMaintenanceResult {
|
|
543
|
-
/** This describes the named vector field. */
|
|
544
|
-
fieldName: string;
|
|
545
1242
|
/**
|
|
546
|
-
*
|
|
547
|
-
*
|
|
548
|
-
* the
|
|
549
|
-
* exists yet.
|
|
1243
|
+
* The segment files that the index's current checkpoint lists for this
|
|
1244
|
+
* partition hold this many bytes. The vector files and graph parts belong to
|
|
1245
|
+
* the whole index, so only {@link IndexStats.savedBytes} counts them.
|
|
550
1246
|
*/
|
|
551
|
-
|
|
552
|
-
/**
|
|
553
|
-
|
|
554
|
-
/** This many vectors wait outside the graph, which a search scans one by one. */
|
|
555
|
-
bufferSize: number;
|
|
556
|
-
/** This stays true while a graph build runs. */
|
|
557
|
-
building: boolean;
|
|
558
|
-
/** {@link Narsil.compactVectors} would take about this many milliseconds. */
|
|
559
|
-
estimatedCompactMs: number;
|
|
560
|
-
/** {@link Narsil.optimizeVectors} would take about this many milliseconds. */
|
|
561
|
-
estimatedOptimizeMs: number;
|
|
562
|
-
}
|
|
563
|
-
/**
|
|
564
|
-
* One stored document, as {@link Narsil.listDocuments} returns it.
|
|
565
|
-
*
|
|
566
|
-
* @typeParam T - Shape of the stored document.
|
|
567
|
-
*
|
|
568
|
-
* @public
|
|
569
|
-
*/
|
|
570
|
-
interface ListedDocument<T = AnyDocument> {
|
|
571
|
-
/** The document is stored under this id. */
|
|
572
|
-
id: string;
|
|
573
|
-
/** This holds the stored document, cut down to what the projection kept. */
|
|
574
|
-
document: T;
|
|
575
|
-
}
|
|
576
|
-
/**
|
|
577
|
-
* What {@link Narsil.listDocuments} returns: one page of stored documents and
|
|
578
|
-
* the cursor that reaches the next one.
|
|
579
|
-
*
|
|
580
|
-
* @typeParam T - Shape of the stored documents.
|
|
581
|
-
*
|
|
582
|
-
* @public
|
|
583
|
-
*/
|
|
584
|
-
interface ListResult<T = AnyDocument> {
|
|
585
|
-
/** These documents make up the page, in ascending document-id order. */
|
|
586
|
-
documents: Array<ListedDocument<T>>;
|
|
587
|
-
/** This opaque cursor reaches the next page, and is null once the listing is finished. */
|
|
588
|
-
cursor: string | null;
|
|
589
|
-
/** The listing covers this many documents in total, and any filter narrows that count. */
|
|
590
|
-
total: number;
|
|
591
|
-
/** The engine spent this many milliseconds building the page. */
|
|
592
|
-
elapsed: number;
|
|
593
|
-
}
|
|
594
|
-
|
|
595
|
-
/**
|
|
596
|
-
* Compares one field against a value. Setting several keys narrows the match,
|
|
597
|
-
* because a document has to satisfy all of them.
|
|
598
|
-
*
|
|
599
|
-
* @public
|
|
600
|
-
*/
|
|
601
|
-
type ComparisonFilter = {
|
|
602
|
-
/** This matches a field equal to the value, or a list field where one element equals it. */
|
|
603
|
-
eq?: number | string | boolean;
|
|
1247
|
+
savedBytes?: number;
|
|
1248
|
+
/** This partition's write-ahead log files and device-sync history files hold this many bytes. */
|
|
1249
|
+
logBytes?: number;
|
|
604
1250
|
/**
|
|
605
|
-
*
|
|
606
|
-
*
|
|
607
|
-
*
|
|
1251
|
+
* A cluster adds up {@link PartitionStatsResult.savedBytes} over every copy
|
|
1252
|
+
* of this partition. The figure is absent outside a cluster, and it is
|
|
1253
|
+
* absent whenever a copy fails to answer or reports no saved size.
|
|
608
1254
|
*/
|
|
609
|
-
|
|
610
|
-
/**
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
/** This matches a field inside the inclusive range, given as `[low, high]`. */
|
|
619
|
-
between?: [number, number];
|
|
620
|
-
};
|
|
1255
|
+
savedBytesOfEveryCopy?: number;
|
|
1256
|
+
/**
|
|
1257
|
+
* A cluster adds up {@link PartitionStatsResult.logBytes} over every copy of
|
|
1258
|
+
* this partition. The figure is absent outside a cluster, and it is absent
|
|
1259
|
+
* whenever a copy fails to answer or reports no log size.
|
|
1260
|
+
*/
|
|
1261
|
+
logBytesOfEveryCopy?: number;
|
|
1262
|
+
}
|
|
1263
|
+
|
|
621
1264
|
/**
|
|
622
|
-
*
|
|
623
|
-
*
|
|
624
|
-
*
|
|
625
|
-
* On a `string[]`, `verbatim[]`, or `enum[]` field, the engine tests each
|
|
626
|
-
* element of the list on its own. A document passes `eq`, `in`, `startsWith`,
|
|
627
|
-
* `endsWith`, `contains`, `wildcard`, or `regex` when one element passes the
|
|
628
|
-
* test. However, a document passes `ne` or `nin` only when every element
|
|
629
|
-
* differs from the values.
|
|
630
|
-
*
|
|
631
|
-
* The engine applies the range tests `gt`, `gte`, `lt`, `lte`, and `between`
|
|
632
|
-
* to a single `string` or `verbatim` field whose type includes `sortable`. It
|
|
633
|
-
* throws `SEARCH_INVALID_FILTER` for a text range on any other field. It
|
|
634
|
-
* orders the values as a sort on the field does, so it compares their case
|
|
635
|
-
* folds first and compares their raw code points only where the folds are
|
|
636
|
-
* equal.
|
|
637
|
-
*
|
|
638
|
-
* A pattern field is a `verbatim` or `verbatim[]` field, or a `string` or
|
|
639
|
-
* `string[]` field whose type includes `pattern`. On a pattern field, the
|
|
640
|
-
* engine answers `eq`, `ne`, `in`, `nin`, `startsWith`, `endsWith`,
|
|
641
|
-
* `contains`, `wildcard`, and `regex` from the field's pattern index, and
|
|
642
|
-
* `caseFold` applies to each of those tests. The engine compares the code
|
|
643
|
-
* points of each value as they are stored, with no Unicode normalisation.
|
|
644
|
-
*
|
|
645
|
-
* On an `enum` or `enum[]` field, the engine answers `eq`, `ne`, `in`, `nin`,
|
|
646
|
-
* `startsWith`, and `endsWith` from the field's index of values. A `string` or
|
|
647
|
-
* `string[]` field whose type leaves out `pattern` keeps no index of whole
|
|
648
|
-
* values, so the engine throws `SEARCH_INVALID_FILTER` for those six tests,
|
|
649
|
-
* and for `matchesAny` and `containsAll`, on such a field.
|
|
650
|
-
*
|
|
651
|
-
* The engine also throws `SEARCH_INVALID_FILTER` in these cases:
|
|
1265
|
+
* What {@link Narsil.query} returns: the ranked hits and everything the query
|
|
1266
|
+
* asked for alongside them.
|
|
652
1267
|
*
|
|
653
|
-
* -
|
|
654
|
-
*
|
|
655
|
-
* - The text or the pattern of a test on a pattern field holds more than 1,024
|
|
656
|
-
* code points.
|
|
657
|
-
* - A literal test under `caseFold` has a text whose case fold holds more than
|
|
658
|
-
* 2,048 code points.
|
|
659
|
-
* - A `wildcard` or `regex` pattern breaks its syntax or one of its limits.
|
|
1268
|
+
* @typeParam T - Shape of the stored documents, which flows through to each
|
|
1269
|
+
* hit's `document`.
|
|
660
1270
|
*
|
|
661
1271
|
* @public
|
|
662
1272
|
*/
|
|
663
|
-
|
|
664
|
-
/**
|
|
665
|
-
|
|
666
|
-
/** This matches a value that comes before the text in sort order. */
|
|
667
|
-
lt?: string;
|
|
668
|
-
/** This matches a value equal to the text or after it in sort order. */
|
|
669
|
-
gte?: string;
|
|
670
|
-
/** This matches a value equal to the text or before it in sort order. */
|
|
671
|
-
lte?: string;
|
|
672
|
-
/** This matches a value inside the inclusive range in sort order, given as `[low, high]`. */
|
|
673
|
-
between?: [string, string];
|
|
674
|
-
/** This matches a field equal to any value in the list, which holds at most 65,536 values. */
|
|
675
|
-
in?: string[];
|
|
676
|
-
/** This matches a field that differs from every value in the list, which holds at most 65,536 values. */
|
|
677
|
-
nin?: string[];
|
|
678
|
-
/** This matches a field starting with the text. */
|
|
679
|
-
startsWith?: string;
|
|
680
|
-
/** This matches a field ending with the text. */
|
|
681
|
-
endsWith?: string;
|
|
682
|
-
/** This matches a pattern field whose value holds the text anywhere in it. */
|
|
683
|
-
contains?: string;
|
|
1273
|
+
interface QueryResult<T = AnyDocument> {
|
|
1274
|
+
/** These documents match, cut to the query's `limit`, best score first or in the query's sort order. */
|
|
1275
|
+
hits: Array<Hit<T>>;
|
|
684
1276
|
/**
|
|
685
|
-
* This
|
|
686
|
-
*
|
|
687
|
-
*
|
|
688
|
-
*
|
|
689
|
-
*
|
|
690
|
-
*
|
|
691
|
-
*
|
|
692
|
-
* The engine throws `SEARCH_INVALID_FILTER` for a pattern that ends in a
|
|
693
|
-
* `\` with no code point after it. It throws the same error for a pattern
|
|
694
|
-
* with more than 2,048 positions. Each `*`, each `?`, and each other code
|
|
695
|
-
* point counts as one position, except that under `caseFold` a code point
|
|
696
|
-
* counts once for each code point of its case fold.
|
|
1277
|
+
* This many documents match in total, before the engine applies `limit`
|
|
1278
|
+
* and `offset`. For a keyword search the engine counts every match. For a
|
|
1279
|
+
* vector search it counts every vector that passes the query's filter and
|
|
1280
|
+
* its `similarity` floor, which is every vector in the field where the query
|
|
1281
|
+
* sets neither of them. The engine also counts each pinned document that
|
|
1282
|
+
* the query does not match, since it places that document among the hits.
|
|
697
1283
|
*/
|
|
698
|
-
|
|
1284
|
+
count: number;
|
|
699
1285
|
/**
|
|
700
|
-
*
|
|
701
|
-
*
|
|
702
|
-
* the
|
|
703
|
-
*
|
|
704
|
-
*
|
|
705
|
-
*
|
|
706
|
-
*
|
|
707
|
-
*
|
|
708
|
-
*
|
|
709
|
-
*
|
|
710
|
-
* `.` matches any code point, including a line break.
|
|
711
|
-
*
|
|
712
|
-
* The matcher never backtracks, so it checks a value in at most as many
|
|
713
|
-
* steps as the value's code points multiplied by the pattern's positions.
|
|
714
|
-
*
|
|
715
|
-
* The engine throws `SEARCH_INVALID_FILTER` for any construct outside that
|
|
716
|
-
* syntax, such as a back-reference, a lookaround, a lazy repeat, or an inline
|
|
717
|
-
* flag. It throws the same error when the groups of a pattern nest more than
|
|
718
|
-
* 32 deep, when a count is above 2,048, and when a pattern holds more than
|
|
719
|
-
* 2,048 positions. When the operator of an HTTP server sets its `allowRegex`
|
|
720
|
-
* option to false, the server refuses every `regex` test.
|
|
1286
|
+
* `count` holds the exact number of matches where this is true, and a
|
|
1287
|
+
* number at or below the true total where it is false. Where a query sets a
|
|
1288
|
+
* `similarity` floor on a vector field that holds a graph, the engine
|
|
1289
|
+
* counts only the vectors that it fetches, because it compares the query
|
|
1290
|
+
* with only a fraction of that field's vectors. For a hybrid query the
|
|
1291
|
+
* engine fuses two rankings, so the count is exact only where each of those
|
|
1292
|
+
* rankings contains every matching document. Where you pin a document from
|
|
1293
|
+
* outside the hits that the engine fetches, the engine reports true only
|
|
1294
|
+
* where it holds every match of the query, because only then can it test
|
|
1295
|
+
* whether the query matches that document.
|
|
721
1296
|
*/
|
|
722
|
-
|
|
1297
|
+
countExact: boolean;
|
|
1298
|
+
/** The engine spent this many milliseconds on the search. */
|
|
1299
|
+
elapsed: number;
|
|
1300
|
+
/** This opaque cursor reaches the next page. Pass it back as `searchAfter`. */
|
|
1301
|
+
cursor?: string;
|
|
1302
|
+
/** These facet counts are keyed by the field each facet was asked for. */
|
|
1303
|
+
facets?: Record<string, FacetResult>;
|
|
1304
|
+
/** These groups arrive when the query asked for grouping. */
|
|
1305
|
+
groups?: GroupResult[];
|
|
1306
|
+
/** This turns true when the index's terms came from an older analysis than its language module produces now. */
|
|
1307
|
+
analysisStale?: boolean;
|
|
1308
|
+
/** The search read this much of the index, which is how you spot a degraded answer. */
|
|
1309
|
+
coverage: QueryCoverage;
|
|
1310
|
+
}
|
|
1311
|
+
/**
|
|
1312
|
+
* How much of an index one search read, which is what you check before you
|
|
1313
|
+
* trust a count or a ranking.
|
|
1314
|
+
*
|
|
1315
|
+
* An embedded engine reads every partition it holds, so `queriedPartitions`
|
|
1316
|
+
* matches `totalPartitions` there and the other two stay zero. A search across
|
|
1317
|
+
* a cluster may find a node slow or unreachable, which it counts here while
|
|
1318
|
+
* still returning the hits the other nodes gave it.
|
|
1319
|
+
*
|
|
1320
|
+
* @public
|
|
1321
|
+
*/
|
|
1322
|
+
interface QueryCoverage {
|
|
1323
|
+
/** The search should have read this many partitions. */
|
|
1324
|
+
totalPartitions: number;
|
|
1325
|
+
/** The search read this many of them. */
|
|
1326
|
+
queriedPartitions: number;
|
|
1327
|
+
/** The search counts a partition here when the node holding it took longer than the query allowed. */
|
|
1328
|
+
timedOutPartitions: number;
|
|
1329
|
+
/** The search counts a partition here when the node holding it returned an error, and when no active replica served it. */
|
|
1330
|
+
failedPartitions: number;
|
|
1331
|
+
}
|
|
1332
|
+
/**
|
|
1333
|
+
* One matching document, with the score that ranked it.
|
|
1334
|
+
*
|
|
1335
|
+
* @typeParam T - Shape of the stored document.
|
|
1336
|
+
*
|
|
1337
|
+
* @public
|
|
1338
|
+
*/
|
|
1339
|
+
interface Hit<T = AnyDocument> {
|
|
1340
|
+
/** The document is stored under this id. */
|
|
1341
|
+
id: string;
|
|
723
1342
|
/**
|
|
724
|
-
*
|
|
725
|
-
*
|
|
726
|
-
*
|
|
727
|
-
* `endsWith`, `contains`, `wildcard`, and `regex`.
|
|
728
|
-
*
|
|
729
|
-
* Under `caseFold`, a set that does not open with `^` can also match a
|
|
730
|
-
* sequence of code points. When a member that the set holds on its own folds
|
|
731
|
-
* to several code points, the set matches that whole fold, so `[ß]` matches
|
|
732
|
-
* `ss`.
|
|
1343
|
+
* This score ranked the hit. Scores compare within one result set, never
|
|
1344
|
+
* across searches. A sorted query ranks by sort values instead and carries
|
|
1345
|
+
* no score unless it sets `includeScores`.
|
|
733
1346
|
*/
|
|
734
|
-
|
|
1347
|
+
score?: number;
|
|
1348
|
+
/** This is the stored document. */
|
|
1349
|
+
document: T;
|
|
1350
|
+
/** These are the parts the score was built from, which arrive when the query asked for them. */
|
|
1351
|
+
scoreComponents?: ScoreComponents;
|
|
1352
|
+
/** These highlighted snippets are keyed by field, and arrive when the query asked for highlighting. */
|
|
1353
|
+
highlights?: Record<string, HighlightMatch>;
|
|
1354
|
+
}
|
|
1355
|
+
/**
|
|
1356
|
+
* The numbers BM25 combined into one hit's score, which is what you read when
|
|
1357
|
+
* a ranking surprises you.
|
|
1358
|
+
*
|
|
1359
|
+
* @public
|
|
1360
|
+
*/
|
|
1361
|
+
interface ScoreComponents {
|
|
735
1362
|
/**
|
|
736
|
-
*
|
|
737
|
-
*
|
|
738
|
-
*
|
|
739
|
-
*
|
|
740
|
-
* the engine counts the edits between the case folds of the value and the
|
|
741
|
-
* text. The tolerance applies to `eq` alone, so the other tests of the field
|
|
742
|
-
* still compare exactly.
|
|
743
|
-
*
|
|
744
|
-
* The engine takes its candidates from the pattern index, so the case fold
|
|
745
|
-
* of the text has to hold enough distinct runs of three code points. For a
|
|
746
|
-
* tolerance of `k`, the engine needs `k × (2 + f) + 1` runs, where `f` is
|
|
747
|
-
* the number of code points in the longest case fold among the text's code
|
|
748
|
-
* points, which is 1 for most text. A tolerance of 1 on `INV-2O24`
|
|
749
|
-
* therefore needs 4 of its 6 runs, while a tolerance of 2 needs 7. Under
|
|
750
|
-
* `'auto'`, the engine uses 2 where the text holds enough runs for 2,
|
|
751
|
-
* otherwise 1 where it holds enough for 1, and otherwise 0.
|
|
752
|
-
*
|
|
753
|
-
* The engine throws `SEARCH_INVALID_FILTER` for a tolerance of 1 or 2 on a
|
|
754
|
-
* text with too few runs, stating how many runs that tolerance needs. It
|
|
755
|
-
* throws the same error for any other tolerance, for a tolerance on a field
|
|
756
|
-
* that is not a pattern field, and for a tolerance in a filter without an
|
|
757
|
-
* `eq` test. Towards the pattern work cap, it counts one unit for each cell
|
|
758
|
-
* that it fills in the table of edit distances between the text and a
|
|
759
|
-
* value.
|
|
1363
|
+
* Each query term appears in one field of this document this many times,
|
|
1364
|
+
* under a key of `field:term`. A term that appears in two fields therefore
|
|
1365
|
+
* has two entries here, while the keys of {@link ScoreComponents.idf} hold
|
|
1366
|
+
* the bare term.
|
|
760
1367
|
*/
|
|
761
|
-
|
|
762
|
-
|
|
1368
|
+
termFrequencies: Record<string, number>;
|
|
1369
|
+
/** Each field the query searched holds this many tokens, keyed by field. */
|
|
1370
|
+
fieldLengths: Record<string, number>;
|
|
1371
|
+
/** Each query term carries this inverse document frequency, which is what makes a rare term count for more. */
|
|
1372
|
+
idf: Record<string, number>;
|
|
1373
|
+
}
|
|
763
1374
|
/**
|
|
764
|
-
*
|
|
765
|
-
* `enum[]`, `verbatim[]`, or `string[]` field.
|
|
766
|
-
*
|
|
767
|
-
* The engine throws `SEARCH_INVALID_FILTER` for these tests on any other
|
|
768
|
-
* field, for a value whose type differs from the type of the list's elements,
|
|
769
|
-
* and for `containsAll` or `matchesAny` on a `string[]` field whose type leaves
|
|
770
|
-
* out `pattern`.
|
|
1375
|
+
* A highlighted field, ready to render.
|
|
771
1376
|
*
|
|
772
1377
|
* @public
|
|
773
1378
|
*/
|
|
774
|
-
|
|
775
|
-
/** This
|
|
776
|
-
|
|
777
|
-
/**
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
1379
|
+
interface HighlightMatch {
|
|
1380
|
+
/** This is the field's text around the match, wrapped in the query's tags. */
|
|
1381
|
+
snippet: string;
|
|
1382
|
+
/**
|
|
1383
|
+
* Each range gives the start and the end of one match in the original field,
|
|
1384
|
+
* so you can render the highlight yourself. Where the snippet covers part of
|
|
1385
|
+
* the field alone, the engine lists only the matches that the snippet
|
|
1386
|
+
* displays. Every offset is a character count from the start of the original
|
|
1387
|
+
* field, whatever the snippet contains.
|
|
1388
|
+
*/
|
|
1389
|
+
positions: Array<{
|
|
1390
|
+
/** The match starts at this offset. */
|
|
1391
|
+
start: number;
|
|
1392
|
+
/** The match ends at this offset. */
|
|
1393
|
+
end: number;
|
|
1394
|
+
}>;
|
|
1395
|
+
}
|
|
782
1396
|
/**
|
|
783
|
-
*
|
|
784
|
-
* holds.
|
|
1397
|
+
* Counts for one faceted field.
|
|
785
1398
|
*
|
|
786
1399
|
* @public
|
|
787
1400
|
*/
|
|
788
|
-
|
|
789
|
-
/** This
|
|
790
|
-
|
|
791
|
-
/** This
|
|
792
|
-
|
|
793
|
-
/**
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
1401
|
+
interface FacetResult {
|
|
1402
|
+
/** This many documents match per value, keyed by value. */
|
|
1403
|
+
values: Record<string, number>;
|
|
1404
|
+
/** This is the number of entries in `values`, which is at most the facet's `limit`. */
|
|
1405
|
+
count: number;
|
|
1406
|
+
/**
|
|
1407
|
+
* Every count in `values` is at most this far below its true count. A value
|
|
1408
|
+
* that the engine leaves out of `values` because of `limit` has a true
|
|
1409
|
+
* count of at most this figure too. Where the engine counts a field on one
|
|
1410
|
+
* thread, it counts every value exactly, so this figure is the largest
|
|
1411
|
+
* count that it leaves out. Where it splits the count across worker copies
|
|
1412
|
+
* or cluster nodes, each of them returns only its own top values, so the
|
|
1413
|
+
* merged count of a value that is common overall but rare on one of them
|
|
1414
|
+
* can lack the matches on that one. A bound of 0 means that `values` holds
|
|
1415
|
+
* every matching value, each with its exact count.
|
|
1416
|
+
*/
|
|
1417
|
+
errorBound: number;
|
|
1418
|
+
}
|
|
798
1419
|
/**
|
|
799
|
-
*
|
|
1420
|
+
* One group of hits, produced by a query that grouped its results.
|
|
800
1421
|
*
|
|
801
1422
|
* @public
|
|
802
1423
|
*/
|
|
803
|
-
|
|
804
|
-
/**
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
* The engine measures `distance` in kilometres under `'km'`, in miles
|
|
814
|
-
* under `'mi'`, and in metres under `'m'`. For any other unit, it throws
|
|
815
|
-
* `SEARCH_INVALID_FILTER`.
|
|
816
|
-
*/
|
|
817
|
-
unit: 'km' | 'mi' | 'm';
|
|
818
|
-
/** The engine matches the points inside the circle while this is true, which is the default, and the points outside it while this is false. */
|
|
819
|
-
inside?: boolean;
|
|
820
|
-
/**
|
|
821
|
-
* The engine measures each distance with the Haversine formula on a sphere
|
|
822
|
-
* by default, and with Vincenty's formula on the WGS-84 ellipsoid while
|
|
823
|
-
* this is true. Vincenty's formula iterates, so the engine takes longer
|
|
824
|
-
* to compute each distance. The two formulas differ by less than 0.3% under about
|
|
825
|
-
* 100 km, while across a continent they can differ by up to 0.5%.
|
|
826
|
-
*/
|
|
827
|
-
highPrecision?: boolean;
|
|
828
|
-
};
|
|
829
|
-
};
|
|
1424
|
+
interface GroupResult {
|
|
1425
|
+
/** Each grouping field holds this value for the group, keyed by field. */
|
|
1426
|
+
values: Record<string, unknown>;
|
|
1427
|
+
/** These hits fall in the group, cut to the query's `maxPerGroup`. */
|
|
1428
|
+
hits: Array<Hit>;
|
|
1429
|
+
/** The query's reducer produced this value for the group, and only a query that set `group.reduce` carries it. */
|
|
1430
|
+
reduced?: unknown;
|
|
1431
|
+
/** The reducer threw, and this holds its message, so the group carries its hits and no `reduced` value. */
|
|
1432
|
+
reducerError?: string;
|
|
1433
|
+
}
|
|
830
1434
|
/**
|
|
831
|
-
*
|
|
1435
|
+
* What {@link Narsil.preflight} returns: how many documents a query matches,
|
|
1436
|
+
* without building or ranking a single hit.
|
|
832
1437
|
*
|
|
833
1438
|
* @public
|
|
834
1439
|
*/
|
|
835
|
-
|
|
836
|
-
/** The
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
* around the area, as in an exterior ring of GeoJSON. Where the corners
|
|
846
|
-
* span 180 degrees of longitude or more, the engine matches the area on
|
|
847
|
-
* the left of that path, so a ring listed that way can cross the
|
|
848
|
-
* antimeridian or span more than half the globe.
|
|
849
|
-
*/
|
|
850
|
-
points: Array<{
|
|
851
|
-
lat: number;
|
|
852
|
-
lon: number;
|
|
853
|
-
}>;
|
|
854
|
-
/** The engine matches the points inside the polygon while this is true, which is the default, and the points outside it while this is false. */
|
|
855
|
-
inside?: boolean;
|
|
856
|
-
};
|
|
857
|
-
};
|
|
1440
|
+
interface PreflightResult {
|
|
1441
|
+
/** The query matches this many documents. */
|
|
1442
|
+
count: number;
|
|
1443
|
+
/** `count` holds the exact number of matches where this is true, and a number at or below the true total where it is false, under the rule in {@link QueryResult.countExact}. */
|
|
1444
|
+
countExact: boolean;
|
|
1445
|
+
/** The count took this many milliseconds. */
|
|
1446
|
+
elapsed: number;
|
|
1447
|
+
/** This turns true when the index's terms came from an older analysis than its language module produces now. */
|
|
1448
|
+
analysisStale?: boolean;
|
|
1449
|
+
}
|
|
858
1450
|
/**
|
|
859
|
-
*
|
|
1451
|
+
* What a batch write returns. One bad document never abandons the rest, so
|
|
1452
|
+
* read both lists.
|
|
860
1453
|
*
|
|
861
1454
|
* @public
|
|
862
1455
|
*/
|
|
863
|
-
|
|
1456
|
+
interface BatchResult {
|
|
1457
|
+
/** The engine wrote the documents under these ids. */
|
|
1458
|
+
succeeded: string[];
|
|
1459
|
+
/** The engine rejected each of these documents, and each entry carries the error that rejected it. */
|
|
1460
|
+
failed: Array<{
|
|
1461
|
+
docId: string;
|
|
1462
|
+
error: NarsilError;
|
|
1463
|
+
}>;
|
|
1464
|
+
}
|
|
864
1465
|
/**
|
|
865
|
-
*
|
|
866
|
-
*
|
|
1466
|
+
* What {@link Narsil.importDocumentExport} returns. The engine continues past each
|
|
1467
|
+
* refused line, so read the refusals to learn which documents it skipped.
|
|
867
1468
|
*
|
|
868
1469
|
* @public
|
|
869
1470
|
*/
|
|
870
|
-
|
|
1471
|
+
interface DocumentImportResult {
|
|
1472
|
+
/** The engine wrote this many documents, counting each one that it replaced. */
|
|
1473
|
+
imported: number;
|
|
1474
|
+
/** The engine refused this many lines in total. */
|
|
1475
|
+
refusedCount: number;
|
|
1476
|
+
/** 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. */
|
|
1477
|
+
refused: Array<{
|
|
1478
|
+
line: number;
|
|
1479
|
+
code: NarsilErrorCode;
|
|
1480
|
+
message: string;
|
|
1481
|
+
}>;
|
|
1482
|
+
}
|
|
871
1483
|
/**
|
|
872
|
-
*
|
|
873
|
-
*
|
|
874
|
-
*
|
|
875
|
-
* The engine answers every test from an index that it keeps for the field. It
|
|
876
|
-
* applies the filter before scoring, so a narrow filter makes a search
|
|
877
|
-
* cheaper. A filter nests at most 30 levels deep and holds at most 1,024
|
|
878
|
-
* tests, counted across every field and nested expression. Past either limit,
|
|
879
|
-
* the engine throws `SEARCH_INVALID_FILTER`, while it throws
|
|
880
|
-
* `SEARCH_INVALID_FIELD` for a test on a field that the schema leaves out.
|
|
1484
|
+
* What {@link Narsil.suggest} returns: the indexed terms that complete a
|
|
1485
|
+
* prefix, ready to offer as you-type suggestions.
|
|
881
1486
|
*
|
|
882
1487
|
* @public
|
|
883
1488
|
*/
|
|
884
|
-
|
|
885
|
-
/** These
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
1489
|
+
interface SuggestResult {
|
|
1490
|
+
/** These completions run most widely used first. */
|
|
1491
|
+
terms: Array<{
|
|
1492
|
+
/** This is the completed term, as the index holds it. */
|
|
1493
|
+
term: string;
|
|
1494
|
+
/** The term appears in this many documents, which is what ordered the list. */
|
|
1495
|
+
documentFrequency: number;
|
|
1496
|
+
}>;
|
|
1497
|
+
/** The lookup took this many milliseconds. */
|
|
1498
|
+
elapsed: number;
|
|
1499
|
+
/** This turns true when the index's terms came from an older analysis than its language module produces now. */
|
|
1500
|
+
analysisStale?: boolean;
|
|
1501
|
+
}
|
|
895
1502
|
/**
|
|
896
|
-
*
|
|
1503
|
+
* The state of one vector field, and what maintenance would cost, as
|
|
1504
|
+
* {@link VectorMaintenanceOperations.vectorMaintenanceStatus} reports it.
|
|
897
1505
|
*
|
|
898
|
-
*
|
|
899
|
-
*
|
|
900
|
-
* The hits past the window follow in their first ranking, with their scores
|
|
901
|
-
* scaled below the lowest reranked score, so every page of one query comes
|
|
902
|
-
* from the same order.
|
|
1506
|
+
* Removing a vector leaves a tombstone in the graph, and enough of them slow a
|
|
1507
|
+
* search down. Read this to decide when compaction earns its cost.
|
|
903
1508
|
*
|
|
904
1509
|
* @public
|
|
905
1510
|
*/
|
|
906
|
-
interface
|
|
907
|
-
/**
|
|
908
|
-
|
|
909
|
-
* key. It throws `RERANK_CONFIG_INVALID` for a key that it has not
|
|
910
|
-
* registered.
|
|
911
|
-
*/
|
|
912
|
-
adapter: string;
|
|
1511
|
+
interface VectorMaintenanceResult {
|
|
1512
|
+
/** This describes the named vector field. */
|
|
1513
|
+
fieldName: string;
|
|
913
1514
|
/**
|
|
914
|
-
*
|
|
915
|
-
*
|
|
916
|
-
*
|
|
917
|
-
*
|
|
918
|
-
* does not declare as text, and for a field that the list gives twice.
|
|
1515
|
+
* Tombstones make up this share of the graph's nodes, from 0 to 1. Before
|
|
1516
|
+
* the first build, where {@link VectorMaintenanceResult.graphCount} reads 0,
|
|
1517
|
+
* the engine divides by the number of stored vectors, because no graph
|
|
1518
|
+
* exists yet.
|
|
919
1519
|
*/
|
|
920
|
-
|
|
1520
|
+
tombstoneRatio: number;
|
|
1521
|
+
/** The field holds this many HNSW graphs: 0 before the first build and 1 once a graph exists. */
|
|
1522
|
+
graphCount: number;
|
|
1523
|
+
/** This many vectors wait outside the graph, which a search scans one by one. */
|
|
1524
|
+
bufferSize: number;
|
|
1525
|
+
/** This stays true while a graph build runs. */
|
|
1526
|
+
building: boolean;
|
|
921
1527
|
/**
|
|
922
|
-
*
|
|
923
|
-
*
|
|
924
|
-
* `RERANK_CONFIG_INVALID` where the query carries neither.
|
|
1528
|
+
* This turns true while a rebuild that keeps recall up waits for the node to have
|
|
1529
|
+
* room for a second graph beside the one it serves, and false once it starts.
|
|
925
1530
|
*/
|
|
926
|
-
|
|
1531
|
+
waitingForMemory: boolean;
|
|
927
1532
|
/**
|
|
928
|
-
*
|
|
929
|
-
*
|
|
930
|
-
* smallest of 100 and `maxRerankWindow`, and no more than the `hybrid.depth`
|
|
931
|
-
* of a hybrid query that sets one. A hybrid query that sets `hybrid.depth`
|
|
932
|
-
* reranks its fused list at that depth, so the engine throws
|
|
933
|
-
* `RERANK_CONFIG_INVALID` when you set a window above that depth.
|
|
1533
|
+
* This stays true after a restart while a field kept on disk loads its codes and graph in the
|
|
1534
|
+
* background, during which a search reads them from the field's files.
|
|
934
1535
|
*/
|
|
935
|
-
|
|
1536
|
+
loadingFromFiles: boolean;
|
|
1537
|
+
/** {@link VectorMaintenanceOperations.compactVectors} would take about this many milliseconds. */
|
|
1538
|
+
estimatedCompactMs: number;
|
|
1539
|
+
/** {@link VectorMaintenanceOperations.optimizeVectors} would take about this many milliseconds. */
|
|
1540
|
+
estimatedOptimizeMs: number;
|
|
936
1541
|
}
|
|
937
|
-
|
|
938
1542
|
/**
|
|
939
|
-
*
|
|
1543
|
+
* One stored document, as {@link Narsil.listDocuments} returns it.
|
|
940
1544
|
*
|
|
941
|
-
*
|
|
942
|
-
* passing both throws `EMBEDDING_CONFIG_INVALID`. Result count is governed
|
|
943
|
-
* by the outer query's `limit`, not by any field on this object.
|
|
1545
|
+
* @typeParam T - Shape of the stored document.
|
|
944
1546
|
*
|
|
945
1547
|
* @public
|
|
946
1548
|
*/
|
|
947
|
-
interface
|
|
948
|
-
/**
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
field: string;
|
|
953
|
-
/**
|
|
954
|
-
* Raw query vector, given as a number array or a `Float32Array`. Length
|
|
955
|
-
* must match the indexed field's dimension or the search rejects the
|
|
956
|
-
* request with `VECTOR_DIMENSION_MISMATCH`.
|
|
957
|
-
*/
|
|
958
|
-
value?: number[] | Float32Array;
|
|
959
|
-
/**
|
|
960
|
-
* Text to embed at query time using the index or instance embedding
|
|
961
|
-
* adapter. Mutually exclusive with `value`; requires a configured adapter.
|
|
962
|
-
*/
|
|
963
|
-
text?: string;
|
|
964
|
-
/**
|
|
965
|
-
* Score floor applied during ranking. Hits scoring below this value
|
|
966
|
-
* are dropped before `limit` is enforced, so the returned hit count
|
|
967
|
-
* can be smaller than `limit` even when more documents exist. The
|
|
968
|
-
* floor is interpreted in score space for every metric; for
|
|
969
|
-
* `euclidean`, distance is mapped to a similarity score of
|
|
970
|
-
* `1 / (1 + distance)` first. Defaults to no floor.
|
|
971
|
-
*/
|
|
972
|
-
similarity?: number;
|
|
973
|
-
/**
|
|
974
|
-
* Similarity metric used for ranking. Defaults to `cosine`. Choose
|
|
975
|
-
* `dotProduct` for raw inner-product scoring on already-normalised
|
|
976
|
-
* vectors and `euclidean` for distance-based ordering.
|
|
977
|
-
*/
|
|
978
|
-
metric?: 'cosine' | 'dotProduct' | 'euclidean';
|
|
979
|
-
/**
|
|
980
|
-
* The engine keeps this many candidates as it walks the HNSW graph, so a
|
|
981
|
-
* higher value can find more of the true neighbours, although each query
|
|
982
|
-
* takes longer. The engine applies it only once the field holds a graph.
|
|
983
|
-
* The engine fetches k hits, where k is one more than the number of hits up
|
|
984
|
-
* to the end of the page, so k is `limit` plus 1 on a first page. When a
|
|
985
|
-
* query leaves `efSearch` unset, the engine keeps the larger of 50 and k
|
|
986
|
-
* plus a margin, where the margin is 50 below 768 dimensions, 75 from 768
|
|
987
|
-
* to 1,023 dimensions, and 0 at 1,024 dimensions and above. Under a
|
|
988
|
-
* filter, the engine counts only the candidates that pass the filter.
|
|
989
|
-
*/
|
|
990
|
-
efSearch?: number;
|
|
991
|
-
/**
|
|
992
|
-
* The engine re-scores this many times k candidates in a quantized field
|
|
993
|
-
* against the full-precision vectors before it returns the best `limit`,
|
|
994
|
-
* where k is one more than the number of hits up to the end of the page, so
|
|
995
|
-
* k is `limit` plus 1 on a first page. For a value below 1, or for a value
|
|
996
|
-
* that is not a finite number, the engine throws a `NarsilError` with code
|
|
997
|
-
* `CONFIG_INVALID`. The engine ignores it on a field whose quantization is
|
|
998
|
-
* `none`. When a query leaves it unset, the engine sets the number of
|
|
999
|
-
* candidates that it re-scores from k and from the field's dimension. It
|
|
1000
|
-
* rounds that number up, and it re-scores at least 3k candidates under
|
|
1001
|
-
* `osq1` and `osq2`, and at least k under `osq4` and `osq8`. Below 768
|
|
1002
|
-
* dimensions, it re-scores 3.23k + 55.9√k under `osq1` and 2.6k + 22.5√k under
|
|
1003
|
-
* `osq2`. From 768 to 1,023 dimensions, it re-scores 2.2k + 27√k under
|
|
1004
|
-
* `osq1` and k + 16√k under `osq2`. At 1,024 dimensions and above, it
|
|
1005
|
-
* re-scores 3k under both. Under `osq4`, it re-scores 5k below 1,024
|
|
1006
|
-
* dimensions and 2k from 1,024 dimensions, while under `osq8` it re-scores
|
|
1007
|
-
* 2k at every dimension. Under a filter, the engine counts only the
|
|
1008
|
-
* candidates that pass the filter. On vectors spread evenly across every
|
|
1009
|
-
* dimension, a one-bit or two-bit code can find fewer than 95% of the true
|
|
1010
|
-
* nearest neighbours at these defaults, so raise `oversample` on a query that
|
|
1011
|
-
* needs more of them.
|
|
1012
|
-
*/
|
|
1013
|
-
oversample?: number;
|
|
1549
|
+
interface ListedDocument<T = AnyDocument> {
|
|
1550
|
+
/** The document is stored under this id. */
|
|
1551
|
+
id: string;
|
|
1552
|
+
/** This holds the stored document, cut down to what the projection kept. */
|
|
1553
|
+
document: T;
|
|
1014
1554
|
}
|
|
1015
1555
|
/**
|
|
1016
|
-
*
|
|
1556
|
+
* What {@link Narsil.listDocuments} returns: one page of stored documents and
|
|
1557
|
+
* the cursor that reaches the next one.
|
|
1017
1558
|
*
|
|
1018
|
-
*
|
|
1019
|
-
* scores that live on different scales. `linear` blends the scores directly,
|
|
1020
|
-
* which gives you control once you know what each side's scores look like.
|
|
1559
|
+
* @typeParam T - Shape of the stored documents.
|
|
1021
1560
|
*
|
|
1022
1561
|
* @public
|
|
1023
1562
|
*/
|
|
1024
|
-
interface
|
|
1025
|
-
/**
|
|
1026
|
-
|
|
1027
|
-
/**
|
|
1028
|
-
|
|
1029
|
-
/** The
|
|
1030
|
-
|
|
1563
|
+
interface ListResult<T = AnyDocument> {
|
|
1564
|
+
/** These documents make up the page, in ascending document-id order. */
|
|
1565
|
+
documents: Array<ListedDocument<T>>;
|
|
1566
|
+
/** This opaque cursor reaches the next page, and is null once the listing is finished. */
|
|
1567
|
+
cursor: string | null;
|
|
1568
|
+
/** The listing covers this many documents in total, and any filter narrows that count. */
|
|
1569
|
+
total: number;
|
|
1570
|
+
/** The engine spent this many milliseconds building the page. */
|
|
1571
|
+
elapsed: number;
|
|
1572
|
+
}
|
|
1573
|
+
|
|
1574
|
+
/**
|
|
1575
|
+
* The change capture setting of one index, which {@link ChangesOperations.updateChanges} takes.
|
|
1576
|
+
*
|
|
1577
|
+
* A subscriber receives the documents of the whole index, so decide which callers may follow an index before you turn
|
|
1578
|
+
* capture on. A filter only chooses which changes a subscriber receives, and it grants no access.
|
|
1579
|
+
*
|
|
1580
|
+
* @public
|
|
1581
|
+
*/
|
|
1582
|
+
interface ChangesSetting {
|
|
1583
|
+
/** This turns change capture on or off. Turning it on gives the index a new epoch unless device sync is on. */
|
|
1584
|
+
enabled: boolean;
|
|
1031
1585
|
/**
|
|
1032
|
-
* Set
|
|
1033
|
-
* a
|
|
1034
|
-
* the
|
|
1035
|
-
* through the top `depth` of the fused list. The last page stops at this
|
|
1036
|
-
* depth, so it can hold fewer hits than the limit. Set a whole number from 1
|
|
1037
|
-
* to 10,000. The engine throws `CONFIG_INVALID` for any other value, and
|
|
1038
|
-
* `SEARCH_RESULT_WINDOW_EXCEEDED` for a page that starts at this depth or
|
|
1039
|
-
* beyond. Where you leave the depth out, each search fetches only enough
|
|
1040
|
-
* results to fill the page, so the fused order can change from one page to
|
|
1041
|
-
* the next, and a cluster refuses a cursor with `SEARCH_INVALID_CURSOR`.
|
|
1586
|
+
* Set this to write into each log entry the document that the entry replaces or removes. A change then holds the
|
|
1587
|
+
* document before the write, and a subscription can hold a filter. It defaults to false, because the engine then
|
|
1588
|
+
* reads the stored document and writes it to the log again on every update and removal.
|
|
1042
1589
|
*/
|
|
1043
|
-
|
|
1590
|
+
previousDocument?: boolean;
|
|
1591
|
+
/** This is the age in milliseconds after which the engine deletes a log segment from history. It defaults to 30
|
|
1592
|
+
* days. */
|
|
1593
|
+
historyMaxAgeMs?: number;
|
|
1594
|
+
/** This is the byte count above which the engine deletes the oldest log segment from history. It defaults to the
|
|
1595
|
+
* larger of the checkpoint's length and 1 GiB. */
|
|
1596
|
+
historyMaxBytes?: number;
|
|
1044
1597
|
}
|
|
1045
|
-
|
|
1046
1598
|
/**
|
|
1047
|
-
*
|
|
1599
|
+
* The change capture state of one index, which {@link ChangesOperations.getChanges} returns.
|
|
1048
1600
|
*
|
|
1049
1601
|
* @public
|
|
1050
1602
|
*/
|
|
1051
|
-
interface
|
|
1052
|
-
/**
|
|
1053
|
-
|
|
1054
|
-
/**
|
|
1055
|
-
|
|
1603
|
+
interface ChangesStatus extends ChangesSetting {
|
|
1604
|
+
/** This is true when the engine writes the document before the write into each log entry. */
|
|
1605
|
+
previousDocument: boolean;
|
|
1606
|
+
/** This is the index epoch, 32 lowercase hexadecimal digits, or `null` while capture is off. */
|
|
1607
|
+
epoch: string | null;
|
|
1056
1608
|
}
|
|
1057
1609
|
/**
|
|
1058
|
-
*
|
|
1610
|
+
* A subscriber's place in one partition of an index: the highest `seqNo` whose change it has applied.
|
|
1059
1611
|
*
|
|
1060
|
-
*
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1612
|
+
* @public
|
|
1613
|
+
*/
|
|
1614
|
+
interface ChangePosition {
|
|
1615
|
+
/** This is the partition that the position belongs to. */
|
|
1616
|
+
partitionId: number;
|
|
1617
|
+
/** This is the sequence number of the last entry that the subscriber has examined in that partition. */
|
|
1618
|
+
seqNo: number;
|
|
1619
|
+
}
|
|
1620
|
+
/**
|
|
1621
|
+
* What a write did to a document. A `put` comes from an entry that the engine wrote while `previousDocument` was off,
|
|
1622
|
+
* so it can be an insert or an update.
|
|
1064
1623
|
*
|
|
1065
|
-
*
|
|
1066
|
-
|
|
1067
|
-
|
|
1624
|
+
* @public
|
|
1625
|
+
*/
|
|
1626
|
+
type ChangeType = 'put' | 'insert' | 'update' | 'remove';
|
|
1627
|
+
/**
|
|
1628
|
+
* One write to an index, as {@link ChangesOperations.followChanges} returns it.
|
|
1068
1629
|
*
|
|
1069
1630
|
* @public
|
|
1070
1631
|
*/
|
|
1071
|
-
interface
|
|
1072
|
-
/**
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
/**
|
|
1079
|
-
|
|
1080
|
-
/** This
|
|
1081
|
-
|
|
1632
|
+
interface Change {
|
|
1633
|
+
/** This is the sequence number of the log entry within its partition. */
|
|
1634
|
+
seqNo: number;
|
|
1635
|
+
/** This is what the write did to the document. */
|
|
1636
|
+
type: ChangeType;
|
|
1637
|
+
/** This is the ID of the document that the write touched. */
|
|
1638
|
+
documentId: string;
|
|
1639
|
+
/** This is the document after the write, with every field and every computed vector, and absent after a removal. */
|
|
1640
|
+
document?: AnyDocument;
|
|
1641
|
+
/** This is the document before the write, present only for an update or a removal with `previousDocument` on. */
|
|
1642
|
+
previousDocument?: AnyDocument;
|
|
1643
|
+
}
|
|
1644
|
+
/**
|
|
1645
|
+
* Where {@link ChangesOperations.followChanges} starts and which changes it returns.
|
|
1646
|
+
*
|
|
1647
|
+
* @public
|
|
1648
|
+
*/
|
|
1649
|
+
interface FollowChangesOptions {
|
|
1650
|
+
/** This is the epoch that the positions belong to. Pass it together with `positions`, or leave both out. */
|
|
1651
|
+
epoch?: string;
|
|
1652
|
+
/** This holds one position for each partition. Leave it out, with `epoch`, to start at the index's current heads. */
|
|
1653
|
+
positions?: ChangePosition[];
|
|
1082
1654
|
/**
|
|
1083
|
-
* This
|
|
1084
|
-
*
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
* The engine reads every document the listing covers to build a sorted page,
|
|
1090
|
-
* so a sorted listing costs more than the default order on a large index.
|
|
1091
|
-
*/
|
|
1092
|
-
sort?: SortSpec;
|
|
1093
|
-
/** This chooses how much of each stored document comes back, and the whole document by default. */
|
|
1094
|
-
document?: DocumentProjection;
|
|
1655
|
+
* This keeps only the changes whose document before or after the write matches it, in the syntax of a query's
|
|
1656
|
+
* filters. It needs `previousDocument` on.
|
|
1657
|
+
*/
|
|
1658
|
+
filter?: FilterExpression;
|
|
1659
|
+
/** This ends the iteration when it aborts. */
|
|
1660
|
+
signal?: AbortSignal;
|
|
1095
1661
|
}
|
|
1096
|
-
|
|
1097
1662
|
/**
|
|
1098
|
-
*
|
|
1099
|
-
* merged into one ranking.
|
|
1663
|
+
* The first event of {@link ChangesOperations.followChanges}, which gives the positions that the changes follow.
|
|
1100
1664
|
*
|
|
1101
1665
|
* @public
|
|
1102
1666
|
*/
|
|
1103
|
-
|
|
1667
|
+
interface ChangesSubscribed {
|
|
1668
|
+
/** This marks the event. */
|
|
1669
|
+
type: 'subscribed';
|
|
1670
|
+
/** This is the index's epoch. Save it with the positions. */
|
|
1671
|
+
epoch: string;
|
|
1672
|
+
/** This is the number of partitions, each of which has a position. */
|
|
1673
|
+
partitionCount: number;
|
|
1674
|
+
/** These are the positions that the changes follow. */
|
|
1675
|
+
positions: ChangePosition[];
|
|
1676
|
+
/** These are the heads of the partitions when the subscription started. */
|
|
1677
|
+
heads: ChangePosition[];
|
|
1678
|
+
/** This is the length in bytes of the history and log between the positions and the heads. */
|
|
1679
|
+
bytesBehind: number;
|
|
1680
|
+
/** This is true when a change can hold the document before the write. */
|
|
1681
|
+
previousDocument: boolean;
|
|
1682
|
+
}
|
|
1104
1683
|
/**
|
|
1105
|
-
*
|
|
1106
|
-
* term, `any` accepts one, and a number demands that many.
|
|
1684
|
+
* A group of changes from one partition. Apply the changes, then save `scannedSeqNo` as the partition's position.
|
|
1107
1685
|
*
|
|
1108
1686
|
* @public
|
|
1109
1687
|
*/
|
|
1110
|
-
|
|
1688
|
+
interface ChangesBatch {
|
|
1689
|
+
/** This marks the event. */
|
|
1690
|
+
type: 'changes';
|
|
1691
|
+
/** This is the partition that the changes come from. */
|
|
1692
|
+
partitionId: number;
|
|
1693
|
+
/** These are the changes in `seqNo` order, which can be empty under a filter. */
|
|
1694
|
+
changes: Change[];
|
|
1695
|
+
/** This is the highest `seqNo` of the partition that the engine examined, which is the next position to save. */
|
|
1696
|
+
scannedSeqNo: number;
|
|
1697
|
+
}
|
|
1111
1698
|
/**
|
|
1112
|
-
*
|
|
1699
|
+
* The last event of {@link ChangesOperations.followChanges} when the positions no longer lead to the index's changes.
|
|
1700
|
+
* Export the index, replace your copy with the export's documents, and follow again from the export's header.
|
|
1113
1701
|
*
|
|
1114
1702
|
* @public
|
|
1115
1703
|
*/
|
|
1116
|
-
interface
|
|
1117
|
-
/**
|
|
1118
|
-
|
|
1119
|
-
/** Ascending or descending order for this field. */
|
|
1120
|
-
direction: 'asc' | 'desc';
|
|
1704
|
+
interface ChangesResync {
|
|
1705
|
+
/** This marks the event. */
|
|
1706
|
+
type: 'resync';
|
|
1121
1707
|
/**
|
|
1122
|
-
*
|
|
1123
|
-
*
|
|
1124
|
-
* `'max'`, and the mean or the median of the list's numbers under `'avg'`
|
|
1125
|
-
* or `'median'`. Where you leave this out, the engine uses `'min'` for an
|
|
1126
|
-
* ascending sort and `'max'` for a descending one. It sorts by a field that
|
|
1127
|
-
* holds a single value as that value stands, under every mode. It throws
|
|
1128
|
-
* `SEARCH_INVALID_FIELD` for `'avg'` or `'median'` on a field that the
|
|
1129
|
-
* schema declares as anything other than `number` or `number[]`.
|
|
1708
|
+
* This is `epoch` when the index has a new epoch, `history` when the history no longer holds the entries above a
|
|
1709
|
+
* position, and `ahead` when a position lies above every entry of its partition.
|
|
1130
1710
|
*/
|
|
1131
|
-
|
|
1711
|
+
reason: 'epoch' | 'history' | 'ahead';
|
|
1132
1712
|
}
|
|
1133
1713
|
/**
|
|
1134
|
-
*
|
|
1135
|
-
* order they apply.
|
|
1136
|
-
*
|
|
1137
|
-
* Both forms order by the first field, break a tie on the second, and carry on
|
|
1138
|
-
* that way. Prefer the list where the order of the fields matters, because
|
|
1139
|
-
* JavaScript moves an all-digit key such as `2024` to the front of an object
|
|
1140
|
-
* and the list keeps the order you wrote.
|
|
1714
|
+
* One event of {@link ChangesOperations.followChanges}.
|
|
1141
1715
|
*
|
|
1142
1716
|
* @public
|
|
1143
1717
|
*/
|
|
1144
|
-
type
|
|
1718
|
+
type ChangesEvent = ChangesSubscribed | ChangesBatch | ChangesResync;
|
|
1145
1719
|
/**
|
|
1146
|
-
*
|
|
1147
|
-
*
|
|
1148
|
-
* Set `term` for keyword search, `vector` for similarity search, and `mode`
|
|
1149
|
-
* when you want both. The engine matches nothing for a query carrying neither
|
|
1150
|
-
* of them, so page through an index with {@link Narsil.listDocuments}
|
|
1151
|
-
* instead.
|
|
1720
|
+
* The methods that turn change capture on and off for an index and follow its changes.
|
|
1152
1721
|
*
|
|
1153
1722
|
* @public
|
|
1154
1723
|
*/
|
|
1155
|
-
interface
|
|
1156
|
-
/** The engine analyses this text with the index's language module and searches for the terms that result. */
|
|
1157
|
-
term?: string;
|
|
1158
|
-
/** The engine searches the term in these fields, and in every text field in the schema by default. */
|
|
1159
|
-
fields?: string[];
|
|
1160
|
-
/**
|
|
1161
|
-
* The engine scores only the documents that pass this filter. It throws
|
|
1162
|
-
* `SEARCH_INVALID_FILTER` for an operand of the wrong shape, and for an
|
|
1163
|
-
* operator on a field of another type, such as `startsWith` on a number
|
|
1164
|
-
* field.
|
|
1165
|
-
*/
|
|
1166
|
-
filters?: FilterExpression;
|
|
1167
|
-
/**
|
|
1168
|
-
* The engine multiplies the score from each named field by its weight. It
|
|
1169
|
-
* throws `SEARCH_INVALID_FIELD` for any field other than a text field that
|
|
1170
|
-
* the schema declares, and `CONFIG_INVALID` for a weight that is not a
|
|
1171
|
-
* finite number.
|
|
1172
|
-
*/
|
|
1173
|
-
boost?: Record<string, number>;
|
|
1174
|
-
/** The engine gathers term statistics this way, and follows the index's `defaultScoring` where the query sets none. */
|
|
1175
|
-
scoring?: ScoringMode;
|
|
1176
|
-
/**
|
|
1177
|
-
* The engine drops any hit scoring below this value. It ranks with BM25,
|
|
1178
|
-
* which has no fixed upper bound, so a floor that suits one index and one
|
|
1179
|
-
* query can reject every hit in another.
|
|
1180
|
-
*/
|
|
1181
|
-
minScore?: number;
|
|
1182
|
-
/**
|
|
1183
|
-
* The engine keeps a document only where the document matches this many
|
|
1184
|
-
* query terms, under the same `tolerance` and `prefixLength` that the search
|
|
1185
|
-
* uses. One term is enough by default.
|
|
1186
|
-
*/
|
|
1187
|
-
termMatch?: TermMatchPolicy;
|
|
1188
|
-
/**
|
|
1189
|
-
* The engine matches an indexed term within this edit distance of a query
|
|
1190
|
-
* term, so it finds a document for a query with a typo. It counts each
|
|
1191
|
-
* Unicode code point as one character. Set an integer from 0 to 10.
|
|
1192
|
-
*/
|
|
1193
|
-
tolerance?: number;
|
|
1194
|
-
/**
|
|
1195
|
-
* The engine applies `tolerance` only to the indexed terms that share this
|
|
1196
|
-
* many leading characters with the query term, or to the terms that start
|
|
1197
|
-
* with the whole query term when the query term is shorter. Set an integer
|
|
1198
|
-
* from 0 to 1,024; the default is 2.
|
|
1199
|
-
*/
|
|
1200
|
-
prefixLength?: number;
|
|
1201
|
-
/**
|
|
1202
|
-
* With this set, the engine treats the last query term as an unfinished
|
|
1203
|
-
* word, so `secur` matches `security`. The engine matches that last term by
|
|
1204
|
-
* its stem or by completing it, while `tolerance` applies only to the earlier
|
|
1205
|
-
* terms, which have to match whole. The engine scores completions against a
|
|
1206
|
-
* shared document frequency. It also ranks them below whole-word matches.
|
|
1207
|
-
* The engine ignores this setting where `exact` is true, and the setting is
|
|
1208
|
-
* false by default.
|
|
1209
|
-
*/
|
|
1210
|
-
prefix?: boolean;
|
|
1724
|
+
interface ChangesOperations {
|
|
1211
1725
|
/**
|
|
1212
|
-
*
|
|
1213
|
-
* characters inside the longer words of every field whose type includes
|
|
1214
|
-
* `partial`, so a search for `proof` matches a document with `waterproof`
|
|
1215
|
-
* in such a field. The engine counts each Unicode code point as one
|
|
1216
|
-
* character. It looks for the query word, before stemming, inside each word
|
|
1217
|
-
* exactly as that word appears in a document.
|
|
1726
|
+
* Replaces the change capture setting of an index.
|
|
1218
1727
|
*
|
|
1219
|
-
*
|
|
1220
|
-
*
|
|
1221
|
-
*
|
|
1222
|
-
*
|
|
1223
|
-
* the query word makes up, so it scores such a match below a whole-word
|
|
1224
|
-
* match at the same frequency in a field of the same length. With
|
|
1225
|
-
* `highlight`, it tags each whole word that contains a query word in a
|
|
1226
|
-
* searched `partial` field.
|
|
1728
|
+
* Turning capture on gives the index a new epoch unless device sync is on, and the engine keeps the log segments
|
|
1729
|
+
* that a checkpoint covers as history from then on. Turning it off ends every follower of the index and deletes the
|
|
1730
|
+
* history unless a device has asked for the index's sync snapshot. The engine saves the setting with the index, and
|
|
1731
|
+
* no snapshot of the index includes it.
|
|
1227
1732
|
*
|
|
1228
|
-
*
|
|
1229
|
-
* setting
|
|
1230
|
-
* `
|
|
1231
|
-
*
|
|
1232
|
-
* or `false`.
|
|
1233
|
-
*/
|
|
1234
|
-
partialWords?: boolean;
|
|
1235
|
-
/**
|
|
1236
|
-
* With this set, the engine matches each query term only against an equal
|
|
1237
|
-
* indexed term, so it turns off fuzzy matching, prefix completion,
|
|
1238
|
-
* partial-word matching, and synonyms. The engine still stems the query, because the
|
|
1239
|
-
* index stores stemmed terms, so a search for `running` matches a document
|
|
1240
|
-
* that contains `runs` through the stem that both words share.
|
|
1241
|
-
*/
|
|
1242
|
-
exact?: boolean;
|
|
1243
|
-
/**
|
|
1244
|
-
* The engine counts the values of these fields across the matching
|
|
1245
|
-
* documents, and each entry sets how it cuts and sorts that field's counts.
|
|
1246
|
-
* For a field outside the schema, it counts the values that the documents
|
|
1247
|
-
* store. It throws `SEARCH_INVALID_FIELD` for a `geopoint` or a vector
|
|
1248
|
-
* field.
|
|
1249
|
-
*/
|
|
1250
|
-
facets?: FacetConfig;
|
|
1251
|
-
/**
|
|
1252
|
-
* The engine sorts the hits by the values of these fields, in place of the
|
|
1253
|
-
* relevance ranking. Pass an object keyed by field, or a list of fields in
|
|
1254
|
-
* the order that the engine compares them. The engine sorts by a `number`,
|
|
1255
|
-
* `boolean`, or `enum` field, by a text field whose type includes
|
|
1256
|
-
* `sortable`, or by a list of any of these, which it reduces to one value by
|
|
1257
|
-
* the entry's `mode`. It throws `SEARCH_INVALID_FIELD` for a sort on a
|
|
1258
|
-
* `geopoint` or a vector field, because neither type has an order. It throws
|
|
1259
|
-
* the same code for a sort on any other text field, since the engine keeps
|
|
1260
|
-
* up to the first 512 code points of every document's value in memory to
|
|
1261
|
-
* sort by a text field. The engine orders hybrid results by fusion, so it
|
|
1262
|
-
* throws `SEARCH_INVALID_MODE` for a sort on a hybrid query. It also throws
|
|
1263
|
-
* that code for a direction other than `asc` and `desc`.
|
|
1264
|
-
*/
|
|
1265
|
-
sort?: SortSpec;
|
|
1266
|
-
/** These settings collapse the hits into groups by field value. */
|
|
1267
|
-
group?: GroupConfig;
|
|
1268
|
-
/**
|
|
1269
|
-
* The query returns this many hits, and 10 by default. Pass 0 to read the
|
|
1270
|
-
* match count with no hits. The engine reads a value below 0 as 0. It falls
|
|
1271
|
-
* back to the default for `NaN` and for an infinite value, so a page size
|
|
1272
|
-
* that you compute from user input never fails the query.
|
|
1733
|
+
* @param indexName - The index whose setting the engine replaces.
|
|
1734
|
+
* @param setting - The new setting.
|
|
1735
|
+
* @throws A `NarsilError` with `CHANGES_DURABILITY_REQUIRED` when the engine has no write-ahead log durability, and
|
|
1736
|
+
* with `CONFIG_INVALID` when a field has the wrong type or a history limit is not a positive whole number.
|
|
1273
1737
|
*/
|
|
1274
|
-
|
|
1275
|
-
/** The query skips this many hits before returning. A deep offset costs more than a cursor. */
|
|
1276
|
-
offset?: number;
|
|
1277
|
-
/** This cursor comes from a previous result's `cursor`, and pages without an offset's cost. */
|
|
1278
|
-
searchAfter?: string;
|
|
1279
|
-
/** These settings name the fields that come back with highlighted snippets. */
|
|
1280
|
-
highlight?: HighlightConfig;
|
|
1281
|
-
/** These documents take fixed positions, ahead of the ranking. */
|
|
1282
|
-
pinned?: Array<{
|
|
1283
|
-
docId: string;
|
|
1284
|
-
position: number;
|
|
1285
|
-
}>;
|
|
1286
|
-
/** This picks which engine answers the query. Keyword search runs by default. */
|
|
1287
|
-
mode?: SearchMode;
|
|
1288
|
-
/** These vector-search inputs are required in `vector` and `hybrid` mode. */
|
|
1289
|
-
vector?: VectorQueryConfig;
|
|
1290
|
-
/** These settings control how the keyword and vector rankings merge in `hybrid` mode. */
|
|
1291
|
-
hybrid?: HybridConfig;
|
|
1738
|
+
updateChanges(indexName: string, setting: ChangesSetting): Promise<void>;
|
|
1292
1739
|
/**
|
|
1293
|
-
*
|
|
1294
|
-
*
|
|
1295
|
-
*
|
|
1296
|
-
*
|
|
1297
|
-
* `
|
|
1298
|
-
* `RERANK_FAILED` where the adapter fails or outlasts the engine's
|
|
1299
|
-
* `rerankTimeout`.
|
|
1740
|
+
* Returns the change capture state of an index.
|
|
1741
|
+
*
|
|
1742
|
+
* @param indexName - The index whose state the engine returns.
|
|
1743
|
+
* @returns The setting and the epoch.
|
|
1744
|
+
* @throws A `NarsilError` with `INDEX_NOT_FOUND` when no index has that name.
|
|
1300
1745
|
*/
|
|
1301
|
-
|
|
1746
|
+
getChanges(indexName: string): Promise<ChangesStatus>;
|
|
1302
1747
|
/**
|
|
1303
|
-
*
|
|
1304
|
-
*
|
|
1305
|
-
*
|
|
1306
|
-
*
|
|
1748
|
+
* Returns the changes of an index above a list of positions, and then each later change as the log makes it
|
|
1749
|
+
* durable, until the signal aborts or the caller stops iterating.
|
|
1750
|
+
*
|
|
1751
|
+
* The first event gives the epoch and the positions. Each later event holds the changes of one partition in `seqNo`
|
|
1752
|
+
* order. Where the positions no longer lead to the index's changes, the last event is a resync.
|
|
1753
|
+
*
|
|
1754
|
+
* @param indexName - The index whose changes the engine returns.
|
|
1755
|
+
* @param options - The epoch and positions to start from, a filter, and a signal.
|
|
1756
|
+
* @returns The events, one at a time.
|
|
1757
|
+
* @throws A `NarsilError` with `CHANGES_NOT_ENABLED` when capture is off or turns off, with
|
|
1758
|
+
* `CHANGES_INVALID_POSITIONS` for a malformed epoch or list of positions, with `SEARCH_INVALID_FILTER` for a filter
|
|
1759
|
+
* that breaks the shape or the limits of a query's filters, with `SEARCH_INVALID_FIELD` for a filter that tests a
|
|
1760
|
+
* field which the schema leaves out, and with `CHANGES_PREVIOUS_DOCUMENT_REQUIRED` for a filter while
|
|
1761
|
+
* `previousDocument` is off.
|
|
1307
1762
|
*/
|
|
1308
|
-
|
|
1309
|
-
/** Setting this returns the numbers behind each hit's score, which is what you read when a ranking surprises you. */
|
|
1310
|
-
includeScoreComponents?: boolean;
|
|
1311
|
-
/** This chooses how much of each stored document comes back, and the whole document by default. */
|
|
1312
|
-
document?: DocumentProjection;
|
|
1763
|
+
followChanges(indexName: string, options?: FollowChangesOptions): AsyncIterable<ChangesEvent>;
|
|
1313
1764
|
}
|
|
1765
|
+
|
|
1314
1766
|
/**
|
|
1315
|
-
*
|
|
1316
|
-
*
|
|
1317
|
-
*
|
|
1318
|
-
* `document` is then an empty object. Pass `include` to keep named fields
|
|
1319
|
-
* alone, or `exclude` to drop named fields and keep the rest; naming both
|
|
1320
|
-
* keeps the included fields and then drops the excluded ones from those. Use
|
|
1321
|
-
* dots to name a nested field, so `author.name` addresses the `name` inside
|
|
1322
|
-
* `author`, and a name that matches no field changes nothing.
|
|
1323
|
-
*
|
|
1324
|
-
* Drop a vector field on a similarity search, because the engine otherwise
|
|
1325
|
-
* reads every hit's vector back out of the index and writes it into the
|
|
1326
|
-
* response.
|
|
1767
|
+
* Snapshot of V8 heap usage as reported by `process.memoryUsage()`, with the
|
|
1768
|
+
* limit the heap may grow to. All values are bytes. `null` in environments
|
|
1769
|
+
* that do not expose `process.memoryUsage`, such as browsers.
|
|
1327
1770
|
*
|
|
1328
1771
|
* @public
|
|
1329
1772
|
*/
|
|
1330
|
-
|
|
1331
|
-
/**
|
|
1332
|
-
|
|
1333
|
-
/**
|
|
1334
|
-
|
|
1335
|
-
|
|
1773
|
+
interface ProcessMemoryReport {
|
|
1774
|
+
/** The process is using this much heap. */
|
|
1775
|
+
heapUsed: number;
|
|
1776
|
+
/** V8 has reserved this much heap. */
|
|
1777
|
+
heapTotal: number;
|
|
1778
|
+
/**
|
|
1779
|
+
* The heap may grow to this many bytes before the runtime ends the process
|
|
1780
|
+
* for running out of memory. Node sets it from `--max-old-space-size`, from
|
|
1781
|
+
* `--max-old-space-size-percentage`, or from the memory the host or the
|
|
1782
|
+
* container reports. `null` where the runtime cannot report it.
|
|
1783
|
+
*/
|
|
1784
|
+
heapLimit: number | null;
|
|
1785
|
+
/** The process holds this much outside the heap, such as buffers. */
|
|
1786
|
+
external: number;
|
|
1787
|
+
/** The process occupies this much physical memory in total. */
|
|
1788
|
+
rss: number;
|
|
1789
|
+
}
|
|
1336
1790
|
/**
|
|
1337
|
-
*
|
|
1791
|
+
* Whether one index holds worker copies at the moment
|
|
1792
|
+
* {@link Narsil.getMemoryStats} reads it, and how many times it has loaded
|
|
1793
|
+
* them again after giving them up while idle.
|
|
1338
1794
|
*
|
|
1339
1795
|
* @public
|
|
1340
1796
|
*/
|
|
1341
|
-
interface
|
|
1342
|
-
/**
|
|
1343
|
-
|
|
1344
|
-
|
|
1345
|
-
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
/** The engine counts a numeric field's matches into these ranges, with one count for each range. A cluster search counts up to 1,000 ranges on a field and throws `CONFIG_INVALID` for more. */
|
|
1349
|
-
ranges?: Array<{
|
|
1350
|
-
from: number;
|
|
1351
|
-
to: number;
|
|
1352
|
-
}>;
|
|
1353
|
-
};
|
|
1797
|
+
interface WorkerCopyReport {
|
|
1798
|
+
/** This names the index. */
|
|
1799
|
+
indexName: string;
|
|
1800
|
+
/** This is true while every worker holds a copy of the index. */
|
|
1801
|
+
scaledOut: boolean;
|
|
1802
|
+
/** The index has loaded its copies again this many times after an idle spell dropped them. */
|
|
1803
|
+
reloadCount: number;
|
|
1354
1804
|
}
|
|
1355
1805
|
/**
|
|
1356
|
-
*
|
|
1806
|
+
* An index whose checkpoints wait until a failed partition recovers, as
|
|
1807
|
+
* {@link Narsil.getMemoryStats} reports it. The engine holds these
|
|
1808
|
+
* checkpoints only for an index with a vector field, because each vector file
|
|
1809
|
+
* mixes every partition's vectors, so a checkpoint would save the failed
|
|
1810
|
+
* partition's vectors from memory. The write-ahead log of the index grows
|
|
1811
|
+
* until the partition recovers or you restore the index from a snapshot.
|
|
1357
1812
|
*
|
|
1358
1813
|
* @public
|
|
1359
1814
|
*/
|
|
1360
|
-
interface
|
|
1361
|
-
/**
|
|
1362
|
-
|
|
1363
|
-
/**
|
|
1364
|
-
|
|
1365
|
-
/**
|
|
1366
|
-
|
|
1367
|
-
/**
|
|
1368
|
-
|
|
1369
|
-
* an average, including the hits beyond `maxPerGroup`. In cluster mode the
|
|
1370
|
-
* coordinator fetches up to 10,000 hits of each group to fold.
|
|
1371
|
-
*/
|
|
1372
|
-
reduce?: GroupReducer;
|
|
1815
|
+
interface HeldCheckpointReport {
|
|
1816
|
+
/** This is the index whose checkpoints wait. */
|
|
1817
|
+
indexName: string;
|
|
1818
|
+
/** These are the partitions of that index whose copy failed. */
|
|
1819
|
+
partitionIds: number[];
|
|
1820
|
+
/** This many write-ahead log records of the index wait for a checkpoint. */
|
|
1821
|
+
recordsSinceCheckpoint: number;
|
|
1822
|
+
/** The documents in those records hold about this many bytes. */
|
|
1823
|
+
documentBytesSinceCheckpoint: number;
|
|
1373
1824
|
}
|
|
1374
1825
|
/**
|
|
1375
|
-
*
|
|
1826
|
+
* What {@link Narsil.getMemoryStats} returns, which is what you size a host
|
|
1827
|
+
* from.
|
|
1376
1828
|
*
|
|
1377
1829
|
* @public
|
|
1378
1830
|
*/
|
|
1379
|
-
|
|
1831
|
+
interface MemoryStats {
|
|
1380
1832
|
/**
|
|
1381
|
-
*
|
|
1382
|
-
*
|
|
1383
|
-
*
|
|
1384
|
-
*
|
|
1385
|
-
* @param doc - The hit's stored document.
|
|
1386
|
-
* @param score - The hit's relevance score.
|
|
1387
|
-
* @returns The new running value.
|
|
1833
|
+
* V8 heap usage for the host process at the moment of the call. It covers
|
|
1834
|
+
* the whole process, so every Narsil engine in one process returns the same
|
|
1835
|
+
* `process` figures from `getMemoryStats`. `null` in browsers and in any
|
|
1836
|
+
* runtime that does not expose `process.memoryUsage`.
|
|
1388
1837
|
*/
|
|
1389
|
-
|
|
1390
|
-
/** Produces the starting value for each group. The engine calls it once per group. */
|
|
1391
|
-
initialValue: () => unknown;
|
|
1392
|
-
};
|
|
1393
|
-
/**
|
|
1394
|
-
* This configuration names the fields that receive highlighted snippets. It
|
|
1395
|
-
* also sets how the engine marks those snippets up.
|
|
1396
|
-
*
|
|
1397
|
-
* The engine analyses the text of each returned field again to tag every word
|
|
1398
|
-
* that it matched, so it tags the same words whatever the index's
|
|
1399
|
-
* `trackPositions` setting is. It tags a word whose stem equals a query stem,
|
|
1400
|
-
* and a word within the query's `tolerance` of a query stem. For a `prefix`
|
|
1401
|
-
* query, it tags a word for the last query term only when that word completes
|
|
1402
|
-
* the term or shares its stem.
|
|
1403
|
-
*
|
|
1404
|
-
* @public
|
|
1405
|
-
*/
|
|
1406
|
-
interface HighlightConfig {
|
|
1407
|
-
/** The engine highlights these fields. */
|
|
1408
|
-
fields: string[];
|
|
1409
|
-
/** The engine writes this before each match, and writes `<mark>` by default. */
|
|
1410
|
-
preTag?: string;
|
|
1411
|
-
/** The engine writes this after each match, and writes `</mark>` by default. */
|
|
1412
|
-
postTag?: string;
|
|
1838
|
+
process: ProcessMemoryReport | null;
|
|
1413
1839
|
/**
|
|
1414
|
-
* The
|
|
1415
|
-
*
|
|
1416
|
-
*
|
|
1417
|
-
*
|
|
1840
|
+
* The sum of every index's {@link IndexStats.estimatedMemoryBytes} held by
|
|
1841
|
+
* this engine. A formula produces it, so read it as an estimate. It compares
|
|
1842
|
+
* engines inside one process, where `process.heapUsed` cannot tell them
|
|
1843
|
+
* apart.
|
|
1418
1844
|
*/
|
|
1419
|
-
|
|
1845
|
+
estimatedIndexBytes: number;
|
|
1846
|
+
/** This many indexes currently occupy engine memory. */
|
|
1847
|
+
openIndexCount: number;
|
|
1848
|
+
/** This many indexes remain registered without occupying engine memory, including parked recovery failures. */
|
|
1849
|
+
closedIndexCount: number;
|
|
1850
|
+
/** This counts successful index loads since this engine started. */
|
|
1851
|
+
reopenCount: number;
|
|
1852
|
+
/** One entry per index, saying whether it holds worker copies now and how many times it has reloaded them. */
|
|
1853
|
+
workerCopies: WorkerCopyReport[];
|
|
1854
|
+
/** One entry per index whose checkpoints wait until a failed partition recovers. */
|
|
1855
|
+
heldCheckpoints: HeldCheckpointReport[];
|
|
1856
|
+
/**
|
|
1857
|
+
* Per-worker V8 heap usage once the engine has started its worker pool.
|
|
1858
|
+
* Empty while no worker is running.
|
|
1859
|
+
*/
|
|
1860
|
+
workers: Array<{
|
|
1861
|
+
/** This identifies the worker within the pool. */
|
|
1862
|
+
workerId: number;
|
|
1863
|
+
/** That worker is using this much heap. */
|
|
1864
|
+
heapUsed: number;
|
|
1865
|
+
/** V8 has reserved this much heap in that worker. */
|
|
1866
|
+
heapTotal: number;
|
|
1867
|
+
/** That worker's heap may grow to this many bytes, or `null` where its runtime cannot report it. */
|
|
1868
|
+
heapLimit: number | null;
|
|
1869
|
+
/** That worker holds this much outside its heap. */
|
|
1870
|
+
external: number;
|
|
1871
|
+
}>;
|
|
1420
1872
|
}
|
|
1421
1873
|
|
|
1422
1874
|
/**
|
|
@@ -1544,159 +1996,838 @@ type NarsilEventMap = {
|
|
|
1544
1996
|
* `--max-old-space-size-percentage` or `--max-old-space-size`, or close an
|
|
1545
1997
|
* idle index; see {@link ProcessMemoryReport.heapLimit}.
|
|
1546
1998
|
*/
|
|
1547
|
-
heapPressure: {
|
|
1548
|
-
/** This is the index that a write or a load was touching when the heap
|
|
1549
|
-
* reached that point. */
|
|
1550
|
-
indexName: string;
|
|
1551
|
-
/** This is the heap that the process uses, in bytes. */
|
|
1552
|
-
heapUsed: number;
|
|
1553
|
-
/** This is the size in bytes that the heap can grow to. */
|
|
1554
|
-
heapLimit: number;
|
|
1555
|
-
/** This is the estimate of the bytes that the index holds. */
|
|
1556
|
-
estimatedMemoryBytes: number;
|
|
1557
|
-
};
|
|
1558
|
-
/** The engine started, completed, or failed a rebuild that brings the terms
|
|
1559
|
-
* of an index up to the current analysis of its language module. */
|
|
1560
|
-
analysisRebuild: {
|
|
1561
|
-
/** This is the name of the index under rebuild. */
|
|
1562
|
-
indexName: string;
|
|
1563
|
-
/** This is the stage that the rebuild has reached. */
|
|
1564
|
-
status: 'started' | 'completed' | 'failed';
|
|
1565
|
-
/** This is the number of partitions that the rebuild has covered so far. */
|
|
1566
|
-
partitionsRebuilt: number;
|
|
1567
|
-
/** This is the number of partitions that the rebuild covers in total. */
|
|
1568
|
-
partitionCount: number;
|
|
1569
|
-
/** This is the error that stopped the rebuild, which only a `failed`
|
|
1570
|
-
* status includes. */
|
|
1571
|
-
error?: Error;
|
|
1572
|
-
};
|
|
1573
|
-
/** The engine started, completed, or failed the rewrite of an index that you
|
|
1574
|
-
* saved with an earlier release. The engine rewrites the index as it
|
|
1575
|
-
* recovers it, before it serves the index's first request. Because the
|
|
1576
|
-
* engine writes the new manifest last, the earlier files stay intact through
|
|
1577
|
-
* a failed rewrite. The engine then starts the rewrite again the next time
|
|
1578
|
-
* it recovers the index. Without index lifecycle settings, the engine
|
|
1579
|
-
* recovers every index before {@link createNarsil} returns, so pass the
|
|
1580
|
-
* listener in the `events` setting of {@link createNarsil}. */
|
|
1581
|
-
layoutUpgrade: {
|
|
1582
|
-
/** This is the name of the index under rewrite. */
|
|
1583
|
-
indexName: string;
|
|
1584
|
-
/** This is the stage that the rewrite has reached. */
|
|
1585
|
-
status: 'started' | 'completed' | 'failed';
|
|
1586
|
-
/** This is `manifest` where the earlier index is a segment manifest with
|
|
1587
|
-
* its files, and `bundle` where it is a single snapshot bundle. */
|
|
1588
|
-
layout: 'manifest' | 'bundle';
|
|
1589
|
-
/** This is the error that stopped the rewrite, which only a `failed`
|
|
1590
|
-
* status includes. */
|
|
1591
|
-
error?: Error;
|
|
1592
|
-
};
|
|
1593
|
-
/**
|
|
1594
|
-
*
|
|
1595
|
-
|
|
1596
|
-
|
|
1597
|
-
|
|
1598
|
-
|
|
1599
|
-
|
|
1600
|
-
|
|
1601
|
-
|
|
1602
|
-
|
|
1603
|
-
|
|
1604
|
-
|
|
1605
|
-
|
|
1999
|
+
heapPressure: {
|
|
2000
|
+
/** This is the index that a write or a load was touching when the heap
|
|
2001
|
+
* reached that point. */
|
|
2002
|
+
indexName: string;
|
|
2003
|
+
/** This is the heap that the process uses, in bytes. */
|
|
2004
|
+
heapUsed: number;
|
|
2005
|
+
/** This is the size in bytes that the heap can grow to. */
|
|
2006
|
+
heapLimit: number;
|
|
2007
|
+
/** This is the estimate of the bytes that the index holds. */
|
|
2008
|
+
estimatedMemoryBytes: number;
|
|
2009
|
+
};
|
|
2010
|
+
/** The engine started, completed, or failed a rebuild that brings the terms
|
|
2011
|
+
* of an index up to the current analysis of its language module. */
|
|
2012
|
+
analysisRebuild: {
|
|
2013
|
+
/** This is the name of the index under rebuild. */
|
|
2014
|
+
indexName: string;
|
|
2015
|
+
/** This is the stage that the rebuild has reached. */
|
|
2016
|
+
status: 'started' | 'completed' | 'failed';
|
|
2017
|
+
/** This is the number of partitions that the rebuild has covered so far. */
|
|
2018
|
+
partitionsRebuilt: number;
|
|
2019
|
+
/** This is the number of partitions that the rebuild covers in total. */
|
|
2020
|
+
partitionCount: number;
|
|
2021
|
+
/** This is the error that stopped the rebuild, which only a `failed`
|
|
2022
|
+
* status includes. */
|
|
2023
|
+
error?: Error;
|
|
2024
|
+
};
|
|
2025
|
+
/** The engine started, completed, or failed the rewrite of an index that you
|
|
2026
|
+
* saved with an earlier release. The engine rewrites the index as it
|
|
2027
|
+
* recovers it, before it serves the index's first request. Because the
|
|
2028
|
+
* engine writes the new manifest last, the earlier files stay intact through
|
|
2029
|
+
* a failed rewrite. The engine then starts the rewrite again the next time
|
|
2030
|
+
* it recovers the index. Without index lifecycle settings, the engine
|
|
2031
|
+
* recovers every index before {@link createNarsil} returns, so pass the
|
|
2032
|
+
* listener in the `events` setting of {@link createNarsil}. */
|
|
2033
|
+
layoutUpgrade: {
|
|
2034
|
+
/** This is the name of the index under rewrite. */
|
|
2035
|
+
indexName: string;
|
|
2036
|
+
/** This is the stage that the rewrite has reached. */
|
|
2037
|
+
status: 'started' | 'completed' | 'failed';
|
|
2038
|
+
/** This is `manifest` where the earlier index is a segment manifest with
|
|
2039
|
+
* its files, and `bundle` where it is a single snapshot bundle. */
|
|
2040
|
+
layout: 'manifest' | 'bundle';
|
|
2041
|
+
/** This is the error that stopped the rewrite, which only a `failed`
|
|
2042
|
+
* status includes. */
|
|
2043
|
+
error?: Error;
|
|
2044
|
+
};
|
|
2045
|
+
/** The engine stopped taking checkpoints of an index with a vector field,
|
|
2046
|
+
* because one of its partitions failed and each vector file mixes every
|
|
2047
|
+
* partition's vectors. The write-ahead log of the index grows until the
|
|
2048
|
+
* partition recovers; {@link MemoryStats.heldCheckpoints} reports how far. */
|
|
2049
|
+
checkpointHeld: HeldCheckpointReport;
|
|
2050
|
+
/** A write to the write-ahead log or a checkpoint failed, so the writes since
|
|
2051
|
+
* the last checkpoint are at risk. */
|
|
2052
|
+
durabilityError: {
|
|
2053
|
+
/** This is the error that the durability layer threw. */
|
|
2054
|
+
error: Error;
|
|
2055
|
+
};
|
|
2056
|
+
/** The invalidation channel failed, so this instance can serve partitions
|
|
2057
|
+
* that another instance has since changed. */
|
|
2058
|
+
invalidationError: {
|
|
2059
|
+
/** This is the error that the adapter threw. */
|
|
2060
|
+
error: Error;
|
|
2061
|
+
};
|
|
2062
|
+
/**
|
|
2063
|
+
* A popular query suggestions build started, completed, failed, or skipped.
|
|
2064
|
+
* The payload carries counts alone, never a phrase.
|
|
2065
|
+
*/
|
|
2066
|
+
querySuggestionsBuild: QuerySuggestionsBuildEvent;
|
|
2067
|
+
/**
|
|
2068
|
+
* The engine skipped a history file, failed to save the counts of a day,
|
|
2069
|
+
* reached a daily limit, or holds an index with the feature on while it has
|
|
2070
|
+
* no key. The payload carries no search text.
|
|
2071
|
+
*/
|
|
2072
|
+
querySuggestionsWarning: QuerySuggestionsWarningEvent;
|
|
2073
|
+
};
|
|
2074
|
+
/**
|
|
2075
|
+
* This map holds a listener for any event of {@link NarsilEventMap}, so that
|
|
2076
|
+
* the engine can register each listener before it starts.
|
|
2077
|
+
*
|
|
2078
|
+
* @public
|
|
2079
|
+
*/
|
|
2080
|
+
type NarsilEventHandlers = {
|
|
2081
|
+
[K in keyof NarsilEventMap]?: (payload: NarsilEventMap[K]) => void;
|
|
2082
|
+
};
|
|
2083
|
+
|
|
2084
|
+
/**
|
|
2085
|
+
* Registers the adapters that indexes and queries reach by name, which is
|
|
2086
|
+
* what lets a binding outlive a restart and reach a worker thread or another
|
|
2087
|
+
* node.
|
|
2088
|
+
*
|
|
2089
|
+
* @public
|
|
2090
|
+
*/
|
|
2091
|
+
interface AdapterRegistrationOperations {
|
|
2092
|
+
/**
|
|
2093
|
+
* Registers an embedding adapter under a name that an index config can
|
|
2094
|
+
* give and that durability metadata keeps. Registering a name again binds
|
|
2095
|
+
* every index that gives that name to the new adapter.
|
|
2096
|
+
*
|
|
2097
|
+
* @param name - The name that an index config gives in `embedding.adapter`.
|
|
2098
|
+
* @param adapter - The adapter that embeds documents and queries.
|
|
2099
|
+
*/
|
|
2100
|
+
registerEmbeddingAdapter(name: string, adapter: EmbeddingAdapter): void;
|
|
2101
|
+
/**
|
|
2102
|
+
* Registers a rerank adapter under a name that a query gives in
|
|
2103
|
+
* `rerank.adapter`. Registering a name again sends every later query that
|
|
2104
|
+
* gives that name to the new adapter. The engine throws
|
|
2105
|
+
* `RERANK_CONFIG_INVALID` for an empty name and for an adapter without a
|
|
2106
|
+
* `rerank` function.
|
|
2107
|
+
*
|
|
2108
|
+
* @param name - The name that a query gives in `rerank.adapter`.
|
|
2109
|
+
* @param adapter - The adapter that scores the top hits of a query.
|
|
2110
|
+
*/
|
|
2111
|
+
registerRerankAdapter(name: string, adapter: RerankAdapter): void;
|
|
2112
|
+
}
|
|
2113
|
+
|
|
2114
|
+
/**
|
|
2115
|
+
* The analysis settings that {@link AnalysisOperations.changeAnalysis} changes
|
|
2116
|
+
* on a live index. A key that you leave out keeps its current value.
|
|
2117
|
+
*
|
|
2118
|
+
* @public
|
|
2119
|
+
*/
|
|
2120
|
+
interface AnalysisChange {
|
|
2121
|
+
/** This is the name of a registered language. */
|
|
2122
|
+
language?: string;
|
|
2123
|
+
/**
|
|
2124
|
+
* This is a name that {@link registerTokenizer} bound. Pass `null` to return
|
|
2125
|
+
* to the tokeniser of the language.
|
|
2126
|
+
*/
|
|
2127
|
+
tokenizer?: string | null;
|
|
2128
|
+
/**
|
|
2129
|
+
* This is a name that {@link registerStopWords} bound, or a list of words.
|
|
2130
|
+
* Pass `null` to return to the stop words of the language.
|
|
2131
|
+
*/
|
|
2132
|
+
stopWords?: string | readonly string[] | ReadonlySet<string> | null;
|
|
2133
|
+
}
|
|
2134
|
+
/**
|
|
2135
|
+
* Changes how an index turns text into terms while the index keeps answering
|
|
2136
|
+
* searches.
|
|
2137
|
+
*
|
|
2138
|
+
* @public
|
|
2139
|
+
*/
|
|
2140
|
+
interface AnalysisOperations {
|
|
2141
|
+
/**
|
|
2142
|
+
* Gives you an index that matches text under new settings, while the index
|
|
2143
|
+
* keeps answering searches and accepting writes.
|
|
2144
|
+
*
|
|
2145
|
+
* The engine builds the new terms beside the old ones. Searches keep matching
|
|
2146
|
+
* under the old settings during that time, while every write that the engine
|
|
2147
|
+
* accepts reaches the new terms. Each search matches under one set of
|
|
2148
|
+
* settings, either the old or the new, and the rebuild leaves vectors alone.
|
|
2149
|
+
* The promise resolves once a durable checkpoint holds the new terms, or once
|
|
2150
|
+
* the switch happens on an engine without durability. After a restart at any
|
|
2151
|
+
* point, the engine goes on to finish the change.
|
|
2152
|
+
*
|
|
2153
|
+
* @param indexName - The index to change.
|
|
2154
|
+
* @param change - The settings to change. A change to the values that the
|
|
2155
|
+
* index already holds completes with no rebuild.
|
|
2156
|
+
* @throws A `NarsilError` with `LANGUAGE_NOT_SUPPORTED` for an unregistered
|
|
2157
|
+
* language, with `CONFIG_INVALID` for an unregistered name, a tokeniser
|
|
2158
|
+
* instance, a stop word function, or a synonym word that breaks the synonym
|
|
2159
|
+
* rules under the new settings, with `ANALYSIS_REBUILD_MEMORY_EXCEEDED` when a
|
|
2160
|
+
* second copy of the terms does not fit in memory, with
|
|
2161
|
+
* `ANALYSIS_CHANGE_REPLACED` when a later change or a restore replaces this
|
|
2162
|
+
* one or when a restore of the index is in flight, with
|
|
2163
|
+
* `ANALYSIS_CHANGE_NOT_READY` when the previous change has no durable
|
|
2164
|
+
* checkpoint yet, with `PERSISTENCE_SAVE_FAILED` when the new terms
|
|
2165
|
+
* answer searches before a durable checkpoint holds them, and with
|
|
2166
|
+
* `PARTITION_REBALANCING_BACKPRESSURE` during a rebalance.
|
|
2167
|
+
*/
|
|
2168
|
+
changeAnalysis(indexName: string, change: AnalysisChange): Promise<void>;
|
|
2169
|
+
}
|
|
2170
|
+
|
|
2171
|
+
/**
|
|
2172
|
+
* Changes the BM25 setting of a live index, which
|
|
2173
|
+
* {@link IndexConfig.bm25} sets when the index is created.
|
|
2174
|
+
*
|
|
2175
|
+
* @public
|
|
2176
|
+
*/
|
|
2177
|
+
interface BM25Operations {
|
|
2178
|
+
/**
|
|
2179
|
+
* Replaces the BM25 setting of an index, so that every search that starts
|
|
2180
|
+
* after the promise resolves scores under the new setting.
|
|
2181
|
+
*
|
|
2182
|
+
* The call replaces the whole setting, so a value that it leaves out returns
|
|
2183
|
+
* to its default, and `{}` clears the setting. The engine rebuilds nothing,
|
|
2184
|
+
* because the setting changes no stored token. It saves the setting with the
|
|
2185
|
+
* index, so the setting stays in place after a restart, and every snapshot
|
|
2186
|
+
* of the index includes it. Where the index has copies on worker threads,
|
|
2187
|
+
* the promise resolves only once every copy holds the new setting. A cursor
|
|
2188
|
+
* from before the change keeps working, and its next pages can repeat or
|
|
2189
|
+
* skip documents, because the scores that order them can change.
|
|
2190
|
+
*
|
|
2191
|
+
* @param indexName - The index whose setting the engine replaces.
|
|
2192
|
+
* @param bm25 - The new setting, in the shape that {@link BM25Params} describes.
|
|
2193
|
+
* @throws A `NarsilError` with `CONFIG_INVALID` when `k1` is not a number from
|
|
2194
|
+
* 0 to 1,000, when `b` is not a number from 0 to 1, or when `fields` holds a
|
|
2195
|
+
* name that is not a text field. The index then keeps the setting that it
|
|
2196
|
+
* held before the call.
|
|
2197
|
+
*/
|
|
2198
|
+
updateBM25(indexName: string, bm25: BM25Params): Promise<void>;
|
|
2199
|
+
}
|
|
2200
|
+
|
|
2201
|
+
/**
|
|
2202
|
+
* The bytes that {@link Narsil.restore} and {@link Narsil.importDocumentExport}
|
|
2203
|
+
* accept, as one array, a stream of chunks, or an async iterable of chunks,
|
|
2204
|
+
* such as a Node.js file stream.
|
|
2205
|
+
*
|
|
2206
|
+
* @public
|
|
2207
|
+
*/
|
|
2208
|
+
type ByteSource = Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
|
|
2209
|
+
|
|
2210
|
+
/**
|
|
2211
|
+
* Opens and closes durable indexes without deleting them.
|
|
2212
|
+
*
|
|
2213
|
+
* @public
|
|
2214
|
+
*/
|
|
2215
|
+
interface IndexLifecycleOperations {
|
|
2216
|
+
/**
|
|
2217
|
+
* Loads a closed index from its durable checkpoint and resets a parked recovery failure.
|
|
2218
|
+
*
|
|
2219
|
+
* @param indexName - The index to load.
|
|
2220
|
+
* @returns A promise that settles when the index is ready for operations.
|
|
2221
|
+
*/
|
|
2222
|
+
open(indexName: string): Promise<void>;
|
|
2223
|
+
/**
|
|
2224
|
+
* Drains active work, checkpoints the index, releases its memory, and keeps its durable files.
|
|
2225
|
+
*
|
|
2226
|
+
* @param indexName - The index to close.
|
|
2227
|
+
* @returns A promise that settles after the index releases its memory.
|
|
2228
|
+
*/
|
|
2229
|
+
close(indexName: string): Promise<void>;
|
|
2230
|
+
}
|
|
2231
|
+
|
|
2232
|
+
/**
|
|
2233
|
+
* The device sync setting of one index, which {@link SyncOperations.updateSync} takes.
|
|
2234
|
+
*
|
|
2235
|
+
* Turn sync on only for an index whose every document belongs to one user, because every device that syncs the index
|
|
2236
|
+
* receives the whole index. Create one index for each user, and leave sync off for a public index or for an index that
|
|
2237
|
+
* holds the data of several users.
|
|
2238
|
+
*
|
|
2239
|
+
* @public
|
|
2240
|
+
*/
|
|
2241
|
+
interface SyncSetting {
|
|
2242
|
+
/** This turns sync on or off. Turning it on gives the index a new epoch, so every synced device loads a new copy. */
|
|
2243
|
+
enabled: boolean;
|
|
2244
|
+
/** This is the age in milliseconds after which the server deletes a log segment from history. It defaults to 30
|
|
2245
|
+
* days. */
|
|
2246
|
+
historyMaxAgeMs?: number;
|
|
2247
|
+
/** This is the byte count above which the server deletes the oldest log segment from history. It defaults to the
|
|
2248
|
+
* length of the published snapshot. */
|
|
2249
|
+
historyMaxBytes?: number;
|
|
2250
|
+
}
|
|
2251
|
+
/**
|
|
2252
|
+
* The device sync state of one index, which {@link SyncOperations.getSync} returns.
|
|
2253
|
+
*
|
|
2254
|
+
* @public
|
|
2255
|
+
*/
|
|
2256
|
+
interface SyncStatus extends SyncSetting {
|
|
2257
|
+
/** This is true once a device has asked for the published snapshot, from when the server keeps history. */
|
|
2258
|
+
active: boolean;
|
|
2259
|
+
/** This is the index epoch, 32 lowercase hexadecimal digits, or `null` while sync is off. */
|
|
2260
|
+
epoch: string | null;
|
|
2261
|
+
}
|
|
2262
|
+
/**
|
|
2263
|
+
* The methods that turn device sync on and off for an index.
|
|
2264
|
+
*
|
|
2265
|
+
* @public
|
|
2266
|
+
*/
|
|
2267
|
+
interface SyncOperations {
|
|
2268
|
+
/**
|
|
2269
|
+
* Replaces the device sync setting of an index.
|
|
2270
|
+
*
|
|
2271
|
+
* Turning sync on gives the index a new epoch. Changing a history limit while sync is on keeps the epoch. Turning
|
|
2272
|
+
* sync off deletes the published snapshot and the history, and the server closes every feed of the index with
|
|
2273
|
+
* close code 4410. The engine saves the setting with the index, so the setting stays in place after a restart, and
|
|
2274
|
+
* no snapshot of the index includes it.
|
|
2275
|
+
*
|
|
2276
|
+
* @param indexName - The index whose setting the engine replaces.
|
|
2277
|
+
* @param setting - The new setting.
|
|
2278
|
+
* @throws A `NarsilError` with `SYNC_DURABILITY_REQUIRED` when the engine has no write-ahead log durability, and
|
|
2279
|
+
* with `CONFIG_INVALID` when a history limit is not a positive whole number.
|
|
2280
|
+
*/
|
|
2281
|
+
updateSync(indexName: string, setting: SyncSetting): Promise<void>;
|
|
2282
|
+
/**
|
|
2283
|
+
* Returns the device sync state of an index.
|
|
2284
|
+
*
|
|
2285
|
+
* @param indexName - The index whose state the engine returns.
|
|
2286
|
+
* @returns The setting, whether a device has asked for the snapshot, and the epoch.
|
|
2287
|
+
* @throws A `NarsilError` with `INDEX_NOT_FOUND` when no index has that name.
|
|
2288
|
+
*/
|
|
2289
|
+
getSync(indexName: string): Promise<SyncStatus>;
|
|
2290
|
+
}
|
|
2291
|
+
|
|
2292
|
+
/**
|
|
2293
|
+
* Reads and replaces the synonym set of an index, which
|
|
2294
|
+
* {@link IndexConfig.synonyms} sets when the index is created.
|
|
2295
|
+
*
|
|
2296
|
+
* @public
|
|
2297
|
+
*/
|
|
2298
|
+
interface SynonymOperations {
|
|
2299
|
+
/**
|
|
2300
|
+
* Replaces the synonym set of an index, so that every search that starts
|
|
2301
|
+
* after the promise resolves expands its words with the new set.
|
|
2302
|
+
*
|
|
2303
|
+
* The engine applies the set without rebuilding the index, because a
|
|
2304
|
+
* synonym set changes no stored token. It saves the set with the index, so
|
|
2305
|
+
* the set stays in place after a restart, and every snapshot of the index
|
|
2306
|
+
* includes it. Where the index has copies on worker threads, the promise
|
|
2307
|
+
* resolves only once every copy uses the new set. Pass an empty list to
|
|
2308
|
+
* remove the set.
|
|
2309
|
+
*
|
|
2310
|
+
* @param indexName - The index whose set the engine replaces.
|
|
2311
|
+
* @param synonyms - The new set, in the shape that {@link SynonymRule}
|
|
2312
|
+
* describes.
|
|
2313
|
+
* @throws A `NarsilError` with `CONFIG_INVALID` when a rule breaks that
|
|
2314
|
+
* shape, when a word analyses to no token or to more than one, or when the
|
|
2315
|
+
* set passes 100,000 rules, 500,000 words, or 4,194,304 bytes of words in
|
|
2316
|
+
* UTF-8. The index then keeps the set that it held before the call.
|
|
2317
|
+
*/
|
|
2318
|
+
updateSynonyms(indexName: string, synonyms: SynonymRule[]): Promise<void>;
|
|
2319
|
+
/**
|
|
2320
|
+
* Returns the synonym set of an index with every word as the caller wrote
|
|
2321
|
+
* it, or an empty list when the index holds no set.
|
|
2322
|
+
*
|
|
2323
|
+
* @param indexName - The index whose set the engine returns.
|
|
2324
|
+
*/
|
|
2325
|
+
getSynonyms(indexName: string): Promise<SynonymRule[]>;
|
|
2326
|
+
}
|
|
2327
|
+
|
|
1606
2328
|
/**
|
|
1607
|
-
*
|
|
1608
|
-
* the engine can register each listener before it starts.
|
|
2329
|
+
* Reports on and rebuilds the graphs of an index's vector fields.
|
|
1609
2330
|
*
|
|
1610
2331
|
* @public
|
|
1611
2332
|
*/
|
|
1612
|
-
|
|
1613
|
-
|
|
1614
|
-
|
|
2333
|
+
interface VectorMaintenanceOperations {
|
|
2334
|
+
/**
|
|
2335
|
+
* Rebuilds a vector field's graph without the tombstones removed documents
|
|
2336
|
+
* left behind, which returns the memory they held and speeds searches up.
|
|
2337
|
+
*
|
|
2338
|
+
* Read {@link VectorMaintenanceOperations.vectorMaintenanceStatus} first to
|
|
2339
|
+
* see whether the work is worth its cost.
|
|
2340
|
+
*
|
|
2341
|
+
* @param indexName - The index holding the field.
|
|
2342
|
+
* @param fieldName - The vector field to compact. Omit it to compact every
|
|
2343
|
+
* vector field in the index.
|
|
2344
|
+
*/
|
|
2345
|
+
compactVectors(indexName: string, fieldName?: string): Promise<void>;
|
|
2346
|
+
/**
|
|
2347
|
+
* Rebuilds a vector field's graph from scratch, which recovers the recall a
|
|
2348
|
+
* long run of inserts and removals costs.
|
|
2349
|
+
*
|
|
2350
|
+
* This is heavier than {@link VectorMaintenanceOperations.compactVectors} and
|
|
2351
|
+
* gives a better graph, so run it once a search starts missing documents it
|
|
2352
|
+
* should find, rather than on a schedule.
|
|
2353
|
+
*
|
|
2354
|
+
* @param indexName - The index holding the field.
|
|
2355
|
+
* @param fieldName - The vector field to rebuild. Omit it to rebuild every
|
|
2356
|
+
* vector field in the index.
|
|
2357
|
+
*/
|
|
2358
|
+
optimizeVectors(indexName: string, fieldName?: string): Promise<void>;
|
|
2359
|
+
/**
|
|
2360
|
+
* Reports the state of each vector field in an index, and what compaction or
|
|
2361
|
+
* optimisation would cost.
|
|
2362
|
+
*
|
|
2363
|
+
* @param indexName - The index to describe.
|
|
2364
|
+
* @returns One entry per vector field, or an empty list while the index is closed.
|
|
2365
|
+
*/
|
|
2366
|
+
vectorMaintenanceStatus(indexName: string): VectorMaintenanceResult[];
|
|
2367
|
+
}
|
|
1615
2368
|
|
|
1616
2369
|
/**
|
|
1617
|
-
*
|
|
1618
|
-
*
|
|
1619
|
-
*
|
|
2370
|
+
* Adds, replaces, and removes documents, and waits for the worker copies to
|
|
2371
|
+
* catch up with those writes.
|
|
2372
|
+
*
|
|
2373
|
+
* A write returns once the main copy holds it, and the worker copies apply
|
|
2374
|
+
* it afterwards, so a query that a copy answers can come back without a write
|
|
2375
|
+
* that returned before it. Every write takes a `wait` option for the cases
|
|
2376
|
+
* where the next query has to see it.
|
|
1620
2377
|
*
|
|
1621
2378
|
* @public
|
|
1622
2379
|
*/
|
|
1623
|
-
interface
|
|
1624
|
-
/** The process is using this much heap. */
|
|
1625
|
-
heapUsed: number;
|
|
1626
|
-
/** V8 has reserved this much heap. */
|
|
1627
|
-
heapTotal: number;
|
|
2380
|
+
interface DocumentWriteOperations {
|
|
1628
2381
|
/**
|
|
1629
|
-
*
|
|
1630
|
-
*
|
|
1631
|
-
*
|
|
1632
|
-
*
|
|
2382
|
+
* Adds one document to an index and returns the id it is stored under.
|
|
2383
|
+
*
|
|
2384
|
+
* The id comes from the `docId` argument when you pass one, otherwise from
|
|
2385
|
+
* the document's own `id` field, and otherwise the engine generates it. Use
|
|
2386
|
+
* {@link DocumentWriteOperations.insertBatch} for a large load, so that one
|
|
2387
|
+
* bad document cannot abandon the rest.
|
|
2388
|
+
*
|
|
2389
|
+
* @param indexName - The index that receives the document.
|
|
2390
|
+
* @param document - Its fields must match the types the schema declares.
|
|
2391
|
+
* @param docId - Pass an id to control it yourself, or omit it and read the
|
|
2392
|
+
* returned value. An id that differs from the document's own `id` field
|
|
2393
|
+
* raises `DOC_VALIDATION_FAILED`, because the stored document would
|
|
2394
|
+
* otherwise contradict the key that it is stored under.
|
|
2395
|
+
* @param options - Per-write settings, such as skipping the defensive copy
|
|
2396
|
+
* or waiting for every worker copy to apply the write.
|
|
2397
|
+
* @returns The id the document is stored under.
|
|
1633
2398
|
*/
|
|
1634
|
-
|
|
1635
|
-
/**
|
|
1636
|
-
|
|
1637
|
-
|
|
1638
|
-
|
|
2399
|
+
insert(indexName: string, document: AnyDocument, docId?: string, options?: InsertOptions): Promise<string>;
|
|
2400
|
+
/**
|
|
2401
|
+
* Adds many documents in one pass and reports each one's outcome.
|
|
2402
|
+
*
|
|
2403
|
+
* A document the engine rejects appears in `failed` with the error that
|
|
2404
|
+
* rejected it, and every other document is still written, which is what
|
|
2405
|
+
* makes this the call to load a corpus with.
|
|
2406
|
+
*
|
|
2407
|
+
* @param indexName - The index that receives the documents.
|
|
2408
|
+
* @param documents - The documents to write, each carrying its own id or
|
|
2409
|
+
* leaving the engine to generate one.
|
|
2410
|
+
* @param options - Per-write settings applied to every document.
|
|
2411
|
+
* @returns The ids written, and each rejection with its error.
|
|
2412
|
+
*/
|
|
2413
|
+
insertBatch(indexName: string, documents: AnyDocument[], options?: InsertOptions): Promise<BatchResult>;
|
|
2414
|
+
/**
|
|
2415
|
+
* Removes one document.
|
|
2416
|
+
*
|
|
2417
|
+
* @param indexName - The index holding the document.
|
|
2418
|
+
* @param docId - The document to remove.
|
|
2419
|
+
* @param options - Per-write settings, such as waiting for every worker
|
|
2420
|
+
* copy to apply the removal.
|
|
2421
|
+
* @throws A `NarsilError` with `DOC_NOT_FOUND` when the index holds no such
|
|
2422
|
+
* document.
|
|
2423
|
+
*/
|
|
2424
|
+
remove(indexName: string, docId: string, options?: WriteOptions): Promise<void>;
|
|
2425
|
+
/**
|
|
2426
|
+
* Removes many documents in one pass and reports each one's outcome.
|
|
2427
|
+
*
|
|
2428
|
+
* @param indexName - The index holding the documents.
|
|
2429
|
+
* @param docIds - The documents to remove.
|
|
2430
|
+
* @param options - Per-write settings applied to the whole batch.
|
|
2431
|
+
* @returns The ids removed, and each failure with its error.
|
|
2432
|
+
*/
|
|
2433
|
+
removeBatch(indexName: string, docIds: string[], options?: WriteOptions): Promise<BatchResult>;
|
|
2434
|
+
/**
|
|
2435
|
+
* Replaces a stored document with the one you pass.
|
|
2436
|
+
*
|
|
2437
|
+
* The engine removes the old document and indexes the new one, so the
|
|
2438
|
+
* document you supply has to be complete, with every field it should hold
|
|
2439
|
+
* afterwards.
|
|
2440
|
+
*
|
|
2441
|
+
* @param indexName - The index holding the document.
|
|
2442
|
+
* @param docId - The document to replace.
|
|
2443
|
+
* @param document - The complete replacement.
|
|
2444
|
+
* @param options - Per-write settings, such as waiting for every worker
|
|
2445
|
+
* copy to apply the replacement.
|
|
2446
|
+
*/
|
|
2447
|
+
update(indexName: string, docId: string, document: AnyDocument, options?: WriteOptions): Promise<void>;
|
|
2448
|
+
/**
|
|
2449
|
+
* Replaces many documents in one pass and reports each one's outcome.
|
|
2450
|
+
*
|
|
2451
|
+
* @param indexName - The index holding the documents.
|
|
2452
|
+
* @param updates - Each id with the complete document that replaces it.
|
|
2453
|
+
* @param options - Per-write settings applied to the whole batch.
|
|
2454
|
+
* @returns The ids replaced, and each failure with its error.
|
|
2455
|
+
*/
|
|
2456
|
+
updateBatch(indexName: string, updates: Array<{
|
|
2457
|
+
docId: string;
|
|
2458
|
+
document: AnyDocument;
|
|
2459
|
+
}>, options?: WriteOptions): Promise<BatchResult>;
|
|
2460
|
+
/**
|
|
2461
|
+
* Resolves once every worker copy of an index has applied every write that
|
|
2462
|
+
* returned before the call.
|
|
2463
|
+
*
|
|
2464
|
+
* Call this after a run of writes, or pass `wait: true` on one write,
|
|
2465
|
+
* before a query that has to see them. An index that holds no copies
|
|
2466
|
+
* resolves at once.
|
|
2467
|
+
*
|
|
2468
|
+
* @param indexName - The index whose copies have to catch up.
|
|
2469
|
+
*/
|
|
2470
|
+
waitForWrites(indexName: string): Promise<void>;
|
|
1639
2471
|
}
|
|
2472
|
+
|
|
1640
2473
|
/**
|
|
1641
|
-
*
|
|
1642
|
-
* {@link Narsil.getMemoryStats} reads it, and how many times it has loaded
|
|
1643
|
-
* them again after giving them up while idle.
|
|
2474
|
+
* What {@link Narsil.snapshot} adds to the archive beyond the checkpoint.
|
|
1644
2475
|
*
|
|
1645
2476
|
* @public
|
|
1646
2477
|
*/
|
|
1647
|
-
interface
|
|
1648
|
-
/**
|
|
1649
|
-
|
|
1650
|
-
|
|
1651
|
-
|
|
1652
|
-
|
|
1653
|
-
|
|
2478
|
+
interface SnapshotOptions {
|
|
2479
|
+
/**
|
|
2480
|
+
* Set this to add the index's popular query history, which holds raw
|
|
2481
|
+
* searches, so that a restore on a node with the same key keeps the counts.
|
|
2482
|
+
* Defaults to false, because a backup that holds history can keep searches
|
|
2483
|
+
* past their retention.
|
|
2484
|
+
*/
|
|
2485
|
+
queryHistory?: boolean;
|
|
1654
2486
|
}
|
|
1655
2487
|
/**
|
|
1656
|
-
*
|
|
1657
|
-
*
|
|
2488
|
+
* The search engine, and everything you do with it.
|
|
2489
|
+
*
|
|
2490
|
+
* One instance holds every index you create, so an application usually keeps a
|
|
2491
|
+
* single engine for its lifetime and reaches each index by name. Build one
|
|
2492
|
+
* with {@link createNarsil}. Its write, open and close, synonym, analysis, BM25,
|
|
2493
|
+
* device sync, change capture, vector maintenance, and adapter registration
|
|
2494
|
+
* methods come from {@link DocumentWriteOperations},
|
|
2495
|
+
* {@link IndexLifecycleOperations}, {@link SynonymOperations},
|
|
2496
|
+
* {@link AnalysisOperations}, {@link BM25Operations}, {@link SyncOperations},
|
|
2497
|
+
* {@link ChangesOperations}, {@link VectorMaintenanceOperations}, and
|
|
2498
|
+
* {@link AdapterRegistrationOperations}.
|
|
1658
2499
|
*
|
|
1659
2500
|
* @public
|
|
1660
2501
|
*/
|
|
1661
|
-
interface
|
|
2502
|
+
interface Narsil extends IndexLifecycleOperations, DocumentWriteOperations, SynonymOperations, AnalysisOperations, BM25Operations, SyncOperations, ChangesOperations, VectorMaintenanceOperations, AdapterRegistrationOperations {
|
|
1662
2503
|
/**
|
|
1663
|
-
*
|
|
1664
|
-
*
|
|
1665
|
-
*
|
|
1666
|
-
*
|
|
2504
|
+
* Creates an index you can insert documents into and query.
|
|
2505
|
+
*
|
|
2506
|
+
* The schema sets the type of each field, marks which fields you can
|
|
2507
|
+
* filter and sort on, and controls how the engine tokenises text. The
|
|
2508
|
+
* `language` option picks the analyser that stems those text fields.
|
|
2509
|
+
*
|
|
2510
|
+
* @param name - Every later call uses this name to reach the index.
|
|
2511
|
+
* @param config - This carries the schema, and the language, partitioning,
|
|
2512
|
+
* and scoring settings.
|
|
1667
2513
|
*/
|
|
1668
|
-
|
|
2514
|
+
createIndex(name: string, config: IndexConfig): Promise<void>;
|
|
1669
2515
|
/**
|
|
1670
|
-
*
|
|
1671
|
-
*
|
|
1672
|
-
*
|
|
1673
|
-
*
|
|
2516
|
+
* Removes an index and everything it holds, including whatever persistence
|
|
2517
|
+
* wrote for it. The documents do not come back.
|
|
2518
|
+
*
|
|
2519
|
+
* @param name - The index to drop.
|
|
1674
2520
|
*/
|
|
1675
|
-
|
|
1676
|
-
/** This many indexes currently occupy engine memory. */
|
|
1677
|
-
openIndexCount: number;
|
|
1678
|
-
/** This many indexes remain registered without occupying engine memory, including parked recovery failures. */
|
|
1679
|
-
closedIndexCount: number;
|
|
1680
|
-
/** This counts successful index loads since this engine started. */
|
|
1681
|
-
reopenCount: number;
|
|
1682
|
-
/** One entry per index, saying whether it holds worker copies now and how many times it has reloaded them. */
|
|
1683
|
-
workerCopies: WorkerCopyReport[];
|
|
2521
|
+
dropIndex(name: string): Promise<void>;
|
|
1684
2522
|
/**
|
|
1685
|
-
*
|
|
1686
|
-
*
|
|
2523
|
+
* Lists every index this engine holds, with its size and its language.
|
|
2524
|
+
*
|
|
2525
|
+
* @returns One entry per index, in creation order.
|
|
1687
2526
|
*/
|
|
1688
|
-
|
|
1689
|
-
|
|
1690
|
-
|
|
1691
|
-
|
|
1692
|
-
|
|
1693
|
-
|
|
1694
|
-
|
|
1695
|
-
|
|
1696
|
-
|
|
1697
|
-
|
|
1698
|
-
|
|
1699
|
-
|
|
2527
|
+
listIndexes(): IndexInfo[];
|
|
2528
|
+
/**
|
|
2529
|
+
* Returns one index's document count, partition count, memory estimate,
|
|
2530
|
+
* language, and schema.
|
|
2531
|
+
*
|
|
2532
|
+
* @param indexName - The index to describe.
|
|
2533
|
+
* @returns The index's current figures.
|
|
2534
|
+
* @throws A `NarsilError` with `INDEX_NOT_FOUND` for an unknown name.
|
|
2535
|
+
*/
|
|
2536
|
+
getStats(indexName: string): IndexStats;
|
|
2537
|
+
/**
|
|
2538
|
+
* Returns per-partition figures for one index, which is where you look when
|
|
2539
|
+
* an index grows unevenly or a rebalance is worth running.
|
|
2540
|
+
*
|
|
2541
|
+
* @param indexName - The index to describe.
|
|
2542
|
+
* @returns One entry per open partition, in partition order, or an empty list while the index is closed.
|
|
2543
|
+
*/
|
|
2544
|
+
getPartitionStats(indexName: string): PartitionStatsResult[];
|
|
2545
|
+
/**
|
|
2546
|
+
* Fetches one stored document by id, without searching.
|
|
2547
|
+
*
|
|
2548
|
+
* A vector field comes back as a `Float32Array`, whatever form you give it.
|
|
2549
|
+
* `JSON.stringify` writes one as an object keyed by index, so convert it
|
|
2550
|
+
* with `Array.from`, or project the field away, before you serialise the
|
|
2551
|
+
* document yourself. The HTTP routes convert it for you.
|
|
2552
|
+
*
|
|
2553
|
+
* @param indexName - The index holding the document.
|
|
2554
|
+
* @param docId - The document to fetch.
|
|
2555
|
+
* @returns The document, or `undefined` when the index holds no such id.
|
|
2556
|
+
*/
|
|
2557
|
+
get(indexName: string, docId: string): Promise<AnyDocument | undefined>;
|
|
2558
|
+
/**
|
|
2559
|
+
* Fetches many stored documents by id in one pass.
|
|
2560
|
+
*
|
|
2561
|
+
* @param indexName - The index holding the documents.
|
|
2562
|
+
* @param docIds - The documents to fetch.
|
|
2563
|
+
* @returns A map from id to document, holding an entry for each id that
|
|
2564
|
+
* exists and nothing for the rest.
|
|
2565
|
+
*/
|
|
2566
|
+
getMultiple(indexName: string, docIds: string[]): Promise<Map<string, AnyDocument>>;
|
|
2567
|
+
/**
|
|
2568
|
+
* Reports whether an index holds a document, without reading it.
|
|
2569
|
+
*
|
|
2570
|
+
* @param indexName - The index to check.
|
|
2571
|
+
* @param docId - The document to look for.
|
|
2572
|
+
* @returns True when the index holds that id.
|
|
2573
|
+
*/
|
|
2574
|
+
has(indexName: string, docId: string): Promise<boolean>;
|
|
2575
|
+
/**
|
|
2576
|
+
* Counts the documents an index holds.
|
|
2577
|
+
*
|
|
2578
|
+
* @param indexName - The index to count.
|
|
2579
|
+
* @returns The document count across every partition.
|
|
2580
|
+
*/
|
|
2581
|
+
countDocuments(indexName: string): Promise<number>;
|
|
2582
|
+
/**
|
|
2583
|
+
* Reads one page of stored documents in document-id order, without
|
|
2584
|
+
* searching, which is how you page through a whole index.
|
|
2585
|
+
*
|
|
2586
|
+
* Leave `cursor` out for the first page, pass the returned cursor back for
|
|
2587
|
+
* each page after it, and stop when the cursor comes back null. A document
|
|
2588
|
+
* that stays in the index for the whole listing comes back exactly once. The
|
|
2589
|
+
* engine skips a document you remove part-way through. It returns one you
|
|
2590
|
+
* insert part-way through once that document's id sorts above the cursor.
|
|
2591
|
+
* The cursor holds no engine state, so it stays valid after a restart, a
|
|
2592
|
+
* snapshot restore, and a rebalance.
|
|
2593
|
+
*
|
|
2594
|
+
* The engine compares document ids by their UTF-16 code units, so `"10"`
|
|
2595
|
+
* sorts ahead of `"9"`.
|
|
2596
|
+
*
|
|
2597
|
+
* Set `document` to drop a vector field, because the engine otherwise reads
|
|
2598
|
+
* every listed document's vector back out of the index.
|
|
2599
|
+
*
|
|
2600
|
+
* @typeParam T - Shape of the stored documents, which flows through to each
|
|
2601
|
+
* entry's `document`.
|
|
2602
|
+
* @param indexName - The index to walk.
|
|
2603
|
+
* @param params - These set the cursor, the page size, the filter, and how
|
|
2604
|
+
* much of each document comes back.
|
|
2605
|
+
* @returns The page, the cursor for the next page, how many documents the
|
|
2606
|
+
* listing walks in total, and the time the page took.
|
|
2607
|
+
*/
|
|
2608
|
+
listDocuments<T = AnyDocument>(indexName: string, params?: ListParams): Promise<ListResult<T>>;
|
|
2609
|
+
/**
|
|
2610
|
+
* Runs a search against an index and returns the ranked hits.
|
|
2611
|
+
*
|
|
2612
|
+
* One call covers keyword search, vector search, and a hybrid of the two,
|
|
2613
|
+
* chosen by the `mode` parameter. BM25 ranks keyword results by default.
|
|
2614
|
+
* Every hit carries its score and its document, along with highlights when
|
|
2615
|
+
* you ask for them.
|
|
2616
|
+
*
|
|
2617
|
+
* @typeParam T - Shape of the stored documents, which flows through to each
|
|
2618
|
+
* hit's `document`.
|
|
2619
|
+
* @param indexName - The index the search runs against.
|
|
2620
|
+
* @param params - These set the search term, filters, field boosts, sorting,
|
|
2621
|
+
* facets, highlighting, and the result limit.
|
|
2622
|
+
* @returns The hits, the total count, the elapsed time, and any facets or
|
|
2623
|
+
* groups the query asked for.
|
|
2624
|
+
*/
|
|
2625
|
+
query<T = AnyDocument>(indexName: string, params: QueryParams): Promise<QueryResult<T>>;
|
|
2626
|
+
/**
|
|
2627
|
+
* Counts what a query would match without building a single hit, which is
|
|
2628
|
+
* how a result-count badge stays cheap. A full-text count also skips scoring
|
|
2629
|
+
* unless the query carries `minScore`, which prunes matches by score, or a
|
|
2630
|
+
* `termMatch` policy other than `any`, which prunes them by term coverage. A
|
|
2631
|
+
* vector or hybrid count still runs its search.
|
|
2632
|
+
*
|
|
2633
|
+
* @param indexName - The index the query would run against.
|
|
2634
|
+
* @param params - The same parameters {@link Narsil.query} takes. Anything
|
|
2635
|
+
* that shapes the output alone, such as `limit` or `highlight`, is ignored.
|
|
2636
|
+
* @returns The match count and the time the count took.
|
|
2637
|
+
*/
|
|
2638
|
+
preflight(indexName: string, params: QueryParams): Promise<PreflightResult>;
|
|
2639
|
+
/**
|
|
2640
|
+
* Returns the indexed terms that complete a prefix, ready to offer as
|
|
2641
|
+
* you-type suggestions.
|
|
2642
|
+
*
|
|
2643
|
+
* The terms come back as the index holds them, which means stems unless the
|
|
2644
|
+
* index was created with `surfaceForms`.
|
|
2645
|
+
*
|
|
2646
|
+
* @param indexName - The index to draw completions from.
|
|
2647
|
+
* @param params - The prefix typed so far, and how many completions to
|
|
2648
|
+
* return.
|
|
2649
|
+
* @returns The completions, most widely used first.
|
|
2650
|
+
*/
|
|
2651
|
+
suggest(indexName: string, params: SuggestParams): Promise<SuggestResult>;
|
|
2652
|
+
/**
|
|
2653
|
+
* Rebuilds an index's terms from the documents it already stores, and
|
|
2654
|
+
* resolves once every partition carries terms the current language module
|
|
2655
|
+
* produced.
|
|
2656
|
+
*
|
|
2657
|
+
* An index whose stored analysis revision differs from the one its language
|
|
2658
|
+
* module carries answers text queries from terms an earlier analysis wrote,
|
|
2659
|
+
* and every such result reports `analysisStale`. Call this after the engine
|
|
2660
|
+
* reports a stale index to configuration that declined an automatic rebuild.
|
|
2661
|
+
* Calling it for an index whose terms are current does nothing.
|
|
2662
|
+
*
|
|
2663
|
+
* @param indexName - The index whose terms are rebuilt.
|
|
2664
|
+
*/
|
|
2665
|
+
rebuildAnalysis(indexName: string): Promise<void>;
|
|
2666
|
+
/**
|
|
2667
|
+
* Returns a stream of the index's snapshot archive. The archive is a pax
|
|
2668
|
+
* file containing the index's configuration and the files of one
|
|
2669
|
+
* checkpoint, and any implementation of the Narsil format can restore it.
|
|
2670
|
+
*
|
|
2671
|
+
* With write-ahead log durability, the engine takes a checkpoint before it
|
|
2672
|
+
* starts the stream, so the archive contains every write that the engine
|
|
2673
|
+
* acknowledged before the call. The engine keeps that checkpoint's files on
|
|
2674
|
+
* disk until the stream ends or you cancel it. Without write-ahead log
|
|
2675
|
+
* durability, the engine builds the archive's files from the index in
|
|
2676
|
+
* memory.
|
|
2677
|
+
*
|
|
2678
|
+
* @param indexName - The index to stream.
|
|
2679
|
+
* @param options - Set `queryHistory` to add the index's popular query
|
|
2680
|
+
* history, which holds raw searches, after the checkpoint's files.
|
|
2681
|
+
* @returns A stream of the archive's bytes, which you can write to a file or
|
|
2682
|
+
* send over a network.
|
|
2683
|
+
*/
|
|
2684
|
+
snapshot(indexName: string, options?: SnapshotOptions): Promise<ReadableStream<Uint8Array>>;
|
|
2685
|
+
/**
|
|
2686
|
+
* Creates an index from a snapshot under the name that you pass, replacing
|
|
2687
|
+
* any index of that name.
|
|
2688
|
+
*
|
|
2689
|
+
* The engine accepts the archive that {@link Narsil.snapshot} streams and
|
|
2690
|
+
* the `.nrsl` file of release 0.3. It checks each archive file against its
|
|
2691
|
+
* manifest and loads the restored index beside the existing one, which
|
|
2692
|
+
* answers requests until the swap. A failed restore leaves the existing index
|
|
2693
|
+
* serving, and after a crash the engine reopens either the old or the new one.
|
|
2694
|
+
*
|
|
2695
|
+
* @param indexName - The name that the restored index takes.
|
|
2696
|
+
* @param data - The snapshot's bytes, as an array, a stream, or async chunks.
|
|
2697
|
+
* @throws A `NarsilError` with `PERSISTENCE_LOAD_FAILED` when the archive is
|
|
2698
|
+
* malformed or a file's length differs from the manifest. The engine raises
|
|
2699
|
+
* `PERSISTENCE_CRC_MISMATCH` when a file's checksum differs from its
|
|
2700
|
+
* contents, and `ENVELOPE_VERSION_MISMATCH` when a file has a format version
|
|
2701
|
+
* other than the ones that this release implements. It raises
|
|
2702
|
+
* `CONFIG_INVALID` when the archive's configuration is invalid,
|
|
2703
|
+
* `DOC_VALIDATION_FAILED` when the data is empty or the release 0.3 file is
|
|
2704
|
+
* invalid, `RESTORE_MEMORY_EXCEEDED` when the restored index needs more
|
|
2705
|
+
* memory than the process has free, and `WORKER_TIMEOUT` when a
|
|
2706
|
+
* worker still holds the old index 30 seconds after the engine asks for it.
|
|
2707
|
+
*/
|
|
2708
|
+
restore(indexName: string, data: ByteSource): Promise<void>;
|
|
2709
|
+
/**
|
|
2710
|
+
* Returns a stream of the index's document export. The export is JSON Lines
|
|
2711
|
+
* text whose format stays the same in every release, so you can use it to
|
|
2712
|
+
* move an index across releases or between implementations.
|
|
2713
|
+
*
|
|
2714
|
+
* The first line is a header containing the format name, the format
|
|
2715
|
+
* version, and the index configuration. Each later line contains one
|
|
2716
|
+
* document, with its ID under `id` and the value of each vector field as an
|
|
2717
|
+
* array of numbers. With write-ahead log durability, the engine exports every
|
|
2718
|
+
* document from one checkpoint; otherwise, it exports them from the index in
|
|
2719
|
+
* memory at one moment.
|
|
2720
|
+
*
|
|
2721
|
+
* JSON has no type for a date, for raw bytes, or for an infinite number or
|
|
2722
|
+
* `NaN`, so the engine writes each such value as a tag. Each tag is an
|
|
2723
|
+
* object with one key that begins with `$`, such as
|
|
2724
|
+
* `{"$date":[1700000000,123000000]}`. The engine also wraps a stored object
|
|
2725
|
+
* whose only key begins with `$` in an `$object` tag, because the import
|
|
2726
|
+
* decodes every other object of that shape as a tag.
|
|
2727
|
+
*
|
|
2728
|
+
* @param indexName - The index to export.
|
|
2729
|
+
* @returns A stream of the export's UTF-8 bytes.
|
|
2730
|
+
*/
|
|
2731
|
+
exportDocuments(indexName: string): Promise<ReadableStream<Uint8Array>>;
|
|
2732
|
+
/**
|
|
2733
|
+
* Imports a document export into the named index. Where the name is free,
|
|
2734
|
+
* the engine creates the index from the export's configuration.
|
|
2735
|
+
*
|
|
2736
|
+
* The engine writes the documents in batches and replaces any document
|
|
2737
|
+
* whose ID the index already contains. Because it replaces existing
|
|
2738
|
+
* documents, you can run an interrupted import again to make the index equal
|
|
2739
|
+
* to the export. When a line is invalid or the engine rejects its document,
|
|
2740
|
+
* the engine records the refusal and continues with the next line.
|
|
2741
|
+
*
|
|
2742
|
+
* The engine converts each tag that {@link Narsil.exportDocuments} writes
|
|
2743
|
+
* into the value that the tag stands for. When an object has one key that
|
|
2744
|
+
* begins with `$` and that key names no tag, or when a tag holds an invalid
|
|
2745
|
+
* value, the engine refuses the line.
|
|
2746
|
+
*
|
|
2747
|
+
* @param indexName - The index that receives the documents.
|
|
2748
|
+
* @param data - The export's bytes, as one array, a stream, or an async
|
|
2749
|
+
* iterable of chunks.
|
|
2750
|
+
* @returns The number of imported documents, the number of refused lines,
|
|
2751
|
+
* and the 1,000 refusals with the lowest line numbers.
|
|
2752
|
+
* @throws A `NarsilError` with `CONFIG_INVALID` when the first line is
|
|
2753
|
+
* anything other than a version 1 header, or when the named index exists
|
|
2754
|
+
* with a different schema.
|
|
2755
|
+
*/
|
|
2756
|
+
importDocumentExport(indexName: string, data: ByteSource): Promise<DocumentImportResult>;
|
|
2757
|
+
/**
|
|
2758
|
+
* Writes an index's current state to the durability directory, so a restart
|
|
2759
|
+
* replays less of the log.
|
|
2760
|
+
*
|
|
2761
|
+
* @param indexName - The index to checkpoint.
|
|
2762
|
+
*/
|
|
2763
|
+
checkpoint(indexName: string): Promise<void>;
|
|
2764
|
+
/**
|
|
2765
|
+
* Removes every document from an index and keeps the index itself, along
|
|
2766
|
+
* with its schema and settings.
|
|
2767
|
+
*
|
|
2768
|
+
* @param indexName - The index to empty.
|
|
2769
|
+
*/
|
|
2770
|
+
clear(indexName: string): Promise<void>;
|
|
2771
|
+
/**
|
|
2772
|
+
* Spreads an index's documents across a different number of partitions.
|
|
2773
|
+
*
|
|
2774
|
+
* The engine keeps answering queries throughout, and it queues the writes
|
|
2775
|
+
* that arrive while the work runs, replaying them in order once it finishes.
|
|
2776
|
+
*
|
|
2777
|
+
* @param indexName - The index to rebalance.
|
|
2778
|
+
* @param targetPartitionCount - Partitions the index ends up with, at most
|
|
2779
|
+
* the index's `maxPartitions`, which defaults to 1. Raise that limit first
|
|
2780
|
+
* with {@link Narsil.updatePartitionConfig}.
|
|
2781
|
+
* @throws A `NarsilError` with `PARTITION_CAPACITY_EXCEEDED` when
|
|
2782
|
+
* `targetPartitionCount` is above `maxPartitions`.
|
|
2783
|
+
*/
|
|
2784
|
+
rebalance(indexName: string, targetPartitionCount: number): Promise<void>;
|
|
2785
|
+
/**
|
|
2786
|
+
* Changes how an index grows into new partitions, without moving the
|
|
2787
|
+
* documents it already holds.
|
|
2788
|
+
*
|
|
2789
|
+
* @param indexName - The index to reconfigure.
|
|
2790
|
+
* @param config - The partitioning fields to change. Anything you leave out
|
|
2791
|
+
* keeps its current value.
|
|
2792
|
+
*/
|
|
2793
|
+
updatePartitionConfig(indexName: string, config: Partial<PartitionConfig>): Promise<void>;
|
|
2794
|
+
/**
|
|
2795
|
+
* Reports what this engine and its host process are using, which is what you
|
|
2796
|
+
* size a host from.
|
|
2797
|
+
*
|
|
2798
|
+
* @returns Process heap figures, the engine's own estimate, and one entry
|
|
2799
|
+
* per worker once the engine has promoted.
|
|
2800
|
+
*/
|
|
2801
|
+
getMemoryStats(): Promise<MemoryStats>;
|
|
2802
|
+
/**
|
|
2803
|
+
* Starts delivering one kind of engine event to your listener.
|
|
2804
|
+
*
|
|
2805
|
+
* These events report work the engine does on its own, away from the call
|
|
2806
|
+
* that triggered it, so this is where a failed background save or a worker
|
|
2807
|
+
* crash reaches you.
|
|
2808
|
+
*
|
|
2809
|
+
* @typeParam K - The event name, which fixes the payload the listener gets.
|
|
2810
|
+
* @param event - Which event to listen for.
|
|
2811
|
+
* @param handler - Called once per event.
|
|
2812
|
+
*/
|
|
2813
|
+
on<K extends keyof NarsilEventMap>(event: K, handler: (payload: NarsilEventMap[K]) => void): void;
|
|
2814
|
+
/**
|
|
2815
|
+
* Removes a listener {@link Narsil.on} registered, so it receives no
|
|
2816
|
+
* further events.
|
|
2817
|
+
*
|
|
2818
|
+
* @typeParam K - The event name.
|
|
2819
|
+
* @param event - The event the listener was registered for.
|
|
2820
|
+
* @param handler - The same function reference that was registered.
|
|
2821
|
+
*/
|
|
2822
|
+
off<K extends keyof NarsilEventMap>(event: K, handler: (payload: NarsilEventMap[K]) => void): void;
|
|
2823
|
+
/**
|
|
2824
|
+
* Closes the engine: it flushes pending writes, ends its workers, and
|
|
2825
|
+
* releases every adapter it opened.
|
|
2826
|
+
*
|
|
2827
|
+
* Call it before the process exits, because writes still in flight are lost
|
|
2828
|
+
* otherwise. The engine rejects new work once this starts.
|
|
2829
|
+
*/
|
|
2830
|
+
shutdown(): Promise<void>;
|
|
1700
2831
|
}
|
|
1701
2832
|
|
|
1702
|
-
export { type
|
|
2833
|
+
export { type FacetResult as $, type SuggestResult as A, type BatchResult as B, type Change as C, type AnalysisChange as D, type ErrorCode as E, type FollowChangesOptions as F, type GroupResult as G, type Hit as H, type IndexInfo as I, type NarsilEventMap as J, type AdapterRegistrationOperations as K, type ListParams as L, type MemoryStats as M, NarsilError as N, type AnalysisOperations as O, type PartitionStatsResult as P, type QueryParams as Q, type ArrayFilter as R, type ServerErrorCode as S, type BM25Operations as T, type ByteSource as U, type VectorMaintenanceResult as V, type ComparisonFilter as W, type DocumentImportResult as X, type DocumentProjection as Y, type DocumentWriteOperations as Z, type FacetConfig as _, type ChangePosition as a, type FieldFilter as a0, type FilterExpression as a1, type GeoFilter as a2, type GeoPolygonFilter as a3, type GeoRadiusFilter as a4, type GroupReducer as a5, type HeldCheckpointReport as a6, type HighlightConfig as a7, type HighlightMatch as a8, type HybridConfig as a9, type IndexLifecycleOperations as aa, type ListedDocument as ab, type PresenceFilter as ac, type ProcessMemoryReport as ad, type QueryCoverage as ae, type RerankConfig as af, type ScoreComponents as ag, type SearchMode as ah, type SortField as ai, type SortSpec as aj, type StringFilter as ak, type SyncOperations as al, type SynonymOperations as am, type TermMatchPolicy as an, type VectorMaintenanceOperations as ao, type VectorQueryConfig as ap, type WorkerCopyReport as aq, type ChangeType as b, type ChangesBatch as c, type ChangesEvent as d, type ChangesOperations as e, type ChangesResync as f, type ChangesSetting as g, type ChangesStatus as h, type ChangesSubscribed as i, type ClientErrorCode as j, ClientErrorCodes as k, ErrorCodes as l, type NarsilErrorCode as m, ServerErrorCodes as n, type SnapshotOptions as o, type SyncSetting as p, type SyncStatus as q, isNarsilError as r, type Narsil as s, type QueryResult as t, type NarsilEventHandlers as u, type GroupConfig as v, type SuggestParams as w, type IndexStats as x, type ListResult as y, type PreflightResult as z };
|