Search

Three search modes are available: full-text, vector (embedding-based), and hybrid (blended).


POST /api/teams/{teamName}/datasets/{dataSetName}/search

bash
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):

json
{
  "text": "wireless headphones",
  "maxNumberOfRecordsToReturn": 30,
  "mode": "Bm25f",
  "ranking": { "rerank": false }
}

With Facets and Filter

json
{
  "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.

json
{
  "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 with weight: 2.0 and a boost of 3.0 counts 6×. Fields you leave out keep their configured weight (a boost of 1.0).
  • Every key must be a searchable field. Here title and description must both have wordMatching or patternMatching on in the dataset's field configuration.
  • A key that is not a searchable field empties the whole search. The response is 200 with no records and a reason naming the field ("FieldBoosts contains unknown or non-searchable field: 'x'"), so read reason before showing "no results". If a search that used to return results suddenly returns none, check ranking.fieldBoosts against 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 bM25k1 in PUT fields/configuration is refused.

Paging and Named Facets

json
{
  "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.

json
[
  { "text": "headphones", "maxNumberOfRecordsToReturn": 20, "enableFacets": true, "includeDocuments": true },
  { "text": "headphones", "maxNumberOfRecordsToReturn": 1, "enableFacets": true, "facetFields": ["brand"] }
]

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.

json
{
  "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 groups is every section's: the text, the settings, includeDocuments. A section's filter is ANDed with the search's own filterExpression.
  • rows is how many records the section lists; 0 lists none and still counts.
  • countFilter counts by another filter than the section lists by: list the upcoming events, count them all. Only the section's count follows it: isFallback and the records are the list's. When no upcoming event matches but past ones do, the section says isFallback with a count of the past ones, and that count is a real one.
  • candidates, ranking and match in 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. Its queryId, in the body and the Indx-Query-Id header, 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:

json
{ "text": "tom hnks", "rows": 10, "search": { "text": "war" } }
json
{ "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.
  • count is how many records hold the value, the most first. With search, 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 its facetSelections is counted without its own ticks, so the other values keep their counts. Without search, 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's ValueFilterPanel does on every keystroke.
  • When no value holds every word, the closest come first and fallback is 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 (exhaustive is always true). An empty text gives the commonest values.
  • rows is 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.

json
{
  "text": "",
  "maxNumberOfRecordsToReturn": 50,
  "sortBy": "rating",
  "sortAscending": false,
  "enableFacets": true
}

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.

bash
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
  }'
PropertyTypeDefaultDescription
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).


POST /api/teams/{teamName}/datasets/{dataSetName}/search/hybrid

Blends text search and vector search scores. The combined score is:

score = alpha × embeddingScore + (1 − alpha) × normalisedTextScore
bash
curl -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
  }'
PropertyTypeDefaultDescription
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

bash
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.

POST/api/teams/{teamName}/datasets/{dataSetName}/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.

Parameters
NameInTypeRequired
teamName
path
string
Yes
dataSetName
path
string
Yes
api-version
header
string
No
api-version
query
string
No
Request Body
Content TypeSchema
application/json
object
POST/api/teams/{teamName}/datasets/{dataSetName}/search/multi

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.

Parameters
NameInTypeRequired
teamName
path
string
Yes
dataSetName
path
string
Yes
api-version
header
string
No
api-version
query
string
No
Request Body
Content TypeSchema
application/json
object[]
POST/api/teams/{teamName}/datasets/{dataSetName}/search/groups

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.

Parameters
NameInTypeRequired
teamName
path
string
Yes
dataSetName
path
string
Yes
api-version
header
string
No
api-version
query
string
No
Request Body
Content TypeSchema
application/json
object
POST/api/teams/{teamName}/datasets/{dataSetName}/facets/{field}/search

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.

Parameters
NameInTypeRequired
teamName
path
string
Yes
dataSetName
path
string
Yes
field
path
string
Yes
api-version
header
string
No
api-version
query
string
No
Request Body
Content TypeSchema
application/json
object
POST/api/teams/{teamName}/datasets/{dataSetName}/search/vector

Searches a single embedding field using approximate nearest-neighbour search.

Parameters
NameInTypeRequired
teamName
path
string
Yes
dataSetName
path
string
Yes
api-version
header
string
No
api-version
query
string
No
Request Body
Content TypeSchema
application/json
object
POST/api/teams/{teamName}/datasets/{dataSetName}/search/hybrid

Combines text search with embedding nearest-neighbour search and blends scores.

Parameters
NameInTypeRequired
teamName
path
string
Yes
dataSetName
path
string
Yes
api-version
header
string
No
api-version
query
string
No
Request Body
Content TypeSchema
application/json
object