From 976922c2ff4d4b3d4f113546b9fc99837f6625e6 Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Mon, 5 Aug 2019 11:13:39 -0400
Subject: [PATCH 1/2] [DOCS] Reformat match phrase query

---
 docs/reference/analysis.asciidoc              |  2 +
 .../query-dsl/match-phrase-query.asciidoc     | 74 +++++++++++++------
 2 files changed, 54 insertions(+), 22 deletions(-)

diff --git a/docs/reference/analysis.asciidoc b/docs/reference/analysis.asciidoc
index 0a3240df091da..dd283d971c3f7 100644
--- a/docs/reference/analysis.asciidoc
+++ b/docs/reference/analysis.asciidoc
@@ -32,6 +32,8 @@ to the inverted index:
 ------
 
 [float]
+[[specify-index-time-analyzer]]
+
 === Specifying an index time analyzer
 
 Each <<text,`text`>> field in a mapping can specify its own
diff --git a/docs/reference/query-dsl/match-phrase-query.asciidoc b/docs/reference/query-dsl/match-phrase-query.asciidoc
index ed847c419af60..482485f562953 100644
--- a/docs/reference/query-dsl/match-phrase-query.asciidoc
+++ b/docs/reference/query-dsl/match-phrase-query.asciidoc
@@ -3,29 +3,21 @@
 ++++
 <titleabbrev>Match phrase</titleabbrev>
 ++++
+Returns documents that contain all words of a provided text, in the **same
+order** as provided.
 
-The `match_phrase` query analyzes the text and creates a `phrase` query
-out of the analyzed text. For example:
+You can use the `match_phrase` query when it's important to find a complete
+phrase or words near each other.
 
-[source,js]
---------------------------------------------------
-GET /_search
-{
-    "query": {
-        "match_phrase" : {
-            "message" : "this is a test"
-        }
-    }
-}
---------------------------------------------------
-// CONSOLE
 
-A phrase query matches terms up to a configurable `slop`
-(which defaults to 0) in any order. Transposed terms have a slop of 2.
+[[match-phrase-query-ex-request]]
+==== Example request
+
+The following `match_phrase` search returns documents containing `brown fox` in
+the `message` field.
 
-The `analyzer` can be set to control which analyzer will perform the
-analysis process on the text. It defaults to the field explicit mapping
-definition, or the default search analyzer, for example:
+This search would match a `message` value of `quick brown fox` but not `the fox
+is brown`.
 
 [source,js]
 --------------------------------------------------
@@ -34,8 +26,7 @@ GET /_search
     "query": {
         "match_phrase" : {
             "message" : {
-                "query" : "this is a test",
-                "analyzer" : "my_analyzer"
+                "query" : "brown fox"
             }
         }
     }
@@ -43,4 +34,43 @@ GET /_search
 --------------------------------------------------
 // CONSOLE
 
-This query also accepts `zero_terms_query`, as explained in <<query-dsl-match-query, `match` query>>.
+
+[[match-phrase-top-level-params]]
+==== Top-level parameters for `match_phrase`
+`<field>`::
+(Required, object) Field you wish to search.
+
+[[match-field-params]]
+==== Parameters for `<field>`
+`query`::
++
+--
+(Required, string) Text you wish to find in the provided `<field>`.
+
+The `match_phrase` query <<analysis,analyzes>> any provided text into tokens
+before performing a search.
+--
+
+`analyzer`::
+(Optional, string) <<analysis,Analyzer>> used to convert text in the `query`
+value into tokens. Defaults to the <<specify-index-time-analyzer,index-time
+analyzer>> mapped for the `<field>`. If no analyzer is mapped, the index's
+default analyzer is used.
+
+`slop`::
+(Optional, integer) Maximum number of positions allowed between matching tokens.
+Defaults to `0`. Transposed terms have a slop of `2`.
+
+`zero_terms_query`::
++
+--
+(Optional, string) Indicates whether no documents are returned if the `analyzer`
+removes all tokens, such as when using a `stop` filter. Valid values are:
+
+ `none` (Default)::
+No documents are returned if the `analyzer` removes all tokens.
+
+ `all`::
+Returns all documents, similar to a <<query-dsl-match-all-query,`match_all`>>
+query.
+--

From 5369db17c3e720ce65eba9e7a2e237b5cca4e2a4 Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Mon, 5 Aug 2019 11:57:29 -0400
Subject: [PATCH 2/2] Correct anchor

---
 docs/reference/query-dsl/match-phrase-query.asciidoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/reference/query-dsl/match-phrase-query.asciidoc b/docs/reference/query-dsl/match-phrase-query.asciidoc
index 482485f562953..e464ab6db0eea 100644
--- a/docs/reference/query-dsl/match-phrase-query.asciidoc
+++ b/docs/reference/query-dsl/match-phrase-query.asciidoc
@@ -40,7 +40,7 @@ GET /_search
 `<field>`::
 (Required, object) Field you wish to search.
 
-[[match-field-params]]
+[[match-phrase-field-params]]
 ==== Parameters for `<field>`
 `query`::
 +