Sends a definition in full, replacing any previous definition. Any setting the body omits is removed. Repeating the request produces the same outcome.
The target of the request depends on the name format. books creates the index with an initial generation named 1, or updates the definition of the live generation; books@2 creates that generation under an existing index, or updates its definition. A newly created generation contains no documents and is not live; the index continues serving from the previous live generation until actions/promote is called, and PUT books@2 on an index that does not exist returns 404.
When the target generation already holds documents, a request is refused with 409 and index:definition:incompatible if the new definition changes how documents are indexed, such as enabling a usage on an existing field, changing an analyzer chain, editing a synonym set, or changing type, primaryKey, or multiple. The response includes one detail item per difference, each with the path of the field that caused it. Adding or removing a field, disabling a usage, and changing stored, source, metadata, ranking, or search-time settings are accepted.
Requests run on the node that writes the index; a request received by another node is forwarded there.
Path parameters
namestringrequired
The index, which creates it or updates the live generation, or one generation by name such as books@2.
Query parameters
allowStaleDocumentsboolean
Forces the update without reindexing existing documents. Existing documents continue to serve queries as indexed until they are reindexed. Has no effect on an empty generation.
Default
false
reindexstring
Starts a reindex job filling the generation being created from the live one, the way the reindex action would. One-shot: it is not stored in the definition, and it is refused on a request that creates no generation. auto also needs indexes.promote, because the job it starts promotes the generation it filled; manual needs only indexes.write.
Values
"auto", "manual"
Headers
If-Matchstring
The expected definition version, as returned in a previous ETag header. * asks only that the index exists. Several versions may be given, separated by commas, and the header is satisfied while the stored version is one of them; versions are compared exactly, so a weak tag (W/"...") matches none. An index that does not exist answers 404, and a version that no longer matches answers 412 instead of overwriting intermediate changes.
What an index contains and how it can be searched. A definition is the state a caller wants: it is sent in full and anything left out is removed. Observed state, such as whether the index is usable, is reported separately under status.
sourceSource
How much of a document the index retains. full retains the entire document, enabling full document retrieval and reindexing from the index itself. none retains only fields configured as stored. Changing this setting applies to documents indexed after the update.
Default
"full"
Values
"full", "none"
metadatamap of string
Free-form metadata for the index, not interpreted by the engine.
1 property
<key>string
fieldsmap of FieldDefinition
The fields of the index, keyed by field name. A name contains letters, numbers, underscores, and *, which defines multiple fields at once; a name never contains a dot, which addresses fields inside object fields. The wildcard matches exactly one name. Explicit definitions take precedence, and the longest literal prefix wins among multiple wildcard patterns.
Definition of a field, structured as a tagged union where type selects the field type and the properties available on it. Field usages are opt-in: adding an empty configuration object enables a usage with engine defaults, and only explicitly configured properties are stored, preserving default values across engine updates. See Field types.
Example
{
"type": "string",
"stored": true,
"filter": {},
"matching": {
"highlight": {}
}
}
10 types
StringFieldDefinitiontype: "string"
Represents text data. Field usages are opt-in, each enabled by including its configuration object. An empty object enables a usage with engine defaults. See string.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Specifies how the text of this usage is analyzed. If omitted, the engine generates an analyzer based on the field usage and locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
3 properties
charFiltersCharFilter[]
An array of character filters applied to the raw text before tokenization, in order.
Example
{
"htmlStrip": {}
}
tokenizerTokenizer
The tokenizer that splits text into tokens. If omitted, the engine chooses a tokenizer based on the locale of the value (Unicode segmentation for most locales; language-specific segmentation for Chinese, Japanese, and Korean).
Example
{
"icu": {}
}
filtersTokenFilter[]
An array of token filters applied to tokens, in order.
Example
{
"normalize": {}
}
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
weightnumber
Relative score weight of hits in this field when querying across multiple fields.
Default
1
Format
float
highlightHighlightUsage
Enables highlighted snippet extraction in search responses. Text is stored for highlighting regardless of the stored property. Highlighting targets matching when defined; highlight on autocomplete takes effect only when matching is omitted.
Example
{}
typoToleranceTypoTolerance
Enables typo tolerance for matching search terms, including prefixes currently being typed.
Example
{
"minLengthOneTypo": 5,
"minLengthTwoTypos": 9,
"prefixLength": 1
}
4 properties
minLengthOneTypointeger
Minimum word length required to allow one typo.
Default
5
Format
int32
minLengthTwoTyposinteger
Minimum word length required to allow two typos. In autocomplete, two typos are permitted only when explicitly configured.
Default
9
Format
int32
prefixLengthinteger
Number of leading characters that must match exactly.
Default
1
Format
int32
numbersNumbers
Enables typo tolerance for digit-only words. If omitted, digit-only words require exact matches regardless of length.
Example
{}
decompoundDecompound
Controls compound word splitting in the engine-generated chain. If omitted, splitting is determined by the locale of the value. Supported only when using engine-generated analyzers; custom analyzers specified via analyzer define their own decompounding behavior. See Compound words.
Values
"none"
exactExact
Boosts documents where the query matches the full field value. Adjusts ranking only without modifying hit counts or facet distributions; analyzer normalization is applied before the comparison.
Example
{
"boost": 2
}
1 property
boostnumber
Score boost multiplier applied when a query matches the full field value.
Default
2
Format
float
lengthNormalizationLengthNormalization
Controls the field length penalty in ranking. Changes take effect at search time without reindexing.
Default
"moderate"
Values
"none", "moderate", "strong"
autocompleteTextUsage
Enables prefix matching for as-you-type search queries. A field defined only for autocomplete does not support phrase matching.
Specifies how the text of this usage is analyzed. If omitted, the engine generates an analyzer based on the field usage and locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
3 properties
charFiltersCharFilter[]
An array of character filters applied to the raw text before tokenization, in order.
Example
{
"htmlStrip": {}
}
tokenizerTokenizer
The tokenizer that splits text into tokens. If omitted, the engine chooses a tokenizer based on the locale of the value (Unicode segmentation for most locales; language-specific segmentation for Chinese, Japanese, and Korean).
Example
{
"icu": {}
}
filtersTokenFilter[]
An array of token filters applied to tokens, in order.
Example
{
"normalize": {}
}
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
weightnumber
Relative score weight of hits in this field when querying across multiple fields.
Default
1
Format
float
highlightHighlightUsage
Enables highlighted snippet extraction in search responses. Text is stored for highlighting regardless of the stored property. Highlighting targets matching when defined; highlight on autocomplete takes effect only when matching is omitted.
Example
{}
typoToleranceTypoTolerance
Enables typo tolerance for matching search terms, including prefixes currently being typed.
Example
{
"minLengthOneTypo": 5,
"minLengthTwoTypos": 9,
"prefixLength": 1
}
4 properties
minLengthOneTypointeger
Minimum word length required to allow one typo.
Default
5
Format
int32
minLengthTwoTyposinteger
Minimum word length required to allow two typos. In autocomplete, two typos are permitted only when explicitly configured.
Default
9
Format
int32
prefixLengthinteger
Number of leading characters that must match exactly.
Default
1
Format
int32
numbersNumbers
Enables typo tolerance for digit-only words. If omitted, digit-only words require exact matches regardless of length.
Example
{}
decompoundDecompound
Controls compound word splitting in the engine-generated chain. If omitted, splitting is determined by the locale of the value. Supported only when using engine-generated analyzers; custom analyzers specified via analyzer define their own decompounding behavior. See Compound words.
Values
"none"
exactExact
Boosts documents where the query matches the full field value. Adjusts ranking only without modifying hit counts or facet distributions; analyzer normalization is applied before the comparison.
Example
{
"boost": 2
}
1 property
boostnumber
Score boost multiplier applied when a query matches the full field value.
Default
2
Format
float
lengthNormalizationLengthNormalization
Controls the field length penalty in ranking. Changes take effect at search time without reindexing.
Default
"moderate"
Values
"none", "moderate", "strong"
hierarchyHierarchy
Enables path hierarchy matching (for example, Men/Shoes/Running). Facets on hierarchy fields return nested counts per level, and the under matcher filters to a level and all sub-levels.
Example
{
"separator": "/"
}
1 property
separatorstring
Specifies the string that separates hierarchy levels. Changing the separator on an index that contains documents requires reindexing them.
Default
"/"
BooleanFieldDefinitiontype: "boolean"
Represents boolean values (true or false). A boolean has nothing to analyze, so filtering is the only way to search it.
Example
{
"type": "boolean",
"filter": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Enables value count aggregations. On numeric and timestamp fields, it also enables range buckets.
Example
{}
VectorFieldDefinitiontype: "vector"
Represents an array of floating-point numbers searched by similarity using the knn search clause. Vector fields do not support filter, sort, facet, or locales. Vectors must be supplied in document payloads. See Search by vector.
Example
{
"type": "vector",
"dimensions": 1536,
"similarity": "cosine"
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Not supported on a vector field; setting it is rejected.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Hierarchical Navigable Small World index configuration.
Example
{
"m": 16,
"efConstruction": 100
}
2 properties
minteger
Number of bi-directional links per node.
Format
int32
efConstructioninteger
Size of dynamic candidate list evaluated during index construction.
Format
int32
quantizationQuantization
Vector compression method.
Default
"none"
Values
"none", "int8", "int4"
Int32FieldDefinitiontype: "int32"
Represents a 32-bit signed integer. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "int32",
"filter": {},
"validation": {
"min": 0
}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationInt32Validation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 100
}
2 properties
mininteger
Lowest value accepted.
Format
int32
Example
0
maxinteger
Highest value accepted.
Format
int32
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"SEK"
Int64FieldDefinitiontype: "int64"
Represents a 64-bit signed integer. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "int64",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationInt64Validation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 1099511627776
}
2 properties
mininteger
Lowest value accepted.
Format
int64
maxinteger
Highest value accepted.
Format
int64
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"gigabyte"
FloatFieldDefinitiontype: "float"
Represents a 32-bit floating point number. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "float",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationFloatValidation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 5
}
2 properties
minnumber
Lowest value accepted.
Format
float
maxnumber
Highest value accepted.
Format
float
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"kilogram"
DoubleFieldDefinitiontype: "double"
Represents a 64-bit floating-point number. A number has nothing to analyze, so it is searched by filtering, which supports both exact matches and range queries.
Example
{
"type": "double",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationDoubleValidation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 1000
}
2 properties
minnumber
Lowest value accepted.
Format
double
maxnumber
Highest value accepted.
Format
double
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"EUR"
TimestampFieldDefinitiontype: "timestamp"
Represents an instant in time formatted as an ISO 8601 date-time string with a timezone offset (for example, Z or +02:00). Timestamps are stored and compared at millisecond precision. Values representing the same instant are identical for filtering and sorting; search results return the original string format provided during ingestion. Documents containing timestamps without timezone offsets are rejected.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Enables value count aggregations. On numeric and timestamp fields, it also enables range buckets.
Example
{}
GeoPointFieldDefinitiontype: "geo_point"
Represents a geographic location defined by WGS 84 lat and lon coordinates. Locations are searched by distance rather than exact value: filter enables the distance matcher, and sort enables ordering by distance from an origin, nearest first.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Represents structured object values containing nested field definitions, referenced by dot notation (such as variants.price). An object field cannot configure filter, sort, facet, locales, or stored on itself. Child fields can be objects in turn, though a nested array cannot contain another nested array. An array of objects can specify a key to identify each object value. Object fields are returned in search results through the preserved document source; a stored child field below single objects also answers when the index keeps none. See object.
Example
{
"type": "object",
"multiple": true,
"mode": "nested",
"key": "sku",
"fields": {
"sku": {
"type": "string",
"required": true,
"filter": {}
},
"color": {
"type": "string",
"filter": {}
},
"price": {
"type": "double",
"filter": {}
}
}
}
primaryKeyboolean
Not supported on an object field; setting it is rejected.
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field holds a list of object values, and mode is required. Single object fields are always indexed as flattened objects.
Default
false
storedboolean
Not supported on an object field; setting it is rejected.
Not supported on an object field; setting it is rejected.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Not supported on an object field; setting it is rejected.
Example
{}
modeMode
Storage mode for multiple objects. Required when multiple is true (index:field:object:mode_required) and rejected when it is not (index:field:object:mode_without_multiple).
Values
"nested", "flattened"
keystring
Names a child field as the unique identifier for each object value in an array. Targets object values in update paths (such as variants[V-2]) and populates key on search value hits. Requires multiple: true (index:field:object:key_without_multiple). Must name a field defined in fields (index:field:object:key_unknown) that is required, not multiple, and of type string, int32, or int64 (index:field:object:key_invalid). Duplicate key values within a document are rejected with document:object_key_duplicate.
fieldsmap of FieldDefinition
Map of child field names to field definitions, the object type included - objects nest, though a nested array cannot contain another nested array (index:field:object:nested_in_nested). What a child field may configure follows from where it sits: sort and stored are rejected below a flattened array (index:field:object:flattened_sort_unsupported, index:field:object:flattened_stored_unsupported), and primaryKey is rejected inside any object (index:field:object:inner_usage_unsupported). Below a nested array stored and highlight work - highlighted fragments come back on value hits. locales works everywhere.
Definition of a field, structured as a tagged union where type selects the field type and the properties available on it. Field usages are opt-in: adding an empty configuration object enables a usage with engine defaults, and only explicitly configured properties are stored, preserving default values across engine updates. See Field types.
Tie-breaking rules and ranking signals. Omitted to order results by match score alone. Replaced entirely while an index has search settings.
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
resourcesResources
Shared resources referenced by name from fields, including named analysis chains, stopword lists, and synonym sets.
Example
{
"analyzers": {
"prose": {
"preset": "full_text"
}
},
"stopwords": {
"brands": [
"acme"
]
},
"synonyms": {
"cars": {
"rules": [
{
"equivalent": [
"car",
"automobile"
]
},
{
"mapping": {
"from": [
"ny"
],
"to": [
"new york"
]
}
}
]
}
}
}
3 properties
analyzersmap of AnalyzerDefinition
Named analysis chains, referenced from a field usage with "analyzer": { "named": "..." }. Presets are expanded the same way as on a field.
Specifies how the text of a usage is analyzed, with exactly one of preset, custom, or named. An analyzer chain describes the indexing process. The engine derives the query analyzer from the indexing chain. Components that select words by locale, such as stopwords and stemming, use the locale of the value being analyzed unless you specify a locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
3 properties
charFiltersCharFilter[]
An array of character filters applied to the raw text before tokenization, in order.
Example
{
"htmlStrip": {}
}
3 properties
htmlStripHtmlStrip
Strips HTML and XML markup and keeps text between tags.
Example
{}
mappingMappingCharFilter
Replaces occurrences of each key with its value.
Example
{
"mappings": {
"&": " and "
}
}
1 property
mappingsmap of stringrequired
Replaces occurrences of each key with its value.
patternReplacePatternReplace
Replaces substrings that match a regular expression.
Example
{
"pattern": "\\s+",
"replacement": ""
}
2 properties
patternstringrequired
The regular expression to match.
replacementstringrequired
What each match is replaced with.
tokenizerTokenizer
The tokenizer that splits text into tokens. If omitted, the engine chooses a tokenizer based on the locale of the value (Unicode segmentation for most locales; language-specific segmentation for Chinese, Japanese, and Korean).
Example
{
"icu": {}
}
4 properties
icuIcuTokenizer
Segments text based on Unicode rules. This is the default tokenizer.
Example
{}
whitespaceWhitespaceTokenizer
Splits text on whitespace characters.
Example
{}
keywordKeywordTokenizer
Retains the entire input value as a single token.
Example
{}
letterLetterTokenizer
Splits text on non-letter characters.
Example
{}
filtersTokenFilter[]
An array of token filters applied to tokens, in order.
Example
{
"normalize": {}
}
8 properties
normalizeNormalize
Applies Unicode normalization and case folding to make analysis case-insensitive.
Example
{
"caseFolding": true
}
1 property
caseFoldingboolean
Whether case folding is applied.
Default
true
stopwordsStopwordsFilter
Removes frequent words.
Example
{
"locale": "sv"
}
3 properties
localestring
BCP-47 locale whose stopwords to remove.
Example
"sv"
wordsstring[]
A list of words to remove.
namedstring
Name of a stopword list defined under the index's resources.
Example
"brands"
stemmingStemming
Reduces words to a shared root.
Example
{
"locale": "sv"
}
1 property
localestring
BCP-47 locale whose rules to stem by. If omitted, uses the stemmer for the locale of the value being analyzed.
Example
"sv"
asciiFoldingAsciiFolding
Converts non-ASCII characters to ASCII equivalents.
Example
{
"preserveOriginal": true
}
1 property
preserveOriginalboolean
Whether to preserve the original non-ASCII token alongside the folded one.
Default
false
edgeNgramEdgeNgram
Generates prefix n-grams for tokens within the specified character lengths.
Example
{
"minGram": 1,
"maxGram": 20
}
2 properties
minGraminteger
The shortest prefix to index.
Default
1
Format
int32
maxGraminteger
The longest prefix to index.
Default
20
Format
int32
ngramNgram
Generates substring n-grams for tokens within the specified character lengths.
Example
{
"minGram": 3,
"maxGram": 5
}
2 properties
minGraminteger
The shortest substring to index.
Format
int32
maxGraminteger
The longest substring to index.
Format
int32
synonymsSynonymsFilter
Expands tokens with synonyms from a synonym set defined in resources. Applied when a value is indexed, not when the text of a search is analyzed.
Example
{
"named": "cars"
}
1 property
namedstringrequired
Name of a synonym set defined under the index's resources.
Example
"cars"
decompoundDecompoundFilter
Splits compound words into parts and retains the original compound word. See Compound words. Applied at index time.
Example
{
"locale": "sv"
}
1 property
localestring
BCP-47 locale whose rules and dictionary split the words. Omitted, the locale of the value being analyzed is used; a value in a locale the engine has no decompounding data for passes through unsplit.
Example
"sv"
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
stopwordsmap of string[]
Named stopword lists, referenced from the stopwords component of an analyzer chain with "stopwords": { "named": "..." }.
1 property
<key>string[]
synonymsmap of Synonyms
Named synonym sets, referenced from the synonyms component of an analyzer chain with "synonyms": { "named": "..." }.
1 property
<key>Synonyms
Synonym rules applied during indexing. Modifying a synonym set applies only to documents indexed after the change.
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.
localesIndexLocales
Declares the locales that localized fields in the index support. A field opts in with "locales": {} to hold all declared locales, or narrows to fewer with "locales": { "only": [...] }. The engine expands the declaration onto each field before storing the index definition, so reading a definition back returns the locales on each field. If omitted, each field declares its own locales.
Example
{
"defaultLocale": "en",
"supported": [
"sv",
"de"
]
}
2 properties
defaultLocalestringrequired
Specifies the BCP-47 locale for values that carry no explicit locale. A field uses this value as its default locale unless the field defines its own defaultLocale. This property is required whenever an index declares locales.
Example
"en"
supportedstring[]
Lists additional BCP-47 locales that the index supports, in addition to defaultLocale. A field can narrow to a subset of these supported locales and the default locale by using only.
localeFallbackLocaleFallback
Configures how missing locale values in a document are populated from available locales during indexing. When omitted, missing locales remain empty, and searches in a locale find only documents translated into it.
Example
{
"chain": [
"da",
"en"
]
}
1 property
chainstring[]
Ordered list of locales to evaluate when populating a missing locale value. A field skips locales for which it has no value, allowing a single chain to serve fields with different configured locales. Specifying a locale not defined on any field in the index is rejected. When omitted, each field falls back to its defaultLocale.
Responses
200
An existing definition was replaced. The new version is in the ETag header.
IndexInfo
An index together with the definition and status of one of its generations: the generation specified in the request, or the live generation if omitted. See Index resource.
namestring
The name of the index.
Example
"products"
generationstring
The generation described in the response. When the request specifies only the index name, this is the live generation.
Example
"2"
liveboolean
A boolean indicating whether this generation is the live generation.
versionstring
An identifier for the definition, also returned in the ETag header. Pass this value in the If-Match header on PUT requests to prevent overwriting concurrent updates.
The active index definition. Presets are stored expanded; the response returns the expanded chain rather than the preset name.
Example
{
"fields": {
"id": {
"type": "string",
"primaryKey": true,
"required": true
},
"name": {
"type": "string",
"matching": {},
"sort": {}
},
"category": {
"type": "string",
"filter": {},
"facet": {}
},
"price": {
"type": "float",
"filter": {},
"sort": {}
},
"published": {
"type": "boolean",
"filter": {}
}
}
}
7 properties
sourceSource
How much of a document the index retains. full retains the entire document, enabling full document retrieval and reindexing from the index itself. none retains only fields configured as stored. Changing this setting applies to documents indexed after the update.
Default
"full"
Values
"full", "none"
metadatamap of string
Free-form metadata for the index, not interpreted by the engine.
1 property
<key>string
fieldsmap of FieldDefinition
The fields of the index, keyed by field name. A name contains letters, numbers, underscores, and *, which defines multiple fields at once; a name never contains a dot, which addresses fields inside object fields. The wildcard matches exactly one name. Explicit definitions take precedence, and the longest literal prefix wins among multiple wildcard patterns.
Definition of a field, structured as a tagged union where type selects the field type and the properties available on it. Field usages are opt-in: adding an empty configuration object enables a usage with engine defaults, and only explicitly configured properties are stored, preserving default values across engine updates. See Field types.
Example
{
"type": "string",
"stored": true,
"filter": {},
"matching": {
"highlight": {}
}
}
10 types
StringFieldDefinitiontype: "string"
Represents text data. Field usages are opt-in, each enabled by including its configuration object. An empty object enables a usage with engine defaults. See string.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Specifies how the text of this usage is analyzed. If omitted, the engine generates an analyzer based on the field usage and locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
weightnumber
Relative score weight of hits in this field when querying across multiple fields.
Default
1
Format
float
highlightHighlightUsage
Enables highlighted snippet extraction in search responses. Text is stored for highlighting regardless of the stored property. Highlighting targets matching when defined; highlight on autocomplete takes effect only when matching is omitted.
Example
{}
typoToleranceTypoTolerance
Enables typo tolerance for matching search terms, including prefixes currently being typed.
Example
{
"minLengthOneTypo": 5,
"minLengthTwoTypos": 9,
"prefixLength": 1
}
4 properties
minLengthOneTypointeger
Minimum word length required to allow one typo.
Default
5
Format
int32
minLengthTwoTyposinteger
Minimum word length required to allow two typos. In autocomplete, two typos are permitted only when explicitly configured.
Default
9
Format
int32
prefixLengthinteger
Number of leading characters that must match exactly.
Default
1
Format
int32
numbersNumbers
Enables typo tolerance for digit-only words. If omitted, digit-only words require exact matches regardless of length.
Example
{}
decompoundDecompound
Controls compound word splitting in the engine-generated chain. If omitted, splitting is determined by the locale of the value. Supported only when using engine-generated analyzers; custom analyzers specified via analyzer define their own decompounding behavior. See Compound words.
Values
"none"
exactExact
Boosts documents where the query matches the full field value. Adjusts ranking only without modifying hit counts or facet distributions; analyzer normalization is applied before the comparison.
Example
{
"boost": 2
}
1 property
boostnumber
Score boost multiplier applied when a query matches the full field value.
Default
2
Format
float
lengthNormalizationLengthNormalization
Controls the field length penalty in ranking. Changes take effect at search time without reindexing.
Default
"moderate"
Values
"none", "moderate", "strong"
autocompleteTextUsage
Enables prefix matching for as-you-type search queries. A field defined only for autocomplete does not support phrase matching.
Specifies how the text of this usage is analyzed. If omitted, the engine generates an analyzer based on the field usage and locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
weightnumber
Relative score weight of hits in this field when querying across multiple fields.
Default
1
Format
float
highlightHighlightUsage
Enables highlighted snippet extraction in search responses. Text is stored for highlighting regardless of the stored property. Highlighting targets matching when defined; highlight on autocomplete takes effect only when matching is omitted.
Example
{}
typoToleranceTypoTolerance
Enables typo tolerance for matching search terms, including prefixes currently being typed.
Example
{
"minLengthOneTypo": 5,
"minLengthTwoTypos": 9,
"prefixLength": 1
}
4 properties
minLengthOneTypointeger
Minimum word length required to allow one typo.
Default
5
Format
int32
minLengthTwoTyposinteger
Minimum word length required to allow two typos. In autocomplete, two typos are permitted only when explicitly configured.
Default
9
Format
int32
prefixLengthinteger
Number of leading characters that must match exactly.
Default
1
Format
int32
numbersNumbers
Enables typo tolerance for digit-only words. If omitted, digit-only words require exact matches regardless of length.
Example
{}
decompoundDecompound
Controls compound word splitting in the engine-generated chain. If omitted, splitting is determined by the locale of the value. Supported only when using engine-generated analyzers; custom analyzers specified via analyzer define their own decompounding behavior. See Compound words.
Values
"none"
exactExact
Boosts documents where the query matches the full field value. Adjusts ranking only without modifying hit counts or facet distributions; analyzer normalization is applied before the comparison.
Example
{
"boost": 2
}
1 property
boostnumber
Score boost multiplier applied when a query matches the full field value.
Default
2
Format
float
lengthNormalizationLengthNormalization
Controls the field length penalty in ranking. Changes take effect at search time without reindexing.
Default
"moderate"
Values
"none", "moderate", "strong"
hierarchyHierarchy
Enables path hierarchy matching (for example, Men/Shoes/Running). Facets on hierarchy fields return nested counts per level, and the under matcher filters to a level and all sub-levels.
Example
{
"separator": "/"
}
1 property
separatorstring
Specifies the string that separates hierarchy levels. Changing the separator on an index that contains documents requires reindexing them.
Default
"/"
BooleanFieldDefinitiontype: "boolean"
Represents boolean values (true or false). A boolean has nothing to analyze, so filtering is the only way to search it.
Example
{
"type": "boolean",
"filter": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Enables value count aggregations. On numeric and timestamp fields, it also enables range buckets.
Example
{}
VectorFieldDefinitiontype: "vector"
Represents an array of floating-point numbers searched by similarity using the knn search clause. Vector fields do not support filter, sort, facet, or locales. Vectors must be supplied in document payloads. See Search by vector.
Example
{
"type": "vector",
"dimensions": 1536,
"similarity": "cosine"
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Not supported on a vector field; setting it is rejected.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Hierarchical Navigable Small World index configuration.
Example
{
"m": 16,
"efConstruction": 100
}
2 properties
minteger
Number of bi-directional links per node.
Format
int32
efConstructioninteger
Size of dynamic candidate list evaluated during index construction.
Format
int32
quantizationQuantization
Vector compression method.
Default
"none"
Values
"none", "int8", "int4"
Int32FieldDefinitiontype: "int32"
Represents a 32-bit signed integer. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "int32",
"filter": {},
"validation": {
"min": 0
}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationInt32Validation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 100
}
2 properties
mininteger
Lowest value accepted.
Format
int32
Example
0
maxinteger
Highest value accepted.
Format
int32
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"SEK"
Int64FieldDefinitiontype: "int64"
Represents a 64-bit signed integer. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "int64",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationInt64Validation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 1099511627776
}
2 properties
mininteger
Lowest value accepted.
Format
int64
maxinteger
Highest value accepted.
Format
int64
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"gigabyte"
FloatFieldDefinitiontype: "float"
Represents a 32-bit floating point number. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "float",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationFloatValidation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 5
}
2 properties
minnumber
Lowest value accepted.
Format
float
maxnumber
Highest value accepted.
Format
float
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"kilogram"
DoubleFieldDefinitiontype: "double"
Represents a 64-bit floating-point number. A number has nothing to analyze, so it is searched by filtering, which supports both exact matches and range queries.
Example
{
"type": "double",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationDoubleValidation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 1000
}
2 properties
minnumber
Lowest value accepted.
Format
double
maxnumber
Highest value accepted.
Format
double
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"EUR"
TimestampFieldDefinitiontype: "timestamp"
Represents an instant in time formatted as an ISO 8601 date-time string with a timezone offset (for example, Z or +02:00). Timestamps are stored and compared at millisecond precision. Values representing the same instant are identical for filtering and sorting; search results return the original string format provided during ingestion. Documents containing timestamps without timezone offsets are rejected.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Enables value count aggregations. On numeric and timestamp fields, it also enables range buckets.
Example
{}
GeoPointFieldDefinitiontype: "geo_point"
Represents a geographic location defined by WGS 84 lat and lon coordinates. Locations are searched by distance rather than exact value: filter enables the distance matcher, and sort enables ordering by distance from an origin, nearest first.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Represents structured object values containing nested field definitions, referenced by dot notation (such as variants.price). An object field cannot configure filter, sort, facet, locales, or stored on itself. Child fields can be objects in turn, though a nested array cannot contain another nested array. An array of objects can specify a key to identify each object value. Object fields are returned in search results through the preserved document source; a stored child field below single objects also answers when the index keeps none. See object.
Example
{
"type": "object",
"multiple": true,
"mode": "nested",
"key": "sku",
"fields": {
"sku": {
"type": "string",
"required": true,
"filter": {}
},
"color": {
"type": "string",
"filter": {}
},
"price": {
"type": "double",
"filter": {}
}
}
}
primaryKeyboolean
Not supported on an object field; setting it is rejected.
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field holds a list of object values, and mode is required. Single object fields are always indexed as flattened objects.
Default
false
storedboolean
Not supported on an object field; setting it is rejected.
Not supported on an object field; setting it is rejected.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Not supported on an object field; setting it is rejected.
Example
{}
modeMode
Storage mode for multiple objects. Required when multiple is true (index:field:object:mode_required) and rejected when it is not (index:field:object:mode_without_multiple).
Values
"nested", "flattened"
keystring
Names a child field as the unique identifier for each object value in an array. Targets object values in update paths (such as variants[V-2]) and populates key on search value hits. Requires multiple: true (index:field:object:key_without_multiple). Must name a field defined in fields (index:field:object:key_unknown) that is required, not multiple, and of type string, int32, or int64 (index:field:object:key_invalid). Duplicate key values within a document are rejected with document:object_key_duplicate.
fieldsmap of FieldDefinition
Map of child field names to field definitions, the object type included - objects nest, though a nested array cannot contain another nested array (index:field:object:nested_in_nested). What a child field may configure follows from where it sits: sort and stored are rejected below a flattened array (index:field:object:flattened_sort_unsupported, index:field:object:flattened_stored_unsupported), and primaryKey is rejected inside any object (index:field:object:inner_usage_unsupported). Below a nested array stored and highlight work - highlighted fragments come back on value hits. locales works everywhere.
Definition of a field, structured as a tagged union where type selects the field type and the properties available on it. Field usages are opt-in: adding an empty configuration object enables a usage with engine defaults, and only explicitly configured properties are stored, preserving default values across engine updates. See Field types.
Tie-breaking rules and ranking signals. Omitted to order results by match score alone. Replaced entirely while an index has search settings.
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
resourcesResources
Shared resources referenced by name from fields, including named analysis chains, stopword lists, and synonym sets.
Example
{
"analyzers": {
"prose": {
"preset": "full_text"
}
},
"stopwords": {
"brands": [
"acme"
]
},
"synonyms": {
"cars": {
"rules": [
{
"equivalent": [
"car",
"automobile"
]
},
{
"mapping": {
"from": [
"ny"
],
"to": [
"new york"
]
}
}
]
}
}
}
3 properties
analyzersmap of AnalyzerDefinition
Named analysis chains, referenced from a field usage with "analyzer": { "named": "..." }. Presets are expanded the same way as on a field.
Specifies how the text of a usage is analyzed, with exactly one of preset, custom, or named. An analyzer chain describes the indexing process. The engine derives the query analyzer from the indexing chain. Components that select words by locale, such as stopwords and stemming, use the locale of the value being analyzed unless you specify a locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
3 properties
charFiltersCharFilter[]
An array of character filters applied to the raw text before tokenization, in order.
Example
{
"htmlStrip": {}
}
3 properties
htmlStripHtmlStrip
Strips HTML and XML markup and keeps text between tags.
Example
{}
mappingMappingCharFilter
Replaces occurrences of each key with its value.
Example
{
"mappings": {
"&": " and "
}
}
patternReplacePatternReplace
Replaces substrings that match a regular expression.
Example
{
"pattern": "\\s+",
"replacement": ""
}
tokenizerTokenizer
The tokenizer that splits text into tokens. If omitted, the engine chooses a tokenizer based on the locale of the value (Unicode segmentation for most locales; language-specific segmentation for Chinese, Japanese, and Korean).
Example
{
"icu": {}
}
4 properties
icuIcuTokenizer
Segments text based on Unicode rules. This is the default tokenizer.
Example
{}
whitespaceWhitespaceTokenizer
Splits text on whitespace characters.
Example
{}
keywordKeywordTokenizer
Retains the entire input value as a single token.
Example
{}
letterLetterTokenizer
Splits text on non-letter characters.
Example
{}
filtersTokenFilter[]
An array of token filters applied to tokens, in order.
Example
{
"normalize": {}
}
8 properties
normalizeNormalize
Applies Unicode normalization and case folding to make analysis case-insensitive.
Example
{
"caseFolding": true
}
stopwordsStopwordsFilter
Removes frequent words.
Example
{
"locale": "sv"
}
stemmingStemming
Reduces words to a shared root.
Example
{
"locale": "sv"
}
asciiFoldingAsciiFolding
Converts non-ASCII characters to ASCII equivalents.
Example
{
"preserveOriginal": true
}
edgeNgramEdgeNgram
Generates prefix n-grams for tokens within the specified character lengths.
Example
{
"minGram": 1,
"maxGram": 20
}
ngramNgram
Generates substring n-grams for tokens within the specified character lengths.
Example
{
"minGram": 3,
"maxGram": 5
}
synonymsSynonymsFilter
Expands tokens with synonyms from a synonym set defined in resources. Applied when a value is indexed, not when the text of a search is analyzed.
Example
{
"named": "cars"
}
decompoundDecompoundFilter
Splits compound words into parts and retains the original compound word. See Compound words. Applied at index time.
Example
{
"locale": "sv"
}
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
stopwordsmap of string[]
Named stopword lists, referenced from the stopwords component of an analyzer chain with "stopwords": { "named": "..." }.
1 property
<key>string[]
synonymsmap of Synonyms
Named synonym sets, referenced from the synonyms component of an analyzer chain with "synonyms": { "named": "..." }.
1 property
<key>Synonyms
Synonym rules applied during indexing. Modifying a synonym set applies only to documents indexed after the change.
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.
localesIndexLocales
Declares the locales that localized fields in the index support. A field opts in with "locales": {} to hold all declared locales, or narrows to fewer with "locales": { "only": [...] }. The engine expands the declaration onto each field before storing the index definition, so reading a definition back returns the locales on each field. If omitted, each field declares its own locales.
Example
{
"defaultLocale": "en",
"supported": [
"sv",
"de"
]
}
2 properties
defaultLocalestringrequired
Specifies the BCP-47 locale for values that carry no explicit locale. A field uses this value as its default locale unless the field defines its own defaultLocale. This property is required whenever an index declares locales.
Example
"en"
supportedstring[]
Lists additional BCP-47 locales that the index supports, in addition to defaultLocale. A field can narrow to a subset of these supported locales and the default locale by using only.
localeFallbackLocaleFallback
Configures how missing locale values in a document are populated from available locales during indexing. When omitted, missing locales remain empty, and searches in a locale find only documents translated into it.
Example
{
"chain": [
"da",
"en"
]
}
1 property
chainstring[]
Ordered list of locales to evaluate when populating a missing locale value. A field skips locales for which it has no value, allowing a single chain to serve fields with different configured locales. Specifying a locale not defined on any field in the index is rejected. When omitted, each field falls back to its defaultLocale.
statusIndexStatus
The observed state reported by the answering node. The API does not accept this object as input.
Example
{
"state": "usable",
"readOnly": false,
"indexer": {
"node": "node-a-7f21",
"address": "http://node-a:8080"
},
"luceneCompatibility": "current",
"luceneCreatedMajor": 10
}
6 properties
stateIndexState
The remote synchronization state as observed by the answering node: needs_pull (a newer remote state exists and has not been pulled yet), pulling (the node is fetching remote state), usable (the index is serving searches), modified (the index has local changes that are not yet pushed; only writer nodes reach this state), pushing (the node is pushing local changes), unsupported (the definition requires engine features not present on this node version), incompatible (the Lucene files are too old for this build to open), or closed (the index is closed on this node; a new request opens a fresh instance).
Indicates whether the answering node can modify the index. Only the node holding the index can modify it; other nodes serve searches from their local copy.
indexerIndexerInfo
Identifies the holder node and the address where writes are forwarded. Omitted if no node holds the index, if the holder could not be read, if the holder provided no address, or on nodes using local storage where readOnly already answers. Data in this field can lag behind a node handover by a few seconds.
Example
{
"node": "node-a-7f21",
"address": "http://node-a:8080"
}
2 properties
nodestring
The name the node competes under.
Example
"node-a-7f21"
addressstring
The target address for write forwarding. Omitted when the node did not set EXOFIND_NODE_ADDRESS.
Example
"http://node-a:8080"
luceneCompatibilityLuceneCompatibility
Indicates Lucene version compatibility. current: created by the current major version, and compatible with the current and next Lucene major versions. ending: readable by the current version, but unsupported by the next Lucene major version; reindex before upgrading across major versions. unreadable: too old to open; the index reports the incompatible state and requires reindexing. unknown: no version was recorded and no commit exists to determine the version, such as on an empty index.
Values
"unknown", "current", "ending", "unreadable"
luceneCreatedMajorinteger
The recorded Lucene major version the index was created with. Omitted when compatibility is unknown.
Format
int32
Example
10
settingsUnsupportedFeaturesstring[]
Lists the capabilities the index's search settings use that the answering node does not have. Present only when the node has set the settings aside and searches with the definition alone; upgrading the node puts them back in force.
A list of all generations for the index, ordered by name.
Example
{
"name": "2",
"live": true,
"createdAt": "2026-08-16T11:02:07Z"
}
3 properties
namestring
Name of the generation within its index, which is what follows the @ when addressing it as products@2.
Example
"2"
liveboolean
Whether the index answers from this generation. Exactly one generation of an index does, unless the index has just been created.
createdAtstring
When the generation was created, as an ISO 8601 timestamp. Omitted for a generation registered before this was recorded.
Example
"2026-08-16T11:02:07Z"
freshnessstring
A freshness token for the state the action landed in. Present on the answer to a commit and to a promotion, and omitted elsewhere. Pass it as freshness.atLeast on a search, and the search is answered only once the node holds the commit or answers from the promoted generation. Opaque; pass it back unchanged. See Freshness.
Example
"AQoIcHJvZHVjdHMSATIYBw"
201
The index or generation was created. The version is in the ETag header and the location in Location.
IndexInfo
An index together with the definition and status of one of its generations: the generation specified in the request, or the live generation if omitted. See Index resource.
namestring
The name of the index.
Example
"products"
generationstring
The generation described in the response. When the request specifies only the index name, this is the live generation.
Example
"2"
liveboolean
A boolean indicating whether this generation is the live generation.
versionstring
An identifier for the definition, also returned in the ETag header. Pass this value in the If-Match header on PUT requests to prevent overwriting concurrent updates.
The active index definition. Presets are stored expanded; the response returns the expanded chain rather than the preset name.
Example
{
"fields": {
"id": {
"type": "string",
"primaryKey": true,
"required": true
},
"name": {
"type": "string",
"matching": {},
"sort": {}
},
"category": {
"type": "string",
"filter": {},
"facet": {}
},
"price": {
"type": "float",
"filter": {},
"sort": {}
},
"published": {
"type": "boolean",
"filter": {}
}
}
}
7 properties
sourceSource
How much of a document the index retains. full retains the entire document, enabling full document retrieval and reindexing from the index itself. none retains only fields configured as stored. Changing this setting applies to documents indexed after the update.
Default
"full"
Values
"full", "none"
metadatamap of string
Free-form metadata for the index, not interpreted by the engine.
1 property
<key>string
fieldsmap of FieldDefinition
The fields of the index, keyed by field name. A name contains letters, numbers, underscores, and *, which defines multiple fields at once; a name never contains a dot, which addresses fields inside object fields. The wildcard matches exactly one name. Explicit definitions take precedence, and the longest literal prefix wins among multiple wildcard patterns.
Definition of a field, structured as a tagged union where type selects the field type and the properties available on it. Field usages are opt-in: adding an empty configuration object enables a usage with engine defaults, and only explicitly configured properties are stored, preserving default values across engine updates. See Field types.
Example
{
"type": "string",
"stored": true,
"filter": {},
"matching": {
"highlight": {}
}
}
10 types
StringFieldDefinitiontype: "string"
Represents text data. Field usages are opt-in, each enabled by including its configuration object. An empty object enables a usage with engine defaults. See string.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Specifies how the text of this usage is analyzed. If omitted, the engine generates an analyzer based on the field usage and locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
weightnumber
Relative score weight of hits in this field when querying across multiple fields.
Default
1
Format
float
highlightHighlightUsage
Enables highlighted snippet extraction in search responses. Text is stored for highlighting regardless of the stored property. Highlighting targets matching when defined; highlight on autocomplete takes effect only when matching is omitted.
Example
{}
typoToleranceTypoTolerance
Enables typo tolerance for matching search terms, including prefixes currently being typed.
Example
{
"minLengthOneTypo": 5,
"minLengthTwoTypos": 9,
"prefixLength": 1
}
4 properties
minLengthOneTypointeger
Minimum word length required to allow one typo.
Default
5
Format
int32
minLengthTwoTyposinteger
Minimum word length required to allow two typos. In autocomplete, two typos are permitted only when explicitly configured.
Default
9
Format
int32
prefixLengthinteger
Number of leading characters that must match exactly.
Default
1
Format
int32
numbersNumbers
Enables typo tolerance for digit-only words. If omitted, digit-only words require exact matches regardless of length.
Example
{}
decompoundDecompound
Controls compound word splitting in the engine-generated chain. If omitted, splitting is determined by the locale of the value. Supported only when using engine-generated analyzers; custom analyzers specified via analyzer define their own decompounding behavior. See Compound words.
Values
"none"
exactExact
Boosts documents where the query matches the full field value. Adjusts ranking only without modifying hit counts or facet distributions; analyzer normalization is applied before the comparison.
Example
{
"boost": 2
}
1 property
boostnumber
Score boost multiplier applied when a query matches the full field value.
Default
2
Format
float
lengthNormalizationLengthNormalization
Controls the field length penalty in ranking. Changes take effect at search time without reindexing.
Default
"moderate"
Values
"none", "moderate", "strong"
autocompleteTextUsage
Enables prefix matching for as-you-type search queries. A field defined only for autocomplete does not support phrase matching.
Specifies how the text of this usage is analyzed. If omitted, the engine generates an analyzer based on the field usage and locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
weightnumber
Relative score weight of hits in this field when querying across multiple fields.
Default
1
Format
float
highlightHighlightUsage
Enables highlighted snippet extraction in search responses. Text is stored for highlighting regardless of the stored property. Highlighting targets matching when defined; highlight on autocomplete takes effect only when matching is omitted.
Example
{}
typoToleranceTypoTolerance
Enables typo tolerance for matching search terms, including prefixes currently being typed.
Example
{
"minLengthOneTypo": 5,
"minLengthTwoTypos": 9,
"prefixLength": 1
}
4 properties
minLengthOneTypointeger
Minimum word length required to allow one typo.
Default
5
Format
int32
minLengthTwoTyposinteger
Minimum word length required to allow two typos. In autocomplete, two typos are permitted only when explicitly configured.
Default
9
Format
int32
prefixLengthinteger
Number of leading characters that must match exactly.
Default
1
Format
int32
numbersNumbers
Enables typo tolerance for digit-only words. If omitted, digit-only words require exact matches regardless of length.
Example
{}
decompoundDecompound
Controls compound word splitting in the engine-generated chain. If omitted, splitting is determined by the locale of the value. Supported only when using engine-generated analyzers; custom analyzers specified via analyzer define their own decompounding behavior. See Compound words.
Values
"none"
exactExact
Boosts documents where the query matches the full field value. Adjusts ranking only without modifying hit counts or facet distributions; analyzer normalization is applied before the comparison.
Example
{
"boost": 2
}
1 property
boostnumber
Score boost multiplier applied when a query matches the full field value.
Default
2
Format
float
lengthNormalizationLengthNormalization
Controls the field length penalty in ranking. Changes take effect at search time without reindexing.
Default
"moderate"
Values
"none", "moderate", "strong"
hierarchyHierarchy
Enables path hierarchy matching (for example, Men/Shoes/Running). Facets on hierarchy fields return nested counts per level, and the under matcher filters to a level and all sub-levels.
Example
{
"separator": "/"
}
1 property
separatorstring
Specifies the string that separates hierarchy levels. Changing the separator on an index that contains documents requires reindexing them.
Default
"/"
BooleanFieldDefinitiontype: "boolean"
Represents boolean values (true or false). A boolean has nothing to analyze, so filtering is the only way to search it.
Example
{
"type": "boolean",
"filter": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Enables value count aggregations. On numeric and timestamp fields, it also enables range buckets.
Example
{}
VectorFieldDefinitiontype: "vector"
Represents an array of floating-point numbers searched by similarity using the knn search clause. Vector fields do not support filter, sort, facet, or locales. Vectors must be supplied in document payloads. See Search by vector.
Example
{
"type": "vector",
"dimensions": 1536,
"similarity": "cosine"
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Not supported on a vector field; setting it is rejected.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Hierarchical Navigable Small World index configuration.
Example
{
"m": 16,
"efConstruction": 100
}
2 properties
minteger
Number of bi-directional links per node.
Format
int32
efConstructioninteger
Size of dynamic candidate list evaluated during index construction.
Format
int32
quantizationQuantization
Vector compression method.
Default
"none"
Values
"none", "int8", "int4"
Int32FieldDefinitiontype: "int32"
Represents a 32-bit signed integer. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "int32",
"filter": {},
"validation": {
"min": 0
}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationInt32Validation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 100
}
2 properties
mininteger
Lowest value accepted.
Format
int32
Example
0
maxinteger
Highest value accepted.
Format
int32
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"SEK"
Int64FieldDefinitiontype: "int64"
Represents a 64-bit signed integer. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "int64",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationInt64Validation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 1099511627776
}
2 properties
mininteger
Lowest value accepted.
Format
int64
maxinteger
Highest value accepted.
Format
int64
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"gigabyte"
FloatFieldDefinitiontype: "float"
Represents a 32-bit floating point number. Numeric fields do not support text analysis and are searched by filtering, which supports exact matches and range queries.
Example
{
"type": "float",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationFloatValidation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 5
}
2 properties
minnumber
Lowest value accepted.
Format
float
maxnumber
Highest value accepted.
Format
float
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"kilogram"
DoubleFieldDefinitiontype: "double"
Represents a 64-bit floating-point number. A number has nothing to analyze, so it is searched by filtering, which supports both exact matches and range queries.
Example
{
"type": "double",
"filter": {},
"sort": {}
}
primaryKeyboolean
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Makes the field a ranking signal that is refreshed in place through the document update action, without indexing the document again. A signal field is sortable and is returned in results, but is left out of the document source and cannot be combined with filter, facet, stored, multiple, locales or primaryKey. A document indexed without a value keeps the value the field holds. See Signal fields.
Example
{}
validationDoubleValidation
Sets allowed numeric bounds. Documents containing values outside these bounds are rejected.
Example
{
"min": 0,
"max": 1000
}
2 properties
minnumber
Lowest value accepted.
Format
double
maxnumber
Highest value accepted.
Format
double
unitstring
What the values are measured in: an ISO 4217 currency code such as SEK, a CLDR unit identifier such as kilogram or gigabyte, or any other text matched as written. A search in user mode reads a number typed next to the unit, or next to a comparative word such as under, as a filter on this field. Changing the unit does not require a reindex. See Reading numbers and units.
Example
"EUR"
TimestampFieldDefinitiontype: "timestamp"
Represents an instant in time formatted as an ISO 8601 date-time string with a timezone offset (for example, Z or +02:00). Timestamps are stored and compared at millisecond precision. Values representing the same instant are identical for filtering and sorting; search results return the original string format provided during ingestion. Documents containing timestamps without timezone offsets are rejected.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Enables value count aggregations. On numeric and timestamp fields, it also enables range buckets.
Example
{}
GeoPointFieldDefinitiontype: "geo_point"
Represents a geographic location defined by WGS 84 lat and lon coordinates. Locations are searched by distance rather than exact value: filter enables the distance matcher, and sort enables ordering by distance from an origin, nearest first.
Specifies a field role that applies a preset combination of usages. The role expands into explicit field properties before the definition is stored, and any property set alongside the role is preserved as given. Supported roles per type are listed under Field roles.
Marks the field as the unique document identifier. Documents with matching primary keys overwrite existing documents. An index can have at most one primary key. Primary key fields must be required and cannot be multiple, locale-specific, or wildcard fields.
Default
false
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field accepts multiple values in a single document. If false, the engine rejects documents containing multiple values for the field.
Default
false
storedboolean
When true, the engine stores field values to return in search results. This setting applies only when source is set to none, as documents are otherwise preserved in full.
Configures locale-specific field values so that analysis and collation follow the locale of each value. On an index that declares locales, configuring {} gives the field every declared locale, and only narrows the field to a subset of those locales.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Represents structured object values containing nested field definitions, referenced by dot notation (such as variants.price). An object field cannot configure filter, sort, facet, locales, or stored on itself. Child fields can be objects in turn, though a nested array cannot contain another nested array. An array of objects can specify a key to identify each object value. Object fields are returned in search results through the preserved document source; a stored child field below single objects also answers when the index keeps none. See object.
Example
{
"type": "object",
"multiple": true,
"mode": "nested",
"key": "sku",
"fields": {
"sku": {
"type": "string",
"required": true,
"filter": {}
},
"color": {
"type": "string",
"filter": {}
},
"price": {
"type": "double",
"filter": {}
}
}
}
primaryKeyboolean
Not supported on an object field; setting it is rejected.
requiredboolean
When true, the engine rejects documents that lack a value for this field.
Default
false
multipleboolean
When true, the field holds a list of object values, and mode is required. Single object fields are always indexed as flattened objects.
Default
false
storedboolean
Not supported on an object field; setting it is rejected.
Not supported on an object field; setting it is rejected.
Example
{
"defaultLocale": "sv",
"locales": [
"en",
"de"
]
}
4 properties
defaultLocalestring
Specifies the BCP-47 fallback locale for values that carry no explicit locale. On an index that declares locales, this property defaults to the defaultLocale of the index.
Example
"sv"
localesstring[]
Lists the supported locales for the field, in addition to the default locale. The engine rejects documents containing values with unlisted locales, and queries can target any listed locale. The engine rejects this property on an index that declares locales, which narrows a field with only instead. Reading an index definition back always returns this list on each field.
onlystring[]
Specifies the locales this field holds from the locales declared in index-level locales. If omitted, the field holds all declared locales. Every tag must be one the index declares, and the list must contain the default locale of the field. The engine expands this property into defaultLocale and locales before storing the index definition, so reading a definition back returns those properties instead.
fallbackFallback
Controls whether this field participates in the index's localeFallback. Only evaluated on an index that declares a fallback; setting enabled on an index without fallback configuration is rejected.
Not supported on an object field; setting it is rejected.
Example
{}
modeMode
Storage mode for multiple objects. Required when multiple is true (index:field:object:mode_required) and rejected when it is not (index:field:object:mode_without_multiple).
Values
"nested", "flattened"
keystring
Names a child field as the unique identifier for each object value in an array. Targets object values in update paths (such as variants[V-2]) and populates key on search value hits. Requires multiple: true (index:field:object:key_without_multiple). Must name a field defined in fields (index:field:object:key_unknown) that is required, not multiple, and of type string, int32, or int64 (index:field:object:key_invalid). Duplicate key values within a document are rejected with document:object_key_duplicate.
fieldsmap of FieldDefinition
Map of child field names to field definitions, the object type included - objects nest, though a nested array cannot contain another nested array (index:field:object:nested_in_nested). What a child field may configure follows from where it sits: sort and stored are rejected below a flattened array (index:field:object:flattened_sort_unsupported, index:field:object:flattened_stored_unsupported), and primaryKey is rejected inside any object (index:field:object:inner_usage_unsupported). Below a nested array stored and highlight work - highlighted fragments come back on value hits. locales works everywhere.
Definition of a field, structured as a tagged union where type selects the field type and the properties available on it. Field usages are opt-in: adding an empty configuration object enables a usage with engine defaults, and only explicitly configured properties are stored, preserving default values across engine updates. See Field types.
Tie-breaking rules and ranking signals. Omitted to order results by match score alone. Replaced entirely while an index has search settings.
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
resourcesResources
Shared resources referenced by name from fields, including named analysis chains, stopword lists, and synonym sets.
Example
{
"analyzers": {
"prose": {
"preset": "full_text"
}
},
"stopwords": {
"brands": [
"acme"
]
},
"synonyms": {
"cars": {
"rules": [
{
"equivalent": [
"car",
"automobile"
]
},
{
"mapping": {
"from": [
"ny"
],
"to": [
"new york"
]
}
}
]
}
}
}
3 properties
analyzersmap of AnalyzerDefinition
Named analysis chains, referenced from a field usage with "analyzer": { "named": "..." }. Presets are expanded the same way as on a field.
Specifies how the text of a usage is analyzed, with exactly one of preset, custom, or named. An analyzer chain describes the indexing process. The engine derives the query analyzer from the indexing chain. Components that select words by locale, such as stopwords and stemming, use the locale of the value being analyzed unless you specify a locale. See Analysis.
Example
{
"preset": "full_text"
}
3 properties
presetPreset
A preset specifies a predefined analyzer chain. The engine expands the preset before storing the index definition.
Values
"preserve_terms", "full_text"
customCustom
A custom analyzer chain that defines character filters, a tokenizer, and token filters.
Example
{
"charFilters": [
{
"htmlStrip": {}
}
],
"tokenizer": {
"icu": {}
},
"filters": [
{
"normalize": {}
},
{
"stemming": {
"locale": "sv"
}
}
]
}
3 properties
charFiltersCharFilter[]
An array of character filters applied to the raw text before tokenization, in order.
Example
{
"htmlStrip": {}
}
3 properties
htmlStripHtmlStrip
Strips HTML and XML markup and keeps text between tags.
Example
{}
mappingMappingCharFilter
Replaces occurrences of each key with its value.
Example
{
"mappings": {
"&": " and "
}
}
patternReplacePatternReplace
Replaces substrings that match a regular expression.
Example
{
"pattern": "\\s+",
"replacement": ""
}
tokenizerTokenizer
The tokenizer that splits text into tokens. If omitted, the engine chooses a tokenizer based on the locale of the value (Unicode segmentation for most locales; language-specific segmentation for Chinese, Japanese, and Korean).
Example
{
"icu": {}
}
4 properties
icuIcuTokenizer
Segments text based on Unicode rules. This is the default tokenizer.
Example
{}
whitespaceWhitespaceTokenizer
Splits text on whitespace characters.
Example
{}
keywordKeywordTokenizer
Retains the entire input value as a single token.
Example
{}
letterLetterTokenizer
Splits text on non-letter characters.
Example
{}
filtersTokenFilter[]
An array of token filters applied to tokens, in order.
Example
{
"normalize": {}
}
8 properties
normalizeNormalize
Applies Unicode normalization and case folding to make analysis case-insensitive.
Example
{
"caseFolding": true
}
stopwordsStopwordsFilter
Removes frequent words.
Example
{
"locale": "sv"
}
stemmingStemming
Reduces words to a shared root.
Example
{
"locale": "sv"
}
asciiFoldingAsciiFolding
Converts non-ASCII characters to ASCII equivalents.
Example
{
"preserveOriginal": true
}
edgeNgramEdgeNgram
Generates prefix n-grams for tokens within the specified character lengths.
Example
{
"minGram": 1,
"maxGram": 20
}
ngramNgram
Generates substring n-grams for tokens within the specified character lengths.
Example
{
"minGram": 3,
"maxGram": 5
}
synonymsSynonymsFilter
Expands tokens with synonyms from a synonym set defined in resources. Applied when a value is indexed, not when the text of a search is analyzed.
Example
{
"named": "cars"
}
decompoundDecompoundFilter
Splits compound words into parts and retains the original compound word. See Compound words. Applied at index time.
Example
{
"locale": "sv"
}
namedstring
A named chain references an analyzer defined under resources in the index definition. Used to share analyzer configurations across fields. Validation fails if the specified name does not exist under resources.
Example
"prose"
stopwordsmap of string[]
Named stopword lists, referenced from the stopwords component of an analyzer chain with "stopwords": { "named": "..." }.
1 property
<key>string[]
synonymsmap of Synonyms
Named synonym sets, referenced from the synonyms component of an analyzer chain with "synonyms": { "named": "..." }.
1 property
<key>Synonyms
Synonym rules applied during indexing. Modifying a synonym set applies only to documents indexed after the change.
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.
localesIndexLocales
Declares the locales that localized fields in the index support. A field opts in with "locales": {} to hold all declared locales, or narrows to fewer with "locales": { "only": [...] }. The engine expands the declaration onto each field before storing the index definition, so reading a definition back returns the locales on each field. If omitted, each field declares its own locales.
Example
{
"defaultLocale": "en",
"supported": [
"sv",
"de"
]
}
2 properties
defaultLocalestringrequired
Specifies the BCP-47 locale for values that carry no explicit locale. A field uses this value as its default locale unless the field defines its own defaultLocale. This property is required whenever an index declares locales.
Example
"en"
supportedstring[]
Lists additional BCP-47 locales that the index supports, in addition to defaultLocale. A field can narrow to a subset of these supported locales and the default locale by using only.
localeFallbackLocaleFallback
Configures how missing locale values in a document are populated from available locales during indexing. When omitted, missing locales remain empty, and searches in a locale find only documents translated into it.
Example
{
"chain": [
"da",
"en"
]
}
1 property
chainstring[]
Ordered list of locales to evaluate when populating a missing locale value. A field skips locales for which it has no value, allowing a single chain to serve fields with different configured locales. Specifying a locale not defined on any field in the index is rejected. When omitted, each field falls back to its defaultLocale.
statusIndexStatus
The observed state reported by the answering node. The API does not accept this object as input.
Example
{
"state": "usable",
"readOnly": false,
"indexer": {
"node": "node-a-7f21",
"address": "http://node-a:8080"
},
"luceneCompatibility": "current",
"luceneCreatedMajor": 10
}
6 properties
stateIndexState
The remote synchronization state as observed by the answering node: needs_pull (a newer remote state exists and has not been pulled yet), pulling (the node is fetching remote state), usable (the index is serving searches), modified (the index has local changes that are not yet pushed; only writer nodes reach this state), pushing (the node is pushing local changes), unsupported (the definition requires engine features not present on this node version), incompatible (the Lucene files are too old for this build to open), or closed (the index is closed on this node; a new request opens a fresh instance).
Indicates whether the answering node can modify the index. Only the node holding the index can modify it; other nodes serve searches from their local copy.
indexerIndexerInfo
Identifies the holder node and the address where writes are forwarded. Omitted if no node holds the index, if the holder could not be read, if the holder provided no address, or on nodes using local storage where readOnly already answers. Data in this field can lag behind a node handover by a few seconds.
Example
{
"node": "node-a-7f21",
"address": "http://node-a:8080"
}
2 properties
nodestring
The name the node competes under.
Example
"node-a-7f21"
addressstring
The target address for write forwarding. Omitted when the node did not set EXOFIND_NODE_ADDRESS.
Example
"http://node-a:8080"
luceneCompatibilityLuceneCompatibility
Indicates Lucene version compatibility. current: created by the current major version, and compatible with the current and next Lucene major versions. ending: readable by the current version, but unsupported by the next Lucene major version; reindex before upgrading across major versions. unreadable: too old to open; the index reports the incompatible state and requires reindexing. unknown: no version was recorded and no commit exists to determine the version, such as on an empty index.
Values
"unknown", "current", "ending", "unreadable"
luceneCreatedMajorinteger
The recorded Lucene major version the index was created with. Omitted when compatibility is unknown.
Format
int32
Example
10
settingsUnsupportedFeaturesstring[]
Lists the capabilities the index's search settings use that the answering node does not have. Present only when the node has set the settings aside and searches with the definition alone; upgrading the node puts them back in force.
A list of all generations for the index, ordered by name.
Example
{
"name": "2",
"live": true,
"createdAt": "2026-08-16T11:02:07Z"
}
3 properties
namestring
Name of the generation within its index, which is what follows the @ when addressing it as products@2.
Example
"2"
liveboolean
Whether the index answers from this generation. Exactly one generation of an index does, unless the index has just been created.
createdAtstring
When the generation was created, as an ISO 8601 timestamp. Omitted for a generation registered before this was recorded.
Example
"2026-08-16T11:02:07Z"
freshnessstring
A freshness token for the state the action landed in. Present on the answer to a commit and to a promotion, and omitted elsewhere. Pass it as freshness.atLeast on a search, and the search is answered only once the node holds the commit or answers from the promoted generation. Opaque; pass it back unchanged. See Freshness.
Example
"AQoIcHJvZHVjdHMSATIYBw"
400
The definition failed validation - the response details each problem - or the request asks for a reindex it cannot run.
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.
A list of objects declares no `mode`. Use `nested` when a search asks that conditions hold inside one value, `flattened` when the values are only structure.
The name in the path names a generation of an index that does not exist. Create the index first.
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.write 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.write` permission.
404
If-Match was sent for an index that does not exist, books@2 named an index that does not exist, or the key has no grant covering the name.
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 name belongs to no index, or the key holds no grant covering it.
409
The definition conflicts with documents stored in the generation (index:definition:incompatible), the stored definition contains settings this API version cannot represent (index:definition:unrepresentable), the index requires engine features this node does not have (index:unsupported), a reindex job is already running (reindex:in_progress), storage holds a generation under the new name that nothing deleted (index:generation:storage_held), no node is available to write the index (indexer:unavailable), or the registry write failed.
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 definition starts keeping a copy of each document, which the documents the generation holds were stored without. Carried inside `index:definition:incompatible`.
The definition changes the locale fallback that decided which locales were filled in for the documents the generation holds. Carried inside `index:definition:incompatible`.
412
The If-Match version does not match the stored definition. Re-read the index and rebuild the change against the new version.
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 `If-Match` version is not the one the stored definition is at. Read the index again and rebuild the change.
502
The index writer did not respond to the forwarded 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 request was forwarded to the index writer and the writer did not answer. Send it again.
503
The request raced the index being closed. Retrying the request reopens 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.
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.