position_increment_gap

Analyzed text fields take term positions into account, in order to be able to support proximity or phrase queries. When indexing text fields with multiple values a “fake” gap is added between the values to prevent most phrase queries from matching across the values. The size of this gap is configured using position_increment_gap and defaults to 100.

For example:

  1. PUT my-index-000001/_doc/1
  2. {
  3.   "names": [ "John Abraham", "Lincoln Smith"]
  4. }
  6. GET my-index-000001/_search
  7. {
  8.   "query": {
  9.     "match_phrase": {
  10.       "names": {
  11.         "query": "Abraham Lincoln" 
  12.       }
  13.     }
  14.   }
  15. }
  17. GET my-index-000001/_search
  18. {
  19.   "query": {
  20.     "match_phrase": {
  21.       "names": {
  22.         "query": "Abraham Lincoln",
  23.         "slop": 101 
  24.       }
  25.     }
  26.   }
  27. }

This phrase query doesn’t match our document which is totally expected.

This phrase query matches our document, even though Abraham and Lincoln are in separate strings, because slop > position_increment_gap.

The position_increment_gap can be specified in the mapping. For instance:

  1. PUT my-index-000001
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "names": {
  6.         "type": "text",
  7.         "position_increment_gap": 0 
  8.       }
  9.     }
  10.   }
  11. }
  13. PUT my-index-000001/_doc/1
  14. {
  15.   "names": [ "John Abraham", "Lincoln Smith"]
  16. }
  18. GET my-index-000001/_search
  19. {
  20.   "query": {
  21.     "match_phrase": {
  22.       "names": "Abraham Lincoln" 
  23.     }
  24.   }
  25. }

The first term in the next array element will be 0 terms apart from the last term in the previous array element.

The phrase query matches our document which is weird, but its what we asked for in the mapping.