You're viewing version 3.0 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Position increment gap

The position_increment_gap mapping parameter defines the positional distance between tokens of multi-valued fields during indexing. This affects how match_phrase and span queries behave when searching across multiple values of the same field.

By default, each new value in a multi-valued field is treated as if it is separated from the previous one by a gap of 100 positions. This helps prevent false positives when searching for phrases that may span across different field values.

Setting a position increment gap

Use the following request to create an index named articles with a tags field of type text, setting position_increment_gap to 0:

PUT /articles
{
  "mappings": {
    "properties": {
      "tags": {
        "type": "text",
        "position_increment_gap": 0
      }
    }
  }
}

Indexing a multi-valued field

Use the following request to index a document in which the tags field contains multiple values:

PUT /articles/_doc/1
{
  "tags": ["machine", "learning"]
}

Search using a match_phrase query

Use the following match_phrase query to search for “machine learning” in the tags field:

GET /articles/_search
{
  "query": {
    "match_phrase": {
      "tags": "machine learning"
    }
  }
}

The result demonstrates that the phrase match succeeds because the position_increment_gap is set to 0, allowing tokens from separate values to be treated as adjacent:

{
  ...
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.5753642,
    "hits": [
      {
        "_index": "articles",
        "_id": "1",
        "_score": 0.5753642,
        "_source": {
          "tags": [
            "machine",
            "learning"
          ]
        }
      }
    ]
  }
}

If the position_increment_gap remained at 100, no hits would be returned because tokens machine and learning would be considered to be 100 positions away from each other.