Completion field type
Introduced 1.0
A completion field type provides autocomplete functionality through a completion suggester. The completion suggester is a prefix suggester, so it matches the beginning of text only. A completion suggester creates an in-memory data structure, which provides faster lookups but leads to increased memory usage. You need to upload a list of all possible completions into the index before using this feature.
Example
Create a mapping with a completion field:
PUT chess_store
{
"mappings": {
"properties": {
"suggestions": {
"type": "completion"
},
"product": {
"type": "keyword"
}
}
}
}
Mapping parameters
The completion field type supports the following mapping parameters.
| Parameter | Description |
|---|---|
analyzer | Specifies the index-time analyzer for input text. Default is simple. See Index analyzers. |
search_analyzer | Defines the analyzer used at search time. Default is the value of analyzer. See Search analyzers. |
preserve_separators | If true (default), preserves separators such as spaces or punctuation. If set to false, allows queries like queensg to match a suggestion like “Queen’s Gambit”. |
preserve_position_increments | If true (default), maintains position increments for analyzed tokens. Setting this to false can match suggestions like “The Sicilian Defense” when typing s because it skips over stopwords like “The”. Alternatively, you can index both “Sicilian Defense” and “The Sicilian Defense” as separate inputs without changing the analyzer. |
max_input_length | Limits the length of each input string. Default is 50 UTF-16 code points. This applies only at index time to prevent large inputs from bloating the underlying data structure. Most prefix completions work well within this limit. |
Example mapping
PUT chess_store
{
"mappings": {
"properties": {
"suggestions": {
"type": "completion",
"analyzer": "standard"
},
"product": {
"type": "keyword"
}
}
}
}
Index suggestions into OpenSearch:
PUT chess_store/_doc/1
{
"suggestions": {
"input": ["Books on openings", "Books on endgames"],
"weight" : 10
}
}
Parameters
The following table lists the parameters accepted by completion fields.
| Parameter | Description |
|---|---|
input | A list of possible completions as a string or array of strings. Cannot contain \u0000 (null), \u001f (information separator one), or \u001e (information separator two). Required. |
weight | A positive integer or a positive integer string for ranking suggestions. Optional. |
Multiple suggestions can be indexed as follows:
PUT chess_store/_doc/2
{
"suggestions": [
{
"input": "Chess set",
"weight": 20
},
{
"input": "Chess pieces",
"weight": 10
},
{
"input": "Chess board",
"weight": 5
}
]
}
As an alternative, you can use the following shorthand notation (note that you cannot provide the weight parameter in this notation):
PUT chess_store/_doc/3
{
"suggestions" : [ "Chess clock", "Chess timer" ]
}
Querying completion field types
To query completion field types, specify the prefix that you want to search for and the name of the field in which to look for suggestions.
Query the index for suggestions that start with the word “chess”:
GET chess_store/_search
{
"suggest": {
"product-suggestions": {
"prefix": "chess",
"completion": {
"field": "suggestions"
}
}
}
}
The response contains autocomplete suggestions:
{
"took" : 3,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 0,
"relation" : "eq"
},
"max_score" : null,
"hits" : [ ]
},
"suggest" : {
"product-suggestions" : [
{
"text" : "chess",
"offset" : 0,
"length" : 5,
"options" : [
{
"text" : "Chess set",
"_index" : "chess_store",
"_type" : "_doc",
"_id" : "2",
"_score" : 20.0,
"_source" : {
"suggestions" : [
{
"input" : "Chess set",
"weight" : 20
},
{
"input" : "Chess pieces",
"weight" : 10
},
{
"input" : "Chess board",
"weight" : 5
}
]
}
},
{
"text" : "Chess clock",
"_index" : "chess_store",
"_type" : "_doc",
"_id" : "3",
"_score" : 1.0,
"_source" : {
"suggestions" : [
"Chess clock",
"Chess timer"
]
}
}
]
}
]
}
}
In the response, the _score field contains the value of the weight parameter that was set up at index time. The text field is populated with the suggestion’s input parameter.
By default, the response contains the whole document, including the _source field, which may impact performance. To return only the suggestions field, you can specify that in the _source parameter. You can also restrict the number of returned suggestions by specifying the size parameter.
GET chess_store/_search
{
"_source": "suggestions",
"suggest": {
"product-suggestions": {
"prefix": "chess",
"completion": {
"field": "suggestions",
"size" : 3
}
}
}
}
The response contains the suggestions:
{
"took" : 5,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 0,
"relation" : "eq"
},
"max_score" : null,
"hits" : [ ]
},
"suggest" : {
"product-suggestions" : [
{
"text" : "chess",
"offset" : 0,
"length" : 5,
"options" : [
{
"text" : "Chess set",
"_index" : "chess_store",
"_type" : "_doc",
"_id" : "2",
"_score" : 20.0,
"_source" : {
"suggestions" : [
{
"input" : "Chess set",
"weight" : 20
},
{
"input" : "Chess pieces",
"weight" : 10
},
{
"input" : "Chess board",
"weight" : 5
}
]
}
},
{
"text" : "Chess clock",
"_index" : "chess_store",
"_type" : "_doc",
"_id" : "3",
"_score" : 1.0,
"_source" : {
"suggestions" : [
"Chess clock",
"Chess timer"
]
}
}
]
}
]
}
}
To take advantage of source filtering, use the suggest functionality on the _search endpoint. The _suggest endpoint does not support source filtering.
Completion query parameters
The following table lists the parameters accepted by the completion suggester query.
| Parameter | Description |
|---|---|
field | A string that specifies the field on which to run the query. Required. |
size | An integer that specifies the maximum number of returned suggestions. Optional. Default is 5. |
skip_duplicates | A Boolean value that specifies whether to skip duplicate suggestions. Optional. Default is false. |
Fuzzy completion query
To allow for fuzzy matching, you can specify the fuzziness parameter for the completion query. In this case, even if the user mistypes a search term, the completion query still returns results. Additionally, the longer the prefix that matches the query, the higher the document’s score.
GET chess_store/_search
{
"suggest": {
"product-suggestions": {
"prefix": "chesc",
"completion": {
"field": "suggestions",
"size" : 3,
"fuzzy" : {
"fuzziness" : "AUTO"
}
}
}
}
}
To use all default fuzziness options, specify "fuzzy": {} or "fuzzy": true.
The following table lists the parameters accepted by the fuzzy completion suggester query. All of the parameters are optional.
| Parameter | Description |
|---|---|
fuzziness | Fuzziness can be set as one of the following: 1. An integer that specifies the maximum allowed Damerau–Levenshtein distance for this edit. 2. AUTO: Strings of 0–2 characters must match exactly, strings of 3–5 characters allow 1 edit, and strings longer than 5 characters allow 2 edits.Default is AUTO. |
min_length | An integer that specifies the minimum length the input must be to start returning suggestions. If the search term is shorter than min_length, no suggestions are returned. Default is 3. |
prefix_length | An integer that specifies the minimum length the matched prefix must be to start returning suggestions. If the prefix of prefix_length is not matched, but the search term is still within the Damerau–Levenshtein distance, no suggestions are returned. Default is 1. |
transpositions | A Boolean value that specifies to count transpositions (interchanges of adjacent characters) as one edit instead of two. Example: The suggestion’s input parameter is abcde and the fuzziness is 1. If transpositions is set to true, abdce will match, but if transpositions is set to false, abdce will not match. Default is true. |
unicode_aware | A Boolean value that specifies whether to use Unicode code points when measuring the edit distance, transposition, and length. If unicode_aware is set to true, the measurement is slower. Default is false, in which case distances are measured in bytes. |
Regex queries
You can use a regular expression to define the prefix for the completion suggester query.
For example, to search for strings that start with “a” and have a “d” later on, use the following query:
GET chess_store/_search
{
"suggest": {
"product-suggestions": {
"regex": "a.*d",
"completion": {
"field": "suggestions"
}
}
}
}
The response matches the string “abcde”:
{
"took" : 2,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 0,
"relation" : "eq"
},
"max_score" : null,
"hits" : [ ]
},
"suggest" : {
"product-suggestions" : [
{
"text" : "a.*d",
"offset" : 0,
"length" : 4,
"options" : [
{
"text" : "abcde",
"_index" : "chess_store",
"_type" : "_doc",
"_id" : "2",
"_score" : 20.0,
"_source" : {
"suggestions" : [
{
"input" : "abcde",
"weight" : 20
}
]
}
}
]
}
]
}
}