Core Concepts
How Search Works
A search makes two choices: how records are fetched and whether they are reranked.
Fetch: each word is looked up, exactly, then within an edit. In the default mode (EditDistance), every query word is looked up in the word lookup: exactly, then within one edit, then within two. Each of those levels is a rung. The first rung on which records hold every query word is the result: those records are counted (count, and per rung toleranceCounts), faceted and listed alike. Nothing is cut from that list, and nothing that misses a word is mixed into it, so "140 hits" means 140.
Rerank: the best of them in order. The reranker (called Coverage before Indx 6) orders the records inside each rung by how well they cover the query: whole words, words typed together or apart, the whole query as a phrase, the fields' weights. It is on by default and fast enough to leave on. Scores run 0 to 65 535.
A search for "Wirless hedphones" finds "Wireless Headphones" on the one-edit rung: each word is one edit away. The count says so too (toleranceCounts.oneEdit), so a page can say "12 hits, all with a typo".
A heavily garbled query like "Wirlss edphons" may leave no record holding every word within the edits allowed. Then you get the fallback, marked isFallback: the records holding the most of the words first, then pattern matches. A search can ask for nothing instead (candidates.fallback: false), which is what an agent wants: an empty result it can trust.
The other mode, Bm25f, ranks every record by BM25F relevance and counts nothing, for long natural-language queries over documents.
Language Handling — Inflections, Compound Words, Synonyms
Indx has no per-language tokenizer, stemmer or stop-word list, and does not need one for Norwegian, English or mixed-language data. What covers what a stemmer usually does:
- Typos and spelling variants — one edit on a word from three letters, two from six, three from nine with
ThreeEdits(Match.Tolerance). - Words being typed — the word at the cursor is matched as the start of a longer word: bok finds bokhandel while it is being typed. A finished word is matched whole. In a field matched by pattern, any part of a word matches too, ranked below whole words.
- Compound words (sammensatte ord) — a compound is linked to its parts when the index is built: ost finds brunost and geitost, hvitløksmør finds records holding hvitløk smør, and two query words find the compound they make. Words typed together or apart match too (
Match.JoinedWords). No dictionary is involved. - Domain vocabulary — synonyms give query words alternatives, editable by editors without code.
On a feature checklist this reads as: no stemmer to configure. An inflection that shares its beginning with the base is met while typing and by pattern; an irregular form that shares little with its base, such as bok and bøker or mouse and mice, is where a synonym entry is the answer. Synonyms are never for typos or for translation.
Field Roles
Fields don't do anything until you explicitly assign them a role: a freshly analyzed dataset searches nothing. You configure this after calling Init (which discovers the field names) and before calling Index.
| Role | What it does |
|---|---|
Word matching | The field is matched by its whole words, exactly and within edits, and counts: a search narrows to the records holding every query word. At least one searched field needs it. |
Pattern matching | The field is also matched inside its words, so a query finds part of a word. Alone it orders records but cannot narrow them. Titles, names and descriptions usually have both; codes and tags word matching alone. |
Filterable | The field can be used to filter results before or during a search. |
Facetable | The field returns value counts in search results — useful for sidebar filters. Values whose count drops to 0 under the current filter are omitted from the response; keep them in the UI greyed out so the user can still deselect them. |
Sortable | Results can be ordered by this field's value. Works on both numbers and strings. |
A field can have multiple roles — a category field can be both filterable and facetable at the same time.
Weight
Searched fields have a weight (default 1.0) that controls how much influence that field has on the final score. If name should matter more than description, give it a higher weight.
engine.GetField("name")!.Weight = 2.0f;
engine.GetField("description")!.Weight = 1.0f;Weight is a relative value — it only matters in proportion to the weights of the other searched fields.
Filters Are Server-Side
A search returns only a limited slice of results (maxNumberOfRecordsToReturn). If you filter that slice yourself after receiving it, you will miss matching documents that weren't in the top results.
Always pass filters to the engine so they are applied during search — the engine evaluates them against the full dataset, not just the returned page.
// Wrong: filter the array you got back
var results = engine.Search(query).Records.Where(e => ...);
// Right: create a filter and give it to the query
var filter = engine.CreateValueFilter("category", "audio", out _);
var query = new Query("wireless", 20) { Filter = filter };
var result = engine.Search(query);The same applies to the HTTP API: create a filter server-side first, then pass its hashString in the search request.
Scoring
Results have a 16-bit score (0–65535). They come in rung order (records with every word exact before those with a typo), reranked inside each rung; a boost or bury moves a record within its rung, never across.
When sorting is applied alongside a text search, the score remains the primary sort — the sort field is only used as a tiebreaker. When searching with no query text (empty search), sorting becomes the primary ordering.
Synonyms
A dataset can carry a synonym list that gives query words alternatives at search time: a word that matches an entry is held through the word as typed or any of the entry's terms, so a synonym widens what the search counts. Multidirectional entries make a group of terms equivalent (sofa, couch); one-way entries let a trigger like an acronym find its expansion without the reverse. Nothing is re-indexed and changes apply on the next search. See Set Up Synonyms.
The Engine Lifecycle
The engine must go through a fixed sequence before it can search:
Init() → configure fields → Load() → Index() → Search()- Init — reads the JSON structure and discovers field names
- Configure — set roles and weights on the fields you care about
- Load — streams the JSON documents into the engine
- Index — builds the inverted index; engine enters the Ready state
- Search — available once the engine is Ready
After indexing you can also insert, update, and delete individual documents without rebuilding the index — see Dynamic Operations.
Empty Search
An empty or null query string is valid, but requires EnableFacets = true — without it, no documents are returned. The result contains up to maxNumberOfRecordsToReturn documents, while facets are calculated across the entire dataset.
Results are ordered by sort field if one is specified, making empty search the natural companion to sorting and faceted navigation.