Returns the search settings as stored, with their version in the ETag header. Settings are read directly from storage rather than from the node's local copy. A request whose If-None-Match header names the stored version is answered 304 Not Modified.
An index with no search settings - one searching with its definition alone - returns 404 with settings:not_found rather than an empty object, ensuring the ETag always represents an explicit stored version.
Served by whichever node receives the request.
Path parameters
namestringrequired
The index the settings belong to. Naming a generation reads the same settings, as they belong to the index name rather than to a generation.
Headers
If-None-Matchstring
Settings versions the client already holds, as ETag values separated by commas, or * for any. While the stored version is one of them, the response is 304 Not Modified with no body.
Responses
200
The stored settings, with their version in the ETag header.
SearchSettingsInfo
The search settings of an index as stored, together with the observed status reported by the answering node. See Search settings.
The ranking searches run with instead of the definition's ranking. Omitted when the settings configure no ranking.
Example
{
"tieBreakers": [
{
"field": "sales",
"direction": "descending"
}
],
"signals": [
{
"field": "purchases",
"saturation": {
"pivot": 50
},
"weight": 0.5
}
]
}
2 properties
tieBreakersTieBreaker[]
Secondary sort criteria applied in sequence after primary sort or relevance scoring until ties are resolved. Target fields must have sort enabled.
Example
{
"field": "sales",
"direction": "descending"
}
2 properties
fieldstringrequired
The field to break ties by. Must have sort enabled.
Example
"sales"
directionDirection
The sort direction for breaking ties. Defaults to descending.
Default
"descending"
Values
"ascending", "descending"
signalsSignalDefinition[]
Document values multiplied into relevance scores in sequence. Evaluated at search time without reindexing, and applied only when results are ordered by relevance. A search request that specifies signals adds to these rules or replaces them based on signalsMode.
Example
{
"field": "purchases",
"saturation": {
"pivot": 50
},
"weight": 0.5
}
5 properties
fieldstringrequired
The field to read the value from. Must be a number or timestamp field with sorting enabled.
Example
"purchases"
saturationRankingSaturation
Ranks by how far the value rises above a pivot. For int32, int64, float and double fields.
Example
{
"pivot": 50
}
1 property
pivotnumberrequired
The value that counts for half of what the signal can give. Required, and must be greater than 0.
Format
double
Example
50
decayRankingDecay
Ranks by how long ago the value was. For timestamp fields.
Example
{
"halfLife": 604800
}
1 property
halfLifeintegerrequired
How many seconds it takes for the signal to be worth half as much. Required, and must be greater than 0.
Format
int64
Example
604800
linearRankingLinear
Ranks by how far the value is toward a ceiling, as value / ceiling held between 0 and 1. For int32, int64, float and double fields holding a score computed elsewhere, such as an engagement score between 0 and 1.
Example
{
"ceiling": 1
}
1 property
ceilingnumberrequired
The value that counts for all of what the signal can give. Required, and must be greater than 0.
Format
double
Example
1
weightnumber
How much the signal can lift a document at most, as a share of its score. At 1, a document at the top of the signal reaches twice the score of one holding no value at all.
Default
1
Format
float
synonymsmap of QuerySynonyms
Synonym sets applied to the text of a search, keyed by set name. Omitted when the settings configure no synonyms.
The rules of the set, using the same shape as rules in an index definition's resources.
Example
{
"equivalent": [
"car",
"automobile"
]
}
2 properties
equivalentstring[]
Interchangeable terms where each term matches every other term. Multi-word terms match words in sequence.
mappingMapping
A one-way mapping rule: values containing a term in from also match searches for any term in to, but not the reverse.
Example
{
"from": [
"ny"
],
"to": [
"new york"
]
}
2 properties
fromstring[]required
Source terms matched by the mapping rule.
tostring[]required
Target terms that the source terms map to.
fieldsstring[]
An optional list of field names the set applies to, named as a search names them. If omitted, the set applies to every field searched as text. Target fields are validated against the generation the index answers from at write time; a generation promoted later that lacks a named field causes searches to skip that field rather than fail.
boostnumber
A positive number specifying what a term added by the rules counts against the typed term. Default 0.8. Values below 1 rank a document holding the typed term above one holding only a synonym. A value of 1 weighs synonyms and typed terms equally.
Format
float
Example
0.8
typoExclusionsmap of TypoExclusions
Words matched as they are spelled, keyed by list name. Omitted when the settings configure no typo exclusions.
Words matched as they are spelled, regardless of the typo tolerance configured on the searched fields.
Example
{
"words": [
"adidas",
"X-15"
],
"fields": [
"name"
]
}
2 properties
wordsstring[]
The words, as typed. Words are read through the analysis chain of each field they are excluded in. A word the chain leaves nothing of (such as a stopword) excludes nothing, and a word the chain produces several terms from excludes each of them.
fieldsstring[]
An optional list of field names the words are excluded in, named as a search names them. If omitted, the list covers every field searched as text. Field names are validated against the active generation at write time; a generation promoted later that lacks a named field applies typo tolerance as configured in the index definition.
fieldsmap of FieldSettings
Settings that apply to one field, keyed by field name. Omitted when the settings configure no field.
How searches read one field. Every capability is off unless its object is present; an empty object turns it on with the engine defaults.
Example
{
"interpret": {},
"suggest": {},
"values": [
{
"value": "S",
"order": 1,
"labels": {
"en": "Small",
"sv": "Liten"
}
}
]
}
3 properties
interpretInterpretUsage
Reads the values the field holds out of the query text of a search in user mode, as a filter on the field. The field must be a string field with filter and facet and without hierarchy; otherwise the request returns settings:fields:interpret_unsupported. Carries no options. See Reading the values of a field.
Example
{}
valuesDeclaredValue[]
Values of the field with a declared order and labels per locale. A facet with "order": "declared" answers these values first, by order, and every other value after them by count. A facet answers each value's label in the locale of the search, a prefix search of the facet matches labels as well as values, and a search in user mode with interpret on the field reads a typed label as its value. The field must be a string field with facet and without hierarchy; otherwise the request returns settings:fields:values_unsupported. At most 10000 values per field. See Field settings.
Example
{
"value": "S",
"order": 1,
"labels": {
"en": "Small",
"sv": "Liten"
}
}
3 properties
valuestring
The value as the field stores it, which is what a facet counts and a filter matches. Required and unique within the field; otherwise the request returns settings:fields:values_invalid.
Example
"S"
orderinteger
Where the value sits in a facet ordered by declared, lower first; values sharing an order are sorted by count. If omitted, the value is ordered by count after every value that has an order, so labels can be declared without an order.
Format
int32
Example
1
labelsmap of string
What a person reads instead of the value, keyed by BCP-47 tag in canonical form (sv, en-GB). A search answers the label of its locale, matched as closely as the tags tell apart, and the label of the field's default locale where its own has none. A tag that is not canonical, or a blank label, returns settings:fields:values_invalid.
1 property
<key>string
suggestSuggest
Suggests the values the field holds while a search is typed, through POST /v1alpha1/indexes/{name}/suggest. The field must be a string field with facet and without hierarchy; otherwise the request returns settings:fields:suggest_unsupported. Carries no options. See Suggesting what to search for.
Example
{}
versionstring
An identifier for the stored settings version, also returned in the ETag header. Pass this value in the If-Match header on PUT and PATCH requests to prevent overwriting concurrent updates; a mismatch returns 412.
Example
"9f2c1a0b3d4e5f60"
unsupportedFeaturesstring[]
Present only when the answering node sets the settings aside because they use capabilities its version does not have. The node searches with the definition alone. Upgrade the node to put the settings in force.
freshnessstring
A freshness token for the state the change landed in. Present on the answer to a PUT and a PATCH, and omitted on a GET. Pass it as freshness.atLeast on a search, and the search is answered with these settings in force whichever node it lands on. Opaque; pass it back unchanged. See Freshness.
Example
"AQoIcHJvZHVjdHMiIiJhYjEyY2QzNCI"
304
The settings are still at a version the If-None-Match header names. The response carries the version in the ETag header and no body.
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 indexes.read 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 `indexes.read` permission.
404
The index has no search settings (settings:not_found), the index does not exist, or the API key lacks permission on the index.
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
Settings storage could not be reached.
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.
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.