Merge pull request #13226 from nik9000/docs_position_increment_gap

[docs] Fix docs for position_increment_gap

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

@@ -4,12 +4,12 @@
 <<mapping-index,Analyzed>> string 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 an array of strings, each string of the array is indexed
-directly after the previous one, almost as though all the strings in the array
-had been concatenated into one big string.
+When indexing string 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`.
 
-This can result in matches from phrase queries spanning two array elements.
-For instance:
+For example:
 
 [source,js]
 --------------------------------------------------
@@ -26,11 +26,24 @@ GET /my_index/groups/_search
         }
     }
 }
+
+GET /my_index/groups/_search
+{
+    "query": {
+        "match_phrase": {
+            "names": "Abraham Lincoln",
+            "slop": 101 <2>
+        }
+    }
+}
 --------------------------------------------------
 // AUTOSENSE
-<1> This phrase query matches our document, even though `Abraham` and `Lincoln` are in separate strings.
+<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 introduce a fake gap between each array element.  For instance:
+
+The `position_increment_gap` can be specified in the mapping.  For instance:
 
 [source,js]
 --------------------------------------------------
@@ -41,7 +54,7 @@ PUT my_index
       "properties": {
         "names": {
           "type": "string",
-          "position_increment_gap": 50 <1>
+          "position_increment_gap": 0 <1>
         }
       }
     }
@@ -63,11 +76,11 @@ GET /my_index/groups/_search
 }
 --------------------------------------------------
 // AUTOSENSE
-<1> The first term in the next array element will be 50 terms apart from the
+<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 no longer matches our document.
+<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>>.
-