Search-as-you-type field type

A search-as-you-type field type provides search-as-you-type functionality using both prefix and infix completion.

Example

Mapping a search-as-you-type field creates n-gram subfields of this field, where n is in the range [2, max_shingle_size]. Additionally, it creates an index prefix subfield.

Create a mapping with a search-as-you-type field:

  1. PUT books
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "suggestions": {
  6.         "type": "search_as_you_type"
  7.       }
  8.     }
  9.   }
  10. }

copy

In addition to the suggestions field, this creates suggestions._2gram, suggestions._3gram, and suggestions._index_prefix fields.

Index a document with a search-as-you-type field:

  1. PUT books/_doc/1
  2. {
  3.   "suggestions": "one two three four"
  4. }

copy

To match terms in any order, use a bool_prefix or multi-match query. These queries rank the documents in which search terms are in the specified order higher than the documents in which terms are out of order.

  1. GET books/_search
  2. {
  3.   "query": {
  4.     "multi_match": {
  5.       "query": "tw one",
  6.       "type": "bool_prefix",
  7.       "fields": [
  8.         "suggestions",
  9.         "suggestions._2gram",
  10.         "suggestions._3gram"
  11.       ]
  12.     }
  13.   }
  14. }

copy

The response contains the matching document:

  1. {
  2.   "took" : 13,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 1,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "books",
  19.         "_type" : "_doc",
  20.         "_id" : "1",
  21.         "_score" : 1.0,
  22.         "_source" : {
  23.           "suggestions" : "one two three four"
  24.         }
  25.       }
  26.     ]
  27.   }
  28. }

To match terms in order, use a match_phrase_prefix query:

  1. GET books/_search
  2. {
  3.   "query": {
  4.     "match_phrase_prefix": {
  5.       "suggestions": "two th"
  6.     }
  7.   }
  8. }

copy

The response contains the matching document:

  1. {
  2.   "took" : 23,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 1,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 0.4793051,
  16.     "hits" : [
  17.       {
  18.         "_index" : "books",
  19.         "_type" : "_doc",
  20.         "_id" : "1",
  21.         "_score" : 0.4793051,
  22.         "_source" : {
  23.           "suggestions" : "one two three four"
  24.         }
  25.       }
  26.     ]
  27.   }
  28. }

To match the last terms exactly, use a match_phrase query:

  1. GET books/_search
  2. {
  3.   "query": {
  4.     "match_phrase": {
  5.       "suggestions": "four"
  6.     }
  7.   }
  8. }

copy

Response:

  1. {
  2.   "took" : 2,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 1,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 0.2876821,
  16.     "hits" : [
  17.       {
  18.         "_index" : "books",
  19.         "_type" : "_doc",
  20.         "_id" : "1",
  21.         "_score" : 0.2876821,
  22.         "_source" : {
  23.           "suggestions" : "one two three four"
  24.         }
  25.       }
  26.     ]
  27.   }
  28. }

Parameters

The following table lists the parameters accepted by search-as-you-type field types. All parameters are optional.

ParameterDescription
analyzerThe analyzer to be used for this field. By default, it will be used at index time and at search time. To override it at search time, set the search_analyzer parameter. Default is the standard analyzer, which uses grammar-based tokenization and is based on the Unicode Text Segmentation algorithm. Configures the root field and subfields.
indexA Boolean value that specifies whether the field should be searchable. Default is true. Configures the root field and subfields.
index_optionsSpecifies the information to be stored in the index for search and highlighting. Valid values: docs (doc number only), freqs (doc number and term frequencies), positions (doc number, term frequencies, and term positions), offsets (doc number, term frequencies, term positions, and start and end character offsets). Default is positions. Configures the root field and subfields.
max_shingle_sizeAn integer that specifies the maximum n-gram size. Valid values are in the range [2, 4]. N-grams to be created are in the range [2, max_shingle_size]. Default is 3, which creates a 2-gram and a 3-gram. Larger max_shingle_size values work better for more specific queries but lead to a larger index size.
normsA Boolean value that specifies whether the field length should be used when calculating relevance scores. Configures the root field and n-gram subfields (default is false). Does not configure the prefix subfield (in the prefix subfield, norms is false).
search_analyzerThe analyzer to be used at search time. Default is the analyzer specified in the analyzer parameter. Configures the root field and subfields.
search_quote_analyzerThe analyzer to be used at search time with phrases. Default is the analyzer specified in the analyzer parameter. Configures the root field and subfields.
similarityThe ranking algorithm for calculating relevance scores. Default is BM25. Configures the root field and subfields.
storeA Boolean value that specifies whether the field value should be stored and can be retrieved separately from the _source field. Default is false. Configures the root field only.
term_vectorA Boolean value that specifies whether a term vector for this field should be stored. Default is no. Configures the root field and n-gram subfields. Does not configure the prefix subfield.