Answers what to search for, from the text typed into a search box so far. A search box asks for this on every keystroke, and shows the answer as a list to pick from.
The suggestions are the values of the fields the search settings of the index opt in with suggest (see Field settings), that start with the text, each with how many documents hold it under the given filters. An index whose settings suggest no field answers an empty list. Each suggestion says how many characters of it were typed, so a search box can mark the part that completes the text.
Matching rules:
Folding: The text and the values of a field are compared folded in case and Unicode form, by the normalize step of the field's autocomplete analyzer chain, or of the chain the engine builds for autocomplete when the field declares none. rö finds Röd. Words are not stemmed, so shoes does not find Shoe.
Declared labels: The text is also compared with the label the search settings declare for a value in the locale of the request, so rö suggests the value red labelled Röd in Swedish. A declared value no document holds is never suggested.
Whole-value prefix: The comparison is against the start of the whole value, not of each word: air does not find Nike Air Max.
Ordering: The most common values first; ties by field name, then by value.
Typo tolerance: When fewer values than limit start with a text of at least five characters and typos is auto, values one mistake away from the text - a character inserted, dropped, replaced, or two adjacent ones swapped - are suggested after them, marked corrected, with typed at 0. The first character of the text is never read as a mistake.
Counts: The counts are the ones a facet of a search under the same filters answers. A filter on a suggested field is left out of that field's own counts, so a brand already ticked keeps the other brands suggestable.
A filter panel that completes the values of one facet uses POST /v1alpha1/indexes/{name}/facets/{field}/values instead. See Suggesting what to search for.
Path parameters
namestringrequired
Name of the index. To suggest from one generation, add @ and the name of the generation, such as books@2.
Headers
X-Exofind-Freshnessany
A freshness token, for a request that carries none in its body. The body's freshness.atLeast is read when both are given.
Body
SuggestRequestRequired
Asks what to search for, from the text typed so far. The suggestions are the values of the fields the search settings of the index opt in with suggest, that start with the text, the most common first. All properties are optional; an empty request answers the most common values.
textstring
What has been typed so far. Compared with the start of each whole value, folded in case and Unicode form, so rö finds Röd and air does not find Nike Air Max, and with the labels the search settings declare for the values in the locale of the request. If omitted or blank, the most common values are answered with typed at 0.
Example
"adi"
localestring
BCP-47 locale tag used to read locale-specific fields and to pick the labels of declared values, as for a search. If omitted, uses each field's default locale.
Refinement clauses, in the same shape as the filters of a search, such as the category a search box is scoped to. The counts are the ones a facet of a search under the same filters answers. A filter on a suggested field is left out of that field's own counts, so a brand already ticked keeps the other brands suggestable (see Facets). The clauses count against EXOFIND_SEARCH_MAX_CLAUSES and EXOFIND_SEARCH_MAX_CLAUSE_DEPTH, as for a search.
Example
{
"field": "category",
"match": {
"value": "fiction"
}
}
9 types
FieldClausetype: "field"
Matches documents by the value of a single field. The targeted field must be indexed for the requested matcher usage; if it is not configured for that usage, the request returns search:usage_unsupported.
Matches field values equal to any value in values. An empty array matches no documents.
Example
{
"type": "in",
"values": [
"fiction",
"poetry"
]
}
valuesany[]required
The values that a field value may equal.
AnyMatchertype: "any"
Matches any document that contains a value for the field.
Example
{
"type": "any"
}
PrefixMatchertype: "prefix"
Matches string field values starting with value, evaluated against the entire field value.
Example
{
"type": "prefix",
"value": "EX-"
}
valuestringrequired
The prefix that a field value must start with.
Example
"EX-"
UnderMatchertype: "under"
Matches values at or below the specified path in a hierarchical tree. Requires a field configured with hierarchy. Path segments must match complete levels, so Men/Sho matches nothing where a prefix matcher matches.
Example
{
"type": "under",
"path": "Men/Shoes"
}
pathstringrequired
Path in the hierarchical tree to match at or below.
Example
"Men/Shoes"
RangeMatchertype: "range"
Matches values within bounds. Accepts inclusive (gte, lte) and exclusive (gt, lt) bounds; either side may be left open, and at least one bound is required (search:matcher:range_empty).
Example
{
"type": "range",
"gte": 10,
"lt": 20
}
gteany
Lower bound, the value itself included.
Example
10
gtany
Lower bound, the value itself excluded.
lteany
Upper bound, the value itself included.
ltany
Upper bound, exclusive.
Example
20
RangesMatchertype: "ranges"
Matches values falling within any of the specified range objects. An empty array matches no documents, matching the behavior of an empty in matcher.
Example
{
"type": "ranges",
"values": [
{
"gte": 10,
"lt": 20
},
{
"gte": 50
}
]
}
valuesMatcherRange[]required
The ranges to evaluate, each requiring at least one bound. A bucket returned by a range facet sets from as gte and to as lt.
Example
{
"gte": 10,
"lt": 20
}
4 properties
gteany
Lower bound, the value itself included.
Example
10
gtany
Lower bound, the value itself excluded.
lteany
Upper bound, the value itself included.
ltany
Upper bound, exclusive.
Example
20
TextMatchertype: "text"
Matches text within a single field using field-level analysis.
How the parts of user text combine: all requires every word and every quoted phrase, any accepts a document that holds one of them. Excluded terms (-word) always apply. Setting join with any other match returns search:clause:join_unsupported.
Typo tolerance handling. auto follows the field's typoTolerance configuration; off disables typo tolerance for the matcher.
Default
"auto"
Values
"auto", "off"
slopinteger
Number of intervening words permitted between terms in a phrase, without changing their relative order. Only applies to phrase queries or quoted phrases in user mode.
Whether parts of user text are read as filters on the fields of the index: auto reads a number typed next to the unit of a number field, or next to a comparative word such as under, as a filter on that field; off takes every word as text. Whatever was read is reported as interpreted beside the results. See Reading numbers and units.
Default
"auto"
Values
"auto", "off"
DistanceMatchertype: "distance"
Matches geopoint values within radius meters of the specified latitude and longitude coordinates.
Matches query text across one or more fields. Phrase queries operate within a single field and match terms exactly as typed, regardless of field typoTolerance. Fields defined only for autocomplete do not support phrase matching. See text.
Example
{
"type": "text",
"text": "silent spr",
"fields": {
"name": 3,
"description": null
}
}
textstringrequired
The query text to match.
Example
"silent spr"
fieldsmap of number
Object mapping field names to score weights. A field mapped to null uses the weight from its field definition. If omitted, searches all searchable fields, skipping autocomplete-only fields.
How the parts of user text combine: all requires every word and every quoted phrase, any accepts a document that holds one of them. Excluded terms (-word) always apply, and a filter read out of the text is one of the parts. Setting join with any other match returns search:clause:join_unsupported. See Reading what was typed.
Typo tolerance handling. auto follows each field's typoTolerance configuration; off disables typo tolerance for the clause.
Default
"auto"
Values
"auto", "off"
slopinteger
Number of intervening words permitted between terms in a phrase, without changing their relative order. Setting slop above 0 with "match": "all" or "match": "any" returns search:clause:slop_unsupported.
Scope for multi-field term matching. term evaluates each term across all targeted fields, so terms may appear in different fields; field requires a single field to satisfy match on its own. Ignored by phrase queries.
Whether parts of user text are read as filters on the fields of the index, given as a mode or as the targets to read on. See Reading numbers and units.
Whether parts of user text are read as filters: auto reads a number typed next to a unit or a comparative word as a filter on the field declaring that unit, off takes every word as text.
Reads user text as filters on the named targets only. A number typed with a unit is read on every target declaring that unit; a number typed without one is read on every target holding a currency, when they all hold the same currency.
Clauses that must hold where the number is read: in the same value as the field for a field inside a nested list, and for the document otherwise. Takes what a nested clause takes: field, text, and, or, not and boost. A clause naming a field outside the list returns search:nested:field_not_inside.
Targets read instead, in order, where the document holds no value on this one - a product with no price on the customer's list is read on the store's list. Every target of the chain must declare the same unit; one in another unit returns search:interpret:fallback_unit_mismatch.
Matches the k nearest documents by vector distance in a specified field, scored by proximity. Cannot be combined with hits (search:hits:knn_unsupported).
Example
{
"type": "knn",
"field": "embedding",
"vector": [
0.1,
0.2
],
"k": 10,
"filter": [
{
"field": "published",
"match": {
"value": true
}
}
]
}
fieldstringrequired
The vector field to search.
Example
"embedding"
vectornumber[]required
The query vector. Its length must match the dimensions declared in the field definition.
Format
float
kintegerrequired
Number of nearest documents to return, at most EXOFIND_SEARCH_MAX_KNN_K.
Matches documents where a single element of a nestedobject field satisfies all child clauses. A nested clause on a flattened object field returns search:nested:path_not_nested; on a non-object field it returns an error. See nested.
Clauses evaluated within a single nested object value, naming fields by their dotted path. An empty array matches any document where the object field is present. May contain field, text, knn, and, or, not and boost; a clause that only means something for whole documents, such as another nested or a fuse, returns search:nested:clause_unsupported.
Example
{
"field": "category",
"match": {
"value": "fiction"
}
}
scoreScore
Scoring mode for aggregating matching nested values. Only applies when scoring clauses exist within the nested clause.
Increases the relevance score of documents that satisfy child clauses without excluding non-matching documents.
Example
{
"type": "boost",
"weight": 2,
"clauses": [
{
"field": "featured",
"match": {
"value": true
}
}
]
}
weightnumberrequired
Multiplier applied to matching documents. Values greater than 1 increase score; values between 0 and 1 decrease score. Leaving it out, or setting it below 0 or to a non-finite number, returns search:clause:weight_out_of_range.
Matches documents across several rankings, scored and merged by rank. Documents are scored by the sum of weight / (rankConstant + rank) across the rankings that reached them. Because the clause reads only result positions, scores from different scales (such as BM25 text relevance and vector similarity) combine without normalization. Matches at most depth results per ranking. See fuse.
Clauses the ranking searches for, combined with an implicit AND. At least one clause is required.
Example
{
"field": "category",
"match": {
"value": "fiction"
}
}
weightnumber
Multiplier that scales the ranking's contribution relative to other rankings. It cannot reorder results within the ranking.
Default
1
Format
float
depthinteger
Number of results read from each ranking. Pagination cannot exceed the merged list, similar to k in a knn clause. Must be at least 1, and at most EXOFIND_SEARCH_MAX_FUSE_DEPTH.
Default
100
Format
int32
rankConstantnumber
Constant added to each rank before it is inverted. Lower values increase the weight of the highest-ranked results in each ranking; higher values flatten the difference across ranks, giving more weight to documents found by multiple rankings. Must be above 0.
Clauses that narrow every ranking before it is cut to depth. A knn clause inside a ranking applies filter entries as a pre-filter, ensuring the vector ranking returns k results. Clauses placed beside the fuse clause filter the merged list after each ranking is cut to depth.
Example
{
"field": "category",
"match": {
"value": "fiction"
}
}
limitinteger
Maximum number of suggestions to return, at most EXOFIND_SUGGEST_MAX_LIMIT.
Default
5
Format
int32
Range
1 or more
typosSuggestTypos
Whether a value one mistake away from the text may be suggested when fewer values than limit start with it. auto suggests them after the values the text starts, once the text is at least five characters long; a mistake is a character inserted, dropped, replaced, or two adjacent ones swapped, never in the first character. Such a suggestion carries corrected: true and typed: 0. off never suggests them.
What the request demands of the state it is answered from. Omit it to be answered from what the node holds. See Freshness.
1 property
atLeaststring
A freshness token that an earlier response returned in its freshness property or X-Exofind-Freshness header. The node answers only once it holds the state the token describes: the generation, the commit and the search settings. A node that is behind commits, pulls or reads the settings first, and answers search:freshness:unavailable with a Retry-After header when it has waited EXOFIND_SEARCH_FRESHNESS_WAIT without reaching the state. The token is opaque; pass it back unchanged.
Example
"AQoIcHJvZHVjdHMSATIYBw"
Responses
200
The suggestions, the most common first.
SuggestResponse
The suggestions for the typed text, the most common first, with every suggestion the text starts before the ones found a mistake away.
suggestionsSuggestion[]
The suggestions, the most common first and limited to the requested maximum.
Example
{
"text": "adidas",
"typed": 3,
"field": "brand",
"value": "adidas",
"label": "Adidas",
"count": 87
}
7 properties
textstring
What to show and to search for: the label of the value in the locale of the request where the search settings declare one, or the value itself. Where the typed text starts the value but not its label, the value is shown, so that typed says something true. Sending it as the text of a search finds the value, and a corrected suggestion finds it exactly.
Example
"adidas"
typedinteger
How many characters at the start of text the typed text covers, so the part typed can be marked apart from the part that completes it. Counted on text as answered, not on what was typed, so RÖ typed against Röd covers 2. 0 when the suggestion was found a mistake away, and for a blank text.
Format
int32
Example
3
correctedboolean
true when the suggestion was found one mistake away from the text instead of starting with it. Omitted otherwise.
fieldstring
The field the value is held by, as declared in the index definition, which a field clause filtering on the value names.
Example
"brand"
valueany
The value as the field stores it, which a filter on the field matches.
Example
"adidas"
labelstring
The label the search settings of the index declare for the value, in the locale of the request, falling back to the field's default locale. Omitted when the settings declare no label for the value.
Example
"Adidas"
countinteger
Number of documents holding the value under the filters of the request.
Format
int64
Example
87
generationstring
Name of the generation that answered. A request that names the index answers from the generation that is live when it arrives, so add @ and this name to the index name to send a later request to the same data. See Names and generations.
Example
"2"
freshnessstring
A freshness token for the state the answer came from: the generation, its commit, and the version of the search settings. Pass it as freshness.atLeast on a later request, and that request is answered from this state or a later one whichever node it lands on. Opaque; pass it back unchanged. See Freshness.
Example
"AQoIcHJvZHVjdHMSATIYBw"
tookMsnumber
Execution time for the request in milliseconds, including fractions of one.
Format
double
Example
0.412
400
The request is not one that can be answered, or it asks for more than the node allows. See Search configuration for the caps.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The freshness token was issued in a format version this node does not read. The `version` argument carries it; send the request to a node of the release that issued the token.
The freshness token is of another index than the one in the path. The `index` argument carries the index the token is of.
401
The request carries no credential this node accepts. Absent, malformed, unknown and lapsed keys are all answered alike, so a refusal cannot be used to find out which keys exist. The response carries WWW-Authenticate: Bearer.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The request carries no credential this node accepts.
403
The API key does not have the search permission.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The key is accepted but does not hold the `search` permission.
404
The index does not exist, or the key has no permissions on it. An index on which a key has no permissions returns this status as though it did not exist.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The node holds no such index, or the key has no permission on it.
409
The index currently has no live generation (index:no_live_generation). Promote a generation and send the request again.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The index has no live generation. Promote one and send the request again.
503
The request raced the index being closed to free local resources (index:closed). Sending the same request again reopens it.
Also returned when counting collected for longer than EXOFIND_SUGGEST_TIMEOUT (search:timeout). The counts collected before the node stopped are dropped, so narrow the filters instead of repeating the request.
ErrorResponse
The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.
codestring
Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.
Example
"validation"
messagestring
Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.
All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.
"message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
"path": "id"
}
4 properties
codestring
The error code identifying this specific problem.
Example
"index:field:primary_key:multiple_unsupported"
messagestring
Human-readable description of this problem.
Example
"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"
pathstring
Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.
Example
"id"
argumentsmap of string
The values the message was rendered with, so a client can render a message of its own from the code.
The node did not reach the state the freshness token asks for within `EXOFIND_SEARCH_FRESHNESS_WAIT`. Send the request again after the `Retry-After` header.
Served to a request carrying no credential where the node sets an anonymous key.
An API key sent as a bearer token, such as Authorization: Bearer exok_4ff6b760264c1918_ePQcdT1O9HSATZoXfDbT8hhHGsP9VpZH. A key carries grants that pair permissions with index patterns; the permission each endpoint needs is named beside it. Nodes running with EXOFIND_AUTH_MODE=none accept requests without a credential, and a node with EXOFIND_AUTH_ANONYMOUS_KEY set serves requests that carry none with the permissions of that key.
Exofind is built by Level Four AB and is available under the Apache License 2.0.