Added cautionary note to match_phrase_prefix explaining its shortcomings

Closes #17655

2 files changed, 31 insertions, 7 deletions

diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc
index 6ec108ae46..9b99b56997 100644
--- a/docs/reference/index.asciidoc
+++ b/docs/reference/index.asciidoc
@@ -5,7 +5,7 @@
 :major-version: 5.x
 :branch:        master
 :jdk:           1.8.0_73
-:defguide:      https://www.elastic.co/guide/en/elasticsearch/guide/current
+:defguide:      https://www.elastic.co/guide/en/elasticsearch/guide/master
 :plugins:       https://www.elastic.co/guide/en/elasticsearch/plugins/master
 :javaclient:    https://www.elastic.co/guide/en/elasticsearch/client/java-api/master/
 :issue:         https://github.com/elastic/elasticsearch/issues/
diff --git a/docs/reference/query-dsl/match-phrase-prefix-query.asciidoc b/docs/reference/query-dsl/match-phrase-prefix-query.asciidoc
index 7e5a75dd17..b715bf8bd6 100644
--- a/docs/reference/query-dsl/match-phrase-prefix-query.asciidoc
+++ b/docs/reference/query-dsl/match-phrase-prefix-query.asciidoc
@@ -8,25 +8,49 @@ allows for prefix matches on the last term in the text. For example:
 --------------------------------------------------
 {
     "match_phrase_prefix" : {
-        "message" : "this is a test"
+        "message" : "quick brown f"
     }
 }
 --------------------------------------------------
 
 It accepts the same parameters as the phrase type. In addition, it also
-accepts a `max_expansions` parameter that can control to how many
-prefixes the last term will be expanded. It is highly recommended to set
-it to an acceptable value to control the execution time of the query.
-For example:
+accepts a `max_expansions` parameter (default `50`) that can control to how
+many prefixes the last term will be expanded. It is highly recommended to set
+it to an acceptable value to control the execution time of the query. For
+example:
 
 [source,js]
 --------------------------------------------------
 {
     "match_phrase_prefix" : {
         "message" : {
-            "query" : "this is a test",
+            "query" : "quick brown f",
             "max_expansions" : 10
         }
     }
 }
 --------------------------------------------------
+
+[IMPORTANT]
+===================================================
+
+The `match_phrase_prefix` query is a poor-man's autocomplete.  It is very easy
+to use, which let's you get started quickly with _search-as-you-type_ but it's
+results, which usually are good enough,  can sometimes be confusing.
+
+Consider the query string `quick brown f`.  This query works by creating a
+phrase query out of `quick` and `brown` (i.e. the term `quick` must exist and
+must be followed by the term `brown`).  Then it looks at the sorted term
+dictionary to find the first 50 terms that begin with `f`, and
+adds these terms to the phrase query.
+
+The problem is that the first 50 terms may not include the term `fox` so the
+phase `quick brown fox` will not be found.  This usually isn't a problem as
+the user will continue to type more letters until the word they are looking
+for appears.
+
+For better solutions for _search-as-you-type_ see the
+<<search-suggesters-completion,completion suggester>> and
+{guide}/_index_time_search_as_you_type.html[Index-Time Search-as-You-Type].
+
+===================================================
\ No newline at end of file