OpenSearch/docs/reference/mapping/params/position-increment-gap.asciidoc

[[position-increment-gap]]
=== `position_increment_gap`

<<mapping-index,Analyzed>> text fields take term <<index-options,positions>>
into account, in order to be able to support
<<query-dsl-match-query-phrase,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:

[source,js]
--------------------------------------------------
PUT my_index/groups/1
{
    "names": [ "John Abraham", "Lincoln Smith"]
}

GET my_index/groups/_search
{
    "query": {
        "match_phrase": {
            "names": {
                "query": "Abraham Lincoln" <1>
            }
        }
    }
}

GET my_index/groups/_search
{
    "query": {
        "match_phrase": {
            "names": {
                "query": "Abraham Lincoln",
                "slop": 101 <2>
            }
        }
    }
}
--------------------------------------------------
// CONSOLE
<1> This phrase query doesn't match our document which is totally expected.
<2> 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:

[source,js]
--------------------------------------------------
PUT my_index
{
  "mappings": {
    "groups": {
      "properties": {
        "names": {
          "type": "text",
          "position_increment_gap": 0 <1>
        }
      }
    }
  }
}

PUT my_index/groups/1
{
    "names": [ "John Abraham", "Lincoln Smith"]
}

GET my_index/groups/_search
{
    "query": {
        "match_phrase": {
            "names": "Abraham Lincoln" <2>
        }
    }
}
--------------------------------------------------
// CONSOLE
<1> The first term in the next array element will be 0 terms apart from the
    last term in the previous array element.
<2> The phrase query matches our document which is weird, but its what we asked
    for in the mapping.

TIP: The `position_increment_gap` setting is allowed to have different settings
for fields of the same name in the same index.  Its value can be updated on
existing fields using the <<indices-put-mapping,PUT mapping API>>.