=== Multivalue Fields A curious thing can happen when you try to use phrase matching on multivalue fields. ((("proximity matching", "on multivalue fields")))((("match_phrase query", "on multivalue fields"))) Imagine that you index this document: [source,js] -------------------------------------------------- PUT /my_index/groups/1 { "names": [ "John Abraham", "Lincoln Smith"] } -------------------------------------------------- // SENSE: 120_Proximity_Matching/15_Multi_value_fields.json Then run a phrase query for `Abraham Lincoln`: [source,js] -------------------------------------------------- GET /my_index/groups/_search { "query": { "match_phrase": { "names": "Abraham Lincoln" } } } -------------------------------------------------- // SENSE: 120_Proximity_Matching/15_Multi_value_fields.json Surprisingly, our document matches, even though `Abraham` and `Lincoln` belong to two different people in the `names` array. The reason for this comes down to the way arrays are indexed in Elasticsearch. When `John Abraham` is analyzed, it produces this: * Position 1: `john` * Position 2: `abraham` Then when `Lincoln Smith` is analyzed, it produces this: * Position 3: `lincoln` * Position 4: `smith` In other words, Elasticsearch produces exactly the same list of tokens as it would have for the single string `John Abraham Lincoln Smith`. Our example query looks for `abraham` directly followed by `lincoln`, and these two terms do indeed exist, and they are right next to each other, so the query matches. Fortunately, there is a simple workaround for cases like these, called the `position_offset_gap`, which((("mapping (types)", "position_offset_gap")))((("position_offset_gap"))) we need to configure in the field mapping: [source,js] -------------------------------------------------- DELETE /my_index/groups/ <1> PUT /my_index/_mapping/groups <2> { "properties": { "names": { "type": "string", "position_offset_gap": 100 } } } -------------------------------------------------- // SENSE: 120_Proximity_Matching/15_Multi_value_fields.json <1> First delete the `groups` mapping and all documents of that type. <2> Then create a new `groups` mapping with the correct values. The `position_offset_gap` setting tells Elasticsearch that it should increase the current term `position` by the specified value for every new array element. So now, when we index the array of names, the terms are emitted with the following positions: * Position 1: `john` * Position 2: `abraham` * Position 103: `lincoln` * Position 104: `smith` Our phrase query would no longer match a document like this because `abraham` and `lincoln` are now 100 positions apart. You would have to add a `slop` value of 100 in order for this document to match.