Deprecate _suggest endpoint in favour of _search (#20305)

* Replace _suggest endpoint to _search in docs In 5.0, the _suggest endpoint is just sugar for _search with suggestions specified. Users should move away from using the _suggest endpoint, as it is marked as deprecated in 5.x and will be removed in 6.0 * update docs to use _search endpoint instead of _suggest * Add deprecation logging to RestSuggestAction * Use search endpoint instead of suggest endpoint in rest tests
2016-12-14 21:49:53 -05:00 · 2016-12-14 21:49:53 -05:00 · cdd5fbe3a1
parent eaf82a6e7e
commit cdd5fbe3a1
11 changed files with 762 additions and 381 deletions
--- a/core/src/main/java/org/elasticsearch/rest/action/search/RestSuggestAction.java
+++ b/core/src/main/java/org/elasticsearch/rest/action/search/RestSuggestAction.java
@ -56,10 +56,14 @@ public class RestSuggestAction extends BaseRestHandler {
                             SearchRequestParsers searchRequestParsers) {
        super(settings);
        this.searchRequestParsers = searchRequestParsers;
-        controller.registerHandler(POST, "/_suggest", this);
-        controller.registerHandler(GET, "/_suggest", this);
-        controller.registerHandler(POST, "/{index}/_suggest", this);
-        controller.registerHandler(GET, "/{index}/_suggest", this);
+        controller.registerAsDeprecatedHandler(POST, "/_suggest", this,
+                "[POST /_suggest] is deprecated! Use [POST /_search] instead.", deprecationLogger);
+        controller.registerAsDeprecatedHandler(GET, "/_suggest", this,
+                "[GET /_suggest] is deprecated! Use [GET /_search] instead.", deprecationLogger);
+        controller.registerAsDeprecatedHandler(POST, "/{index}/_suggest", this,
+                "[POST /{index}/_suggest] is deprecated! Use [POST /{index}/_search] instead.", deprecationLogger);
+        controller.registerAsDeprecatedHandler(GET, "/{index}/_suggest", this,
+                "[GET /{index}/_suggest] is deprecated! Use [GET /{index}/_search] instead.", deprecationLogger);
    }

    @Override
--- a/docs/reference/search/suggesters.asciidoc
+++ b/docs/reference/search/suggesters.asciidoc
@ -5,8 +5,12 @@ The suggest feature suggests similar looking terms based on a provided
 text by using a suggester. Parts of the suggest feature are still under
 development.

-The suggest request part is either defined alongside the query part in a
-`_search` request or via the REST `_suggest` endpoint.
+The suggest request part is defined alongside the query part in a `_search`
+request.
+
+NOTE: `_suggest` endpoint has been deprecated in favour of using suggest via
+`_search` endpoint. In 5.0, the `_search` endpoint has been optimized for
+suggest only search requests.

 [source,js]
 --------------------------------------------------
@ -30,25 +34,6 @@ POST twitter/_search
 // CONSOLE
 // TEST[setup:twitter]

-Suggest requests executed against the `_suggest` endpoint should omit
-the surrounding `suggest` element which is only used if the suggest
-request is part of a search.
-
-[source,js]
--------------------------------------------------
-POST _suggest
-{
-  "my-suggestion" : {
-    "text" : "tring out Elasticsearch",
-    "term" : {
-      "field" : "message"
-    }
-  }
-}
--------------------------------------------------
-// CONSOLE
-// TEST[setup:twitter]
-
 Several suggestions can be specified per request. Each suggestion is
 identified with an arbitrary name. In the example below two suggestions
 are requested. Both `my-suggest-1` and `my-suggest-2` suggestions use
@ -56,18 +41,20 @@ the `term` suggester, but have a different `text`.

 [source,js]
 --------------------------------------------------
-POST _suggest
+POST _search
 {
-  "my-suggest-1" : {
-    "text" : "tring out Elasticsearch",
-    "term" : {
-      "field" : "message"
-    }
-  },
-  "my-suggest-2" : {
-    "text" : "kmichy",
-    "term" : {
-      "field" : "user"
+  "suggest": {
+    "my-suggest-1" : {
+      "text" : "tring out Elasticsearch",
+      "term" : {
+        "field" : "message"
+      }
+    },
+    "my-suggest-2" : {
+      "text" : "kmichy",
+      "term" : {
+        "field" : "user"
+      }
    }
  }
 }
@ -85,27 +72,34 @@ in the suggest text and if found an arbitrary number of options.
 --------------------------------------------------
 {
  "_shards": ...
-  "my-suggest-1": [ {
-    "text": "tring",
-    "offset": 0,
-    "length": 5,
-    "options": [ {"text": "trying", "score": 0.8, "freq": 1 } ]
-  }, {
-    "text": "out",
-    "offset": 6,
-    "length": 3,
-    "options": []
-  }, {
-    "text": "elasticsearch",
-    "offset": 10,
-    "length": 13,
-    "options": []
-  } ],
-  "my-suggest-2": ...
+  "hits": ...
+  "took": 2,
+  "timed_out": false,
+  "suggest": {
+    "my-suggest-1": [ {
+      "text": "tring",
+      "offset": 0,
+      "length": 5,
+      "options": [ {"text": "trying", "score": 0.8, "freq": 1 } ]
+    }, {
+      "text": "out",
+      "offset": 6,
+      "length": 3,
+      "options": []
+    }, {
+      "text": "elasticsearch",
+      "offset": 10,
+      "length": 13,
+      "options": []
+    } ],
+    "my-suggest-2": ...
+  }
 }
 --------------------------------------------------
 // TESTRESPONSE[s/"_shards": \.\.\./"_shards": "$body._shards",/]
-// TESTRESPONSE[s/"my-suggest-2": \.\.\./"my-suggest-2": "$body.my-suggest-2"/]
+// TESTRESPONSE[s/"hits": .../"hits": "$body.hits",/]
+// TESTRESPONSE[s/"took": 2,/"took": "$body.took",/]
+// TESTRESPONSE[s/"my-suggest-2": \.\.\./"my-suggest-2": "$body.suggest.my-suggest-2"/]


 Each options array contains an option object that includes the
@ -123,17 +117,19 @@ and applies to the `my-suggest-1` and `my-suggest-2` suggestions.

 [source,js]
 --------------------------------------------------
-POST _suggest
+POST _search
 {
-  "text" : "tring out Elasticsearch",
-  "my-suggest-1" : {
-    "term" : {
-      "field" : "message"
-    }
-  },
-  "my-suggest-2" : {
-    "term" : {
-      "field" : "user"
+  "suggest": {
+    "text" : "tring out Elasticsearch",
+    "my-suggest-1" : {
+      "term" : {
+        "field" : "message"
+      }
+    },
+    "my-suggest-2" : {
+       "term" : {
+        "field" : "user"
+       }
    }
  }
 }
--- a/docs/reference/search/suggesters/completion-suggest.asciidoc
+++ b/docs/reference/search/suggesters/completion-suggest.asciidoc
@ -152,12 +152,14 @@ documents once deleted are never shown. This request:

 [source,js]
 --------------------------------------------------
-POST music/_suggest?pretty
+POST music/_search?pretty
 {
-    "song-suggest" : {
-        "prefix" : "nir",
-        "completion" : {
-            "field" : "suggest"
+    "suggest": {
+        "song-suggest" : {
+            "prefix" : "nir",
+            "completion" : {
+                "field" : "suggest"
+            }
        }
    }
 }
@ -175,24 +177,30 @@ returns this response:
    "successful" : 5,
    "failed" : 0
  },
-  "song-suggest" : [ {
-    "text" : "nir",
-    "offset" : 0,
-    "length" : 3,
-    "options" : [ {
-      "text" : "Nirvana",
-      "_index": "music",
-      "_type": "song",
-      "_id": "1",
-      "_score": 1.0,
-      "_source": {
-        "suggest": ["Nevermind", "Nirvana"]
-      }
+  "hits": ...
+  "took": 2,
+  "timed_out": false,
+  "suggest": {
+    "song-suggest" : [ {
+      "text" : "nir",
+      "offset" : 0,
+      "length" : 3,
+      "options" : [ {
+        "text" : "Nirvana",
+        "_index": "music",
+        "_type": "song",
+        "_id": "1",
+        "_score": 1.0,
+        "_source": {
+          "suggest": ["Nevermind", "Nirvana"]
+        }
+      } ]
    } ]
-  } ]
+  }
 }
 --------------------------------------------------
-// TESTRESPONSE
+// TESTRESPONSE[s/"hits": .../"hits": "$body.hits",/]
+// TESTRESPONSE[s/"took": 2,/"took": "$body.took",/]


 IMPORTANT: `_source` meta-field must be enabled, which is the default
@ -289,14 +297,16 @@ you can have a typo in your search and still get results back.

 [source,js]
 --------------------------------------------------
-POST music/_suggest?pretty
+POST music/_search?pretty
 {
-    "song-suggest" : {
-        "prefix" : "nor",
-        "completion" : {
-            "field" : "suggest",
-            "fuzzy" : {
-                "fuzziness" : 2
+    "suggest": {
+        "song-suggest" : {
+            "prefix" : "nor",
+            "completion" : {
+                "field" : "suggest",
+                "fuzzy" : {
+                    "fuzziness" : 2
+                }
            }
        }
    }
@ -346,12 +356,14 @@ you can express a prefix as a regular expression

 [source,js]
 --------------------------------------------------
-POST music/_suggest?pretty
+POST music/_search?pretty
 {
-    "song-suggest" : {
-        "regex" : "n[ever|i]r",
-        "completion" : {
-            "field" : "suggest"
+    "suggest": {
+        "song-suggest" : {
+            "regex" : "n[ever|i]r",
+            "completion" : {
+                "field" : "suggest"
+            }
        }
    }
 }
--- a/docs/reference/search/suggesters/context-suggest.asciidoc
+++ b/docs/reference/search/suggesters/context-suggest.asciidoc
@ -138,15 +138,17 @@ filters suggestions by multiple categories:

 [source,js]
 --------------------------------------------------
-POST place/_suggest?pretty
+POST place/_search?pretty
 {
-    "suggest" : {
-        "prefix" : "tim",
-        "completion" : {
-            "field" : "suggest",
-            "size": 10,
-            "contexts": {
-                "place_type": [ "cafe", "restaurants" ]
+    "suggest": {
+        "place_suggestion" : {
+            "prefix" : "tim",
+            "completion" : {
+                "field" : "suggest",
+                "size": 10,
+                "contexts": {
+                    "place_type": [ "cafe", "restaurants" ]
+                }
            }
        }
    }
@ -165,18 +167,20 @@ suggestions associated with some categories:

 [source,js]
 --------------------------------------------------
-POST place/_suggest?pretty
+POST place/_search?pretty
 {
-    "suggest" : {
-        "prefix" : "tim",
-        "completion" : {
-            "field" : "suggest",
-            "size": 10,
-            "contexts": {
-                "place_type": [ <1>
-                    { "context" : "cafe" },
-                    { "context" : "restaurants", "boost": 2 }
-                 ]
+    "suggest": {
+        "place_suggestion" : {
+            "prefix" : "tim",
+            "completion" : {
+                "field" : "suggest",
+                "size": 10,
+                "contexts": {
+                    "place_type": [ <1>
+                        { "context" : "cafe" },
+                        { "context" : "restaurants", "boost": 2 }
+                     ]
+                }
            }
        }
    }
@ -275,17 +279,19 @@ the encoded geohash of a geo point:

 [source,js]
 --------------------------------------------------
-POST place/_suggest
+POST place/_search
 {
-    "suggest" : {
-        "prefix" : "tim",
-        "completion" : {
-            "field" : "suggest",
-            "size": 10,
-            "contexts": {
-                "location": {
-                    "lat": 43.662,
-                    "lon": -79.380
+    "suggest": {
+        "place_suggestion" : {
+            "prefix" : "tim",
+            "completion" : {
+                "field" : "suggest",
+                "size": 10,
+                "contexts": {
+                    "location": {
+                        "lat": 43.662,
+                        "lon": -79.380
+                    }
                }
            }
        }
@ -303,28 +309,30 @@ than others, as shown by the following:

 [source,js]
 --------------------------------------------------
-POST place/_suggest?pretty
+POST place/_search?pretty
 {
-    "suggest" : {
-        "prefix" : "tim",
-        "completion" : {
-            "field" : "suggest",
-            "size": 10,
-            "contexts": {
-                "location": [ <1>
-                    {
-                        "lat": 43.6624803,
-                        "lon": -79.3863353,
-                        "precision": 2
-                    },
-                    {
-                        "context": {
+    "suggest": {
+        "place_suggestion" : {
+            "prefix" : "tim",
+            "completion" : {
+                "field" : "suggest",
+                "size": 10,
+                "contexts": {
+                    "location": [ <1>
+                        {
                            "lat": 43.6624803,
-                            "lon": -79.3863353
+                            "lon": -79.3863353,
+                            "precision": 2
                        },
-                        "boost": 2
-                    }
-                 ]
+                        {
+                            "context": {
+                                "lat": 43.6624803,
+                                "lon": -79.3863353
+                            },
+                            "boost": 2
+                        }
+                     ]
+                }
            }
        }
    }
--- a/docs/reference/search/suggesters/phrase-suggest.asciidoc
+++ b/docs/reference/search/suggesters/phrase-suggest.asciidoc
@ -84,21 +84,23 @@ suggester in the same spot you'd use the `term` suggester:

 [source,js]
 --------------------------------------------------
-POST _suggest
+POST test/_search
 {
-  "text": "noble prize",
-  "simple_phrase": {
-    "phrase": {
-      "field": "title.trigram",
-      "size": 1,
-      "gram_size": 3,
-      "direct_generator": [ {
+  "suggest": {
+    "text": "noble prize",
+    "simple_phrase": {
+      "phrase": {
        "field": "title.trigram",
-        "suggest_mode": "always"
-      } ],
-      "highlight": {
-        "pre_tag": "<em>",
-        "post_tag": "</em>"
+        "size": 1,
+        "gram_size": 3,
+        "direct_generator": [ {
+          "field": "title.trigram",
+          "suggest_mode": "always"
+        } ],
+        "highlight": {
+          "pre_tag": "<em>",
+          "post_tag": "</em>"
+        }
      }
    }
  }
@ -112,21 +114,28 @@ The response contains suggestions scored by the most likely spell correction fir
 --------------------------------------------------
 {
  "_shards": ...
-  "simple_phrase" : [
-    {
-      "text" : "noble prize",
-      "offset" : 0,
-      "length" : 11,
-      "options" : [ {
-        "text" : "nobel prize",
-        "highlighted": "<em>nobel</em> prize",
-        "score" : 0.5962314
-      }]
-    }
-  ]
+  "hits": ...
+  "timed_out": false,
+  "took": 3,
+  "suggest": {
+    "simple_phrase" : [
+      {
+        "text" : "noble prize",
+        "offset" : 0,
+        "length" : 11,
+        "options" : [ {
+          "text" : "nobel prize",
+          "highlighted": "<em>nobel</em> prize",
+          "score" : 0.5962314
+        }]
+      }
+    ]
+  }
 }
 --------------------------------------------------
 // TESTRESPONSE[s/"_shards": .../"_shards": "$body._shards",/]
+// TESTRESPONSE[s/"hits": .../"hits": "$body.hits",/]
+// TESTRESPONSE[s/"took": 3,/"took": "$body.took",/]

 ==== Basic Phrase suggest API parameters

@ -217,28 +226,30 @@ The response contains suggestions scored by the most likely spell correction fir

 [source,js]
 --------------------------------------------------
-POST _suggest
+POST _search
 {
-  "text" : "noble prize",
-  "simple_phrase" : {
-    "phrase" : {
-      "field" :  "title.trigram",
-      "size" :   1,
-      "direct_generator" : [ {
-        "field" :            "title.trigram",
-        "suggest_mode" :     "always",
-        "min_word_length" :  1
-      } ],
-      "collate": {
-        "query": { <1>
-          "inline" : {
-            "match": {
-              "{{field_name}}" : "{{suggestion}}" <2>
+  "suggest": {
+    "text" : "noble prize",
+    "simple_phrase" : {
+      "phrase" : {
+        "field" :  "title.trigram",
+        "size" :   1,
+        "direct_generator" : [ {
+          "field" :            "title.trigram",
+          "suggest_mode" :     "always",
+          "min_word_length" :  1
+        } ],
+        "collate": {
+          "query": { <1>
+            "inline" : {
+              "match": {
+                "{{field_name}}" : "{{suggestion}}" <2>
+              }
            }
-          }
-        },
-        "params": {"field_name" : "title"}, <3>
-        "prune": true <4>
+          },
+          "params": {"field_name" : "title"}, <3>
+          "prune": true <4>
+        }
      }
    }
  }
@ -381,22 +392,24 @@ accept ordinary analyzer names.

 [source,js]
 --------------------------------------------------
-POST _suggest
+POST _search
 {
-  "text" : "obel prize",
-  "simple_phrase" : {
-    "phrase" : {
-      "field" : "title.trigram",
-      "size" : 1,
-      "direct_generator" : [ {
+  "suggest": {
+    "text" : "obel prize",
+    "simple_phrase" : {
+      "phrase" : {
        "field" : "title.trigram",
-        "suggest_mode" : "always"
-      }, {
-        "field" : "title.reverse",
-        "suggest_mode" : "always",
-        "pre_filter" : "reverse",
-        "post_filter" : "reverse"
-      } ]
+        "size" : 1,
+        "direct_generator" : [ {
+          "field" : "title.trigram",
+          "suggest_mode" : "always"
+        }, {
+          "field" : "title.reverse",
+          "suggest_mode" : "always",
+          "pre_filter" : "reverse",
+          "post_filter" : "reverse"
+        } ]
+      }
    }
  }
 }
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/suggest.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/suggest.json
@ -1,7 +1,7 @@
 {
  "suggest": {
    "documentation": "http://www.elastic.co/guide/en/elasticsearch/reference/master/search-suggesters.html",
-    "methods": ["POST", "GET"],
+    "methods": ["POST"],
    "url": {
      "path": "/_suggest",
      "paths": ["/_suggest", "/{index}/_suggest"],
@ -13,18 +13,18 @@
      },
      "params": {
        "ignore_unavailable": {
-            "type" : "boolean",
-            "description" : "Whether specified concrete indices should be ignored when unavailable (missing or closed)"
+          "type" : "boolean",
+          "description" : "Whether specified concrete indices should be ignored when unavailable (missing or closed)"
        },
        "allow_no_indices": {
-            "type" : "boolean",
-            "description" : "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)"
+          "type" : "boolean",
+          "description" : "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)"
        },
        "expand_wildcards": {
-            "type" : "enum",
-            "options" : ["open","closed","none","all"],
-            "default" : "open",
-            "description" : "Whether to expand wildcard expression to concrete indices that are open, closed or both."
+          "type" : "enum",
+          "options" : ["open","closed","none","all"],
+          "default" : "open",
+          "description" : "Whether to expand wildcard expression to concrete indices that are open, closed or both."
        },
        "preference": {
          "type" : "string",
@ -41,4 +41,4 @@
      "required" : true
    }
  }
-}
+}
--- a/rest-api-spec/src/main/resources/rest-api-spec/test/indices.stats/13_fields.yaml
+++ b/rest-api-spec/src/main/resources/rest-api-spec/test/indices.stats/13_fields.yaml
@ -38,22 +38,24 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        index: test1
        body:
-          result:
-            text: "b"
-            completion:
-              field: bar.completion
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: bar.completion

  - do:
-      suggest:
+      search:
        index: test1
        body:
-          result:
-            text: "b"
-            completion:
-              field: baz.completion
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: baz.completion

  - do:
      indices.refresh: {}
@ -291,4 +293,3 @@ setup:
  - gt:       { _all.total.completion.fields.bar\.completion.size_in_bytes: 0 }
  - is_false:   _all.total.completion.fields.baz\.completion
  - is_false:   _all.total.fielddata.fields
-
--- a/rest-api-spec/src/main/resources/rest-api-spec/test/suggest/10_basic.yaml
+++ b/rest-api-spec/src/main/resources/rest-api-spec/test/suggest/10_basic.yaml
@ -13,6 +13,24 @@ setup:
 "Basic tests for suggest API":

  - do:
+      search:
+        body:
+          suggest:
+            test_suggestion:
+              text: "The Amsterdma meetpu"
+              term:
+                field: body
+
+  - match: {suggest.test_suggestion.1.options.0.text: amsterdam}
+  - match: {suggest.test_suggestion.2.options.0.text: meetup}
+
+---
+"Suggest API should have deprecation warning":
+  - skip:
+      features: 'warnings'
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
      suggest:
        body:
          test_suggestion:
--- a/rest-api-spec/src/main/resources/rest-api-spec/test/suggest/110_completion.yaml
+++ b/rest-api-spec/src/main/resources/rest-api-spec/test/suggest/110_completion.yaml
@ -0,0 +1,314 @@
+# This test creates one huge mapping in the setup
+# Every test should use its own field to make sure it works
+
+setup:
+
+  - do:
+      indices.create:
+          index: test
+          body:
+            mappings:
+              test:
+                "properties":
+                  "suggest_1":
+                     "type" : "completion"
+                  "suggest_2":
+                     "type" : "completion"
+                  "suggest_3":
+                     "type" : "completion"
+                  "suggest_4":
+                     "type" : "completion"
+                  "suggest_5a":
+                     "type" : "completion"
+                  "suggest_5b":
+                     "type" : "completion"
+                  "suggest_6":
+                     "type" : "completion"
+                  title:
+                     type: keyword
+
+---
+"Simple suggestion should work":
+  - skip:
+      features: 'warnings'
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    1
+        body:
+          suggest_1: "bar"
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    2
+        body:
+          suggest_1: "baz"
+
+  - do:
+      indices.refresh: {}
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "b"
+            completion:
+              field: suggest_1
+
+  - length: { result: 1  }
+  - length: { result.0.options: 2  }
+
+---
+"Simple suggestion array should work":
+  - skip:
+      features: 'warnings'
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    1
+        body:
+          suggest_2: ["bar", "foo"]
+
+  - do:
+      indices.refresh: {}
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "f"
+            completion:
+              field: suggest_2
+
+  - length: { result: 1  }
+  - length: { result.0.options: 1  }
+  - match:  { result.0.options.0.text: "foo" }
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "b"
+            completion:
+              field: suggest_2
+
+  - length: { result: 1  }
+  - length: { result.0.options: 1  }
+  - match:  { result.0.options.0.text: "bar" }
+
+---
+"Suggestion entry should work":
+  - skip:
+      features: 'warnings'
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    1
+        body:
+          suggest_3:
+            input: "bar"
+            weight: 2
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    2
+        body:
+          suggest_3:
+            input: "baz"
+            weight: 3
+
+  - do:
+      indices.refresh: {}
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "b"
+            completion:
+              field: suggest_3
+
+  - length: { result: 1  }
+  - length: { result.0.options: 2  }
+  - match:  { result.0.options.0.text: "baz" }
+  - match:  { result.0.options.1.text: "bar" }
+
+---
+"Suggestion entry array should work":
+  - skip:
+      features: 'warnings'
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    1
+        body:
+          suggest_4:
+            - input: "bar"
+              weight: 3
+            - input: "fo"
+              weight: 3
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    2
+        body:
+          suggest_4:
+            - input: "baz"
+              weight: 2
+            - input: "foo"
+              weight: 1
+
+  - do:
+      indices.refresh: {}
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "b"
+            completion:
+              field: suggest_4
+
+  - length: { result: 1  }
+  - length: { result.0.options: 2  }
+  - match:  { result.0.options.0.text: "bar" }
+  - match:  { result.0.options.1.text: "baz" }
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "f"
+            completion:
+              field: suggest_4
+
+  - length: { result: 1  }
+  - length: { result.0.options: 2  }
+  - match:  { result.0.options.0.text: "fo" }
+  - match:  { result.0.options.1.text: "foo" }
+
+---
+"Multiple Completion fields should work":
+  - skip:
+      features: 'warnings'
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    1
+        body:
+          suggest_5a: "bar"
+          suggest_5b: "baz"
+
+  - do:
+      indices.refresh: {}
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "b"
+            completion:
+              field: suggest_5a
+
+  - length: { result: 1  }
+  - length: { result.0.options: 1  }
+  - match:  { result.0.options.0.text: "bar" }
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "b"
+            completion:
+              field: suggest_5b
+
+  - length: { result: 1  }
+  - length: { result.0.options: 1  }
+  - match:  { result.0.options.0.text: "baz" }
+
+---
+"Suggestions with source should work":
+  - skip:
+      features: 'warnings'
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    1
+        body:
+          suggest_6:
+            input: "bar"
+            weight: 2
+          title: "title_bar"
+          count: 4
+
+  - do:
+      index:
+        index: test
+        type:  test
+        id:    2
+        body:
+          suggest_6:
+            input: "baz"
+            weight: 3
+          title: "title_baz"
+          count: 3
+
+  - do:
+      indices.refresh: {}
+
+  - do:
+      warnings:
+        - "[POST /_suggest] is deprecated! Use [POST /_search] instead."
+      suggest:
+        body:
+          result:
+            text: "b"
+            completion:
+              field: suggest_6
+
+  - length: { result: 1  }
+  - length: { result.0.options: 2  }
+  - match:  { result.0.options.0.text: "baz" }
+  - match:  { result.0.options.0._index: "test" }
+  - match:  { result.0.options.0._type: "test" }
+  - match:  { result.0.options.0._source.title: "title_baz" }
+  - match:  { result.0.options.0._source.count: 3 }
+  - match:  { result.0.options.1.text: "bar" }
+  - match:  { result.0.options.1._index: "test" }
+  - match:  { result.0.options.1._type: "test" }
+  - match:  { result.0.options.1._source.title: "title_bar" }
+  - match:  { result.0.options.1._source.count: 4 }
--- a/rest-api-spec/src/main/resources/rest-api-spec/test/suggest/20_completion.yaml
+++ b/rest-api-spec/src/main/resources/rest-api-spec/test/suggest/20_completion.yaml
@ -50,15 +50,16 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "b"
-            completion:
-              field: suggest_1
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: suggest_1

-  - length: { result: 1  }
-  - length: { result.0.options: 2  }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 2  }

 ---
 "Simple suggestion array should work":
@ -75,28 +76,30 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "f"
-            completion:
-              field: suggest_2
+          suggest:
+            result:
+              text: "f"
+              completion:
+                field: suggest_2

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "foo" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "foo" }

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "b"
-            completion:
-              field: suggest_2
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: suggest_2

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "bar" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "bar" }

 ---
 "Suggestion entry should work":
@ -125,17 +128,18 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "b"
-            completion:
-              field: suggest_3
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: suggest_3

-  - length: { result: 1  }
-  - length: { result.0.options: 2  }
-  - match:  { result.0.options.0.text: "baz" }
-  - match:  { result.0.options.1.text: "bar" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 2  }
+  - match:  { suggest.result.0.options.0.text: "baz" }
+  - match:  { suggest.result.0.options.1.text: "bar" }

 ---
 "Suggestion entry array should work":
@ -168,30 +172,32 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "b"
-            completion:
-              field: suggest_4
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: suggest_4

-  - length: { result: 1  }
-  - length: { result.0.options: 2  }
-  - match:  { result.0.options.0.text: "bar" }
-  - match:  { result.0.options.1.text: "baz" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 2  }
+  - match:  { suggest.result.0.options.0.text: "bar" }
+  - match:  { suggest.result.0.options.1.text: "baz" }

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "f"
-            completion:
-              field: suggest_4
+          suggest:
+            result:
+              text: "f"
+              completion:
+                field: suggest_4

-  - length: { result: 1  }
-  - length: { result.0.options: 2  }
-  - match:  { result.0.options.0.text: "fo" }
-  - match:  { result.0.options.1.text: "foo" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 2  }
+  - match:  { suggest.result.0.options.0.text: "fo" }
+  - match:  { suggest.result.0.options.1.text: "foo" }

 ---
 "Multiple Completion fields should work":
@ -209,28 +215,30 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "b"
-            completion:
-              field: suggest_5a
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: suggest_5a

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "bar" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "bar" }

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "b"
-            completion:
-              field: suggest_5b
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: suggest_5b

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "baz" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "baz" }

 ---
 "Suggestions with source should work":
@ -263,23 +271,23 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "b"
-            completion:
-              field: suggest_6
-
-  - length: { result: 1  }
-  - length: { result.0.options: 2  }
-  - match:  { result.0.options.0.text: "baz" }
-  - match:  { result.0.options.0._index: "test" }
-  - match:  { result.0.options.0._type: "test" }
-  - match:  { result.0.options.0._source.title: "title_baz" }
-  - match:  { result.0.options.0._source.count: 3 }
-  - match:  { result.0.options.1.text: "bar" }
-  - match:  { result.0.options.1._index: "test" }
-  - match:  { result.0.options.1._type: "test" }
-  - match:  { result.0.options.1._source.title: "title_bar" }
-  - match:  { result.0.options.1._source.count: 4 }
+          suggest:
+            result:
+              text: "b"
+              completion:
+                field: suggest_6

+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 2  }
+  - match:  { suggest.result.0.options.0.text: "baz" }
+  - match:  { suggest.result.0.options.0._index: "test" }
+  - match:  { suggest.result.0.options.0._type: "test" }
+  - match:  { suggest.result.0.options.0._source.title: "title_baz" }
+  - match:  { suggest.result.0.options.0._source.count: 3 }
+  - match:  { suggest.result.0.options.1.text: "bar" }
+  - match:  { suggest.result.0.options.1._index: "test" }
+  - match:  { suggest.result.0.options.1._type: "test" }
+  - match:  { suggest.result.0.options.1._source.title: "title_bar" }
+  - match:  { suggest.result.0.options.1._source.count: 4 }
--- a/rest-api-spec/src/main/resources/rest-api-spec/test/suggest/30_context.yaml
+++ b/rest-api-spec/src/main/resources/rest-api-spec/test/suggest/30_context.yaml
@ -74,18 +74,19 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "foo"
-            completion:
-              field: suggest_context
-              contexts:
-                color: "red"
+          suggest:
+            result:
+              text: "foo"
+              completion:
+                field: suggest_context
+                contexts:
+                  color: "red"

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  {  result.0.options.0.text: "foo red" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "foo red" }

 ---
 "Category suggest context from path should work":
@ -114,45 +115,48 @@ setup:
      indices.refresh: {}

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "foo"
-            completion:
-              field: suggest_context_with_path
-              contexts:
-                color: "red"
+          suggest:
+            result:
+              text: "foo"
+              completion:
+                field: suggest_context_with_path
+                contexts:
+                  color: "red"

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "Foo red" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "Foo red" }

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "foo"
-            completion:
-              field: suggest_context_with_path
-              contexts:
-                color: "blue"
+          suggest:
+            result:
+              text: "foo"
+              completion:
+                field: suggest_context_with_path
+                contexts:
+                  color: "blue"

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "Foo blue" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "Foo blue" }

  - do:
-      suggest:
+      search:
        body:
-          result:
-            text: "foo"
-            completion:
-              field: suggest_context_with_path
-              contexts:
-                color: ["blue", "red"]
+          suggest:
+            result:
+              text: "foo"
+              completion:
+                field: suggest_context_with_path
+                contexts:
+                  color: ["blue", "red"]

-  - length: { result: 1  }
-  - length: { result.0.options: 2  }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 2  }

 ---
 "Geo suggest should work":
@ -190,21 +194,22 @@ setup:
      indices.get_mapping: {}

  - do:
-      suggest:
+      search:
        index: test
        body:
-          result:
-            text: "mar"
-            completion:
-              field: suggest_geo
-              contexts:
-                location:
-                  lat : 52.2263
-                  lon : 4.543
+          suggest:
+            result:
+              text: "mar"
+              completion:
+                field: suggest_geo
+                contexts:
+                  location:
+                    lat : 52.2263
+                    lon : 4.543

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "Marriot in Amsterdam" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "Marriot in Amsterdam" }

 ---
 "Multi contexts should work":
@ -240,33 +245,35 @@ setup:
      indices.get_mapping: {}

  - do:
-      suggest:
+      search:
        index: test
        body:
-          result:
-            text: "mar"
-            completion:
-              field: suggest_multi_contexts
-              contexts:
-                location:
-                  lat : 52.22
-                  lon : 4.53
+          suggest:
+            result:
+              text: "mar"
+              completion:
+                field: suggest_multi_contexts
+                contexts:
+                  location:
+                    lat : 52.22
+                    lon : 4.53

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "Marriot in Amsterdam" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "Marriot in Amsterdam" }

  - do:
-      suggest:
+      search:
        index: test
        body:
-          result:
-            text: "mar"
-            completion:
-              field: suggest_multi_contexts
-              contexts:
-                color: "blue"
+          suggest:
+            result:
+              text: "mar"
+              completion:
+                field: suggest_multi_contexts
+                contexts:
+                  color: "blue"

-  - length: { result: 1  }
-  - length: { result.0.options: 1  }
-  - match:  { result.0.options.0.text: "Marriot in Berlin" }
+  - length: { suggest.result: 1  }
+  - length: { suggest.result.0.options: 1  }
+  - match:  { suggest.result.0.options.0.text: "Marriot in Berlin" }