Narsil documentation
Narsil is an open source search engine with full-text, vector, hybrid, and geosearch on one typed index. It embeds in your app or serves a REST API behind its own server, and recorded benchmark runs score it against the engines on either side of it.
Getting started
1 guide
Core concepts
6 guides
Indexes and documents13 min readDeclare a typed schema, store documents under their ids, read them back, page through an index in id order, and change or remove a document.Full-text search17 min readRank documents with BM25, choose which fields the engine searches, match through typos, require every word, mark the matches, and complete the word that a reader is typing.Filters and facets17 min readNarrow a search to the documents whose fields pass your tests, combine those tests with and, or, and not, and count each field's values for a filter sidebar.Sorting, grouping, and pagination19 min readOrder hits by field values, collapse them into groups with a reducer, page through them by offset or by cursor, browse an index in any order, and pin a result in place.Language support12 min readLoad a language module, index text in French and Chinese, name your own tokeniser and stop words, write a language of your own, and rebuild an index when a language changes.Errors11 min readRead the code on a Narsil failure, branch on it from any entry point, and make a strict index reject a query that names a misspelt field.
Search modes
4 guides
Vector search15 min readEmbed text with a local model, store the vectors in a typed field, and search by meaning, with a similarity floor, an HNSW graph, and compaction after a removal.Hybrid search10 min readSearch one index for keywords and for meaning at once, read the two rankings behind the fused order, and weight one side with the linear blend.Geosearch8 min readStore coordinates in a geopoint field, keep the documents inside a radius or a polygon, flip either test, and filter across the antimeridian without a search term.Embedding adapters12 min readLet the engine embed your text on every write and every search, keep a batch going when one document has no text, name the adapter an index uses, and wrap it in your own.
Operations
6 guides
Configuration8 min readSet up one engine for production, check every write and search with a plugin, and look up each option that createNarsil and createIndex take, with its default.Persistence and durability9 min readKeep every acknowledged write across a restart, choose how many writes you can lose in a crash, see the files that a checkpoint writes, close idle indexes, and move an index as one snapshot.Partitions and workers7 min readSplit an index across partitions, get a warning before it fills, reshape it while it serves queries, and move its searches onto worker threads that stay current.Observability8 min readRead what each index holds, report the memory that the engine uses, alert on the events that the engine emits on its own, and probe a server from a load balancer.Native search core5 min readInstall the C core that searches vector fields, confirm that the engine loaded it, see how much faster it builds and searches, and keep a bundler from leaving it out in production.HTTP server6 min readServe an engine over HTTP, admit only the callers that hold a token, set limits for a public address, and stop the server so that the process exits cleanly.
Clients
2 guides
Client SDK8 min readReach a Narsil server from Node, a browser, or an edge function with the same calls as the embedded engine, and handle the tasks, deadlines, and failures of a network call.React hooks6 min readGive a React tree one Narsil client, search as somebody types, offer completions under the box, and read documents, stats, and tasks through hooks that share their requests.
AI agents
9 guides
Overview4 min readRead what one Narsil search returns to an AI agent, and find the guide for each failure that a person would notice.Cite the passage behind an answer16 min readGive every answer from an AI agent the rule's reference and its exact sentence, and check the quote against the stored text before a passenger reads it.Give a model a search tool15 min readGive a model a search tool that takes a resident's own words, since a lookup by key needs an identifier that the model has no way of knowing.Keep each agent to its own index12 min readGive each client's AI agent an index of its own, because the engine ranks passages by relevance and can put another client's handbook first.Fit the passages in a context budget16 min readMeasure the characters that a search tool returns, set each passage's cap from the text that it has to include, and keep the total within a budget.When the index has no good match13 min readRequire every query term and return a retrieval status that the AI agent states first, since a near miss looks like an answer and an empty result leads to a guess.Keep the index current12 min readWrite every change in your records to the index as an update or a removal, and wait for the worker copies, since the index keeps the last version that you wrote.Record every search13 min readRecord every query and every preflight with one plugin on the engine, so that your journal includes the searches from every tool.Search by wording and by meaning11 min readAdd the customer's own words to the catalogue and fuse the keyword and vector rankings, since neither ranking alone puts the right product first for this customer.