Search
Three search modes are available: full-text, vector (embedding-based), and hybrid (blended).
Full-Text Search
POST /api/teams/{teamName}/datasets/{dataSetName}/search
curl -X POST https://your-host/api/teams/acme/datasets/products/search \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"text": "wireless headphones", "maxNumberOfRecordsToReturn": 20}'Without reranking
The reranker (called Coverage before 6.0) reranks by default ("ranking": { "rerank": true }, in either mode). Pattern
recognition alone is "mode": "Bm25f" with "rerank": false; the counted records ordered by
pattern recognition are "mode": "EditDistance" (the default) with "rerank": false. Enums are
written by name (a number is still accepted):
{
"text": "wireless headphones",
"maxNumberOfRecordsToReturn": 30,
"mode": "Bm25f",
"ranking": { "rerank": false }
}With Facets and Filter
{
"text": "headphones",
"maxNumberOfRecordsToReturn": 20,
"enableFacets": true,
"filter": {"hashString": "abc123..."}
}With Per-Field Boosts
ranking.fieldBoosts adjusts how much each field counts for one search, without reconfiguring or rebuilding the index. Keys are field names, values are multipliers.
{
"text": "noise cancelling",
"maxNumberOfRecordsToReturn": 10,
"ranking": {
"fieldBoosts": {
"title": 3.0,
"description": 0.5
}
}
}- A boost multiplies the field's configured
weight; it does not replace it. A field withweight: 2.0and a boost of3.0counts 6×. Fields you leave out keep their configured weight (a boost of 1.0). - Every key must be a searchable field. Here
titleanddescriptionmust both havewordMatchingorpatternMatchingon in the dataset's field configuration. - A key that is not a searchable field empties the whole search. The response is
200with no records and areasonnaming the field ("FieldBoosts contains unknown or non-searchable field: 'x'"), so readreasonbefore showing "no results". If a search that used to return results suddenly returns none, checkranking.fieldBoostsagainst the field configuration first — making a field non-searchable does not remove it from boosts your code still sends. - Field boosts always apply. Every dataset on the server scores in BM25F mode with one k1 for all fields, so a changed
bM25k1inPUT fields/configurationis refused.
Paging and Named Facets
{
"text": "headphones",
"maxNumberOfRecordsToReturn": 20,
"offset": 40,
"enableFacets": true,
"facetFields": ["brand", "price"],
"facetValueLimit": 10
}The third page of 20, the counts of brand and price only, and the ten commonest values of each.
facetStats.price gives the lowest and highest price over the whole search. Page while offset is
below ranked: the search ranks at most its candidate bound, so with count above ranked the
records past ranked are counted, and in the facets, but cannot be returned.
With the Records' JSON
Add "includeDocuments": true to any search: the response gains documents, the records' JSON in
the order of records, so the page needs no second call to documents/lookup. Add
"includeFields": ["card", "id"] to get only those top-level fields of each record: what the page
shows, without the long texts and the fields that are only there to filter on.
Which Records Have Cold Storage
When a listed record holds cold storage the key may read, the response
carries cold: the names each such record holds, by its key, such as { "1": ["review", "toc"] }.
It is left out when none does.
Several Searches in One Call
POST /api/teams/{teamName}/datasets/{dataSetName}/search/multi takes a JSON array of up to 20
search bodies and answers an array in the same order. Each search runs as POST …/search runs it;
each answer is that search's result, with its queryId in the body where a single search sends the
Indx-Query-Id header. A search that fails is { "status": 400, "error": { … } } in its place, the
problem a single search would have answered, and the others are answered. An InstantSearch page uses
it for its list and the counts of each ticked OR facet without that facet's own filter.
Each search may say for itself whether it counts in the statistics: count, source and session
in its body take the place of ?count=, ?source= and ?session= for that search. So the
visitor's search goes beside the page's helper searches, and only it is counted. The response's
Server-Timing header gives the searches' time together, with how many there were.
[
{ "text": "headphones", "maxNumberOfRecordsToReturn": 20, "enableFacets": true, "includeDocuments": true },
{ "text": "headphones", "maxNumberOfRecordsToReturn": 1, "enableFacets": true, "facetFields": ["brand"] }
]Sections in One Search
POST /api/teams/{teamName}/datasets/{dataSetName}/search/groups searches one text and answers it in
named sections, each with its own filter, rows and count: a search box that shows books, authors and
upcoming events under one another, in one call.
{
"text": "hamsun",
"includeDocuments": true,
"includeFields": ["card"],
"groups": [
{ "name": "books", "filter": "contentType = \"product\" AND isMainProduct = true", "rows": 8,
"candidates": { "fallback": true }, "primary": true },
{ "name": "authors", "filter": "contentType = \"contributor\"", "rows": 3, "candidates": { "fallback": false } },
{ "name": "events", "filter": "contentType = \"event\" AND eventEndDate >= 1794492000000", "rows": 3,
"countFilter": "contentType = \"event\"", "candidates": { "fallback": false } }
]
}The answer is { "groups": { "books": { … }, "authors": { … }, "events": { … } }, "queryId": "…" },
each section a result as POST …/search gives it.
- Everything outside
groupsis every section's: the text, the settings,includeDocuments. A section'sfilteris ANDed with the search's ownfilterExpression. rowsis how many records the section lists;0lists none and still counts.countFiltercounts by another filter than the section lists by: list the upcoming events, count them all. Only the section'scountfollows it:isFallbackand the records are the list's. When no upcoming event matches but past ones do, the section saysisFallbackwith acountof the past ones, and that count is a real one.candidates,rankingandmatchin a section replace the search's for that section, each whole: the fallback on for books and off for the rest, a boost for books only.- The statistics hold one search: the section marked
primary, else the first. ItsqueryId, in the body and theIndx-Query-Idheader, is the one a click in any section refers to. - A section that fails is
{ "status": 400, "error": { … } }in its place, and the others are answered. At most 20 sections.
Each section is ranked within its own filter, so a section with few or weak matches still gets its rows: one mixed list cut into sections would give its places to the strongest.
Search a Facet's Values
A facet with many values (thousands of actors, authors or brands) shows only the commonest. To let a
visitor find the rest, give the facet a search field of its own and send what they type to
POST /api/teams/{teamName}/datasets/{dataSetName}/facets/{field}/search:
{ "text": "tom hnks", "rows": 10, "search": { "text": "war" } }{ "values": [ { "value": "Tom Hanks", "count": 23 } ], "fallback": false, "exhaustive": true }- The values are matched as a search is: typos, the start of a word while typing (from its second letter, so "le" finds Leonardo DiCaprio), and any word of the value, so "hanks" finds Tom Hanks and "scarlet johanson" Scarlett Johansson.
countis how many records hold the value, the most first. Withsearch, they are the records that search finds, as its facet counts them, and a value it holds none of is left out. A field ticked in itsfacetSelectionsis counted without its own ticks, so the other values keep their counts. Withoutsearch, every record counts.- A page that already shows the facet's values and counts for the visitor's search can send those
values instead of
search:"values": ["Tom Hanks", "Kate Winslet", …], at most 3,000. The match is then among them, the server need not count the search again, and the page shows its own counts. This is what intrface'sValueFilterPaneldoes on every keystroke. - When no value holds every word, the closest come first and
fallbackis true: the values holding the most of the words, then those the pattern index finds. So the list does not empty while a name is still being typed ("donna rea"), and "leodicaprio" finds Leonardo DiCaprio. - The counts are exact (
exhaustiveis always true). An emptytextgives the commonest values. rowsis 1 to 100, 10 by default. The field must be facetable. Nothing goes into the statistics.- The first search of a field indexes its values, a fraction of a second for tens of thousands; the index is kept while the facet is in use, and a value an insert or update brings is found at once.
It answers what an InstantSearch refinementList with searchable: true asks of
searchForFacetValues: facetQuery is text, maxFacetHits is rows, and the current search's
parameters are search. The values come without highlighted marks for now.
Browse / Empty Search
{
"text": "",
"maxNumberOfRecordsToReturn": 50,
"sortBy": "rating",
"sortAscending": false,
"enableFacets": true
}Vector Search
POST /api/teams/{teamName}/datasets/{dataSetName}/search/vector
Approximate nearest-neighbour search against a field marked Embeddable. The query vector must match the field's embedding dimensions. Any length is accepted: Indx brings it to unit length, so scores are cosine similarity.
curl -X POST https://your-host/api/teams/acme/datasets/products/search/vector \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"fieldName": "embedding",
"vector": [0.12, -0.45, 0.33, ...],
"maxResults": 10
}'| Property | Type | Default | Description |
|---|---|---|---|
fieldName | string | required | Name of the Embeddable field to search |
vector | float[] | required | Query vector, with the field's dimensions |
maxResults | int | 10 | Maximum number of results |
filter | FilterProxy? | null | Optional filter to restrict the search space |
Returns an array of EmbeddingResultEntry with scores in [0, 1] (cosine similarity).
Hybrid Search
POST /api/teams/{teamName}/datasets/{dataSetName}/search/hybrid
Blends text search and vector search scores. The combined score is:
score = alpha × embeddingScore + (1 − alpha) × normalisedTextScorecurl -X POST https://your-host/api/teams/acme/datasets/products/search/hybrid \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"text": "comfortable headphones",
"embeddingField": "embedding",
"vector": [0.12, -0.45, 0.33, ...],
"alpha": 0.6,
"maxNumberOfRecordsToReturn": 20
}'| Property | Type | Default | Description |
|---|---|---|---|
text | string | "" | Text query |
embeddingField | string | required | Name of the Embeddable field |
vector | float[] | required | Query vector, with the field's dimensions |
alpha | float | 0.5 | Blend weight. 0 = pure text, 1 = pure embedding. Values around 0.5–0.7 work well |
maxNumberOfRecordsToReturn | int | 10 | Maximum results |
filter | FilterProxy? | null | Optional filter |
timeOutLimitMilliseconds | int | 1000 | Text search timeout |
Returns an array of EmbeddingResultEntry with blended scores in [0, 1].
Retrieving Full Documents
Search endpoints return keys and scores only. Use documents/lookup to fetch the full JSON for a set of keys.
POST /api/teams/{teamName}/datasets/{dataSetName}/documents/lookup
curl -X POST https://your-host/api/teams/acme/datasets/products/documents/lookup \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '[42, 17, 305]'Returns a string[] of JSON documents in the same order as the input keys.
Search
Search will validate the search query and return the search result. With `includeDocuments` the records' JSON comes with it, in `documents`, in the order of `records` (null for a record gone since), so a search is one call, not two; `includeFields` keeps only the fields named.
| Name | In | Type | Required |
|---|---|---|---|
teamName | path | string | Yes |
dataSetName | path | string | Yes |
api-version | header | string | No |
api-version | query | string | No |
| Content Type | Schema |
|---|---|
application/json | object |
Several searches of the dataset in one call, answered in the order sent: what an InstantSearch page asks for at once, its list and the counts of each refined OR facet without that facet's own filter (11 Nov 2026, backlog 90 step 4). Each runs as M:IndxServer.Controllers.SearchController.Search(System.String,System.String,IndxServer.Models.ServerQueryProxy) runs it, the statistics and the query string's parameters included; a search that fails is an `error` in its place, with the status and problem a single search would have answered, and the others are answered. Each answer carries its `queryId` where a single search's header would. At most IndxServer.Controllers.SearchController.MaxSearchesPerCall searches. A search may say for itself whether it counts in the statistics, and its source and session (`count`, `source`, `session` in its body), over the query string's: a page sends its visitor's search beside its helper searches and counts only the first (12 Nov 2026). `Server-Timing` gives the searches' time together. The engine searches them in one call, at once on the search slots it has free and one after the other when none is (ISearchEngine.Search(Query[]), 12 Nov 2026); `Server-Timing`'s search is the time until the last is answered.
| Name | In | Type | Required |
|---|---|---|---|
teamName | path | string | Yes |
dataSetName | path | string | Yes |
api-version | header | string | No |
api-version | query | string | No |
| Content Type | Schema |
|---|---|
application/json | object[] |
One text, answered in named sections: a search box's products, brands, articles and pages in one call, each section with its own filter (ANDed with the search's), rows and count (12 Nov 2026: one search per keystroke instead of several). A section may count by another filter than it lists (`countFilter`: list the ones in stock, count them all), and take its own candidates, ranking and match. The answer is `{ "groups": { name: result }, "queryId" }`, each result as a single search's, a section that fails an error in its place. One search in the statistics: the section marked `primary`, else the first, whose `queryId` (also the `Indx-Query-Id` header) a click in any section references. Each section is its own search in the engine, all of them searched in one call, at once on the free search slots (ISearchEngine.Search(Query[]), 12 Nov 2026); were the library to match once for them all, the request and answer would stay as they are.
| Name | In | Type | Required |
|---|---|---|---|
teamName | path | string | Yes |
dataSetName | path | string | Yes |
api-version | header | string | No |
api-version | query | string | No |
| Content Type | Schema |
|---|---|
application/json | object |
Searches the values of a facetable field, for a long facet's own search field ("Search actors…", InstantSearch's searchable refinement list): the values that match what was typed, with Indx's matching (typos, word starts, whole words anywhere in a value), each with how many records hold it, the most first (FacetValueIndex, 14 Nov 2026). With `search` the counts are of that search's records, as its facet would count them, and a value it holds none of is left out; a field ticked in its `facetSelections` is counted without its own ticks, as InstantSearch asks. Answers `{ values: [{ value, count }], exhaustive }`; the counts are exact. Nothing goes into the statistics.
| Name | In | Type | Required |
|---|---|---|---|
teamName | path | string | Yes |
dataSetName | path | string | Yes |
field | path | string | Yes |
api-version | header | string | No |
api-version | query | string | No |
| Content Type | Schema |
|---|---|
application/json | object |
Searches a single embedding field using approximate nearest-neighbour search.
| Name | In | Type | Required |
|---|---|---|---|
teamName | path | string | Yes |
dataSetName | path | string | Yes |
api-version | header | string | No |
api-version | query | string | No |
| Content Type | Schema |
|---|---|
application/json | object |
Combines text search with embedding nearest-neighbour search and blends scores.
| Name | In | Type | Required |
|---|---|---|---|
teamName | path | string | Yes |
dataSetName | path | string | Yes |
api-version | header | string | No |
api-version | query | string | No |
| Content Type | Schema |
|---|---|
application/json | object |