Skip to content

Commit cdd5fbe

Browse files
areekareek
authored
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
1 parent eaf82a6 commit cdd5fbe

File tree

11 files changed

+769
-388
lines changed

11 files changed

+769
-388
lines changed

‎core/src/main/java/org/elasticsearch/rest/action/search/RestSuggestAction.java

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,10 +56,14 @@ public RestSuggestAction(Settings settings, RestController controller,
5656
SearchRequestParsers searchRequestParsers) {
5757
super(settings);
5858
this.searchRequestParsers = searchRequestParsers;
59-
controller.registerHandler(POST, "/_suggest", this);
60-
controller.registerHandler(GET, "/_suggest", this);
61-
controller.registerHandler(POST, "/{index}/_suggest", this);
62-
controller.registerHandler(GET, "/{index}/_suggest", this);
59+
controller.registerAsDeprecatedHandler(POST, "/_suggest", this,
60+
"[POST /_suggest] is deprecated! Use [POST /_search] instead.", deprecationLogger);
61+
controller.registerAsDeprecatedHandler(GET, "/_suggest", this,
62+
"[GET /_suggest] is deprecated! Use [GET /_search] instead.", deprecationLogger);
63+
controller.registerAsDeprecatedHandler(POST, "/{index}/_suggest", this,
64+
"[POST /{index}/_suggest] is deprecated! Use [POST /{index}/_search] instead.", deprecationLogger);
65+
controller.registerAsDeprecatedHandler(GET, "/{index}/_suggest", this,
66+
"[GET /{index}/_suggest] is deprecated! Use [GET /{index}/_search] instead.", deprecationLogger);
6367
}
6468

6569
@Override

‎docs/reference/search/suggesters.asciidoc

Lines changed: 56 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,12 @@ The suggest feature suggests similar looking terms based on a provided
55
text by using a suggester. Parts of the suggest feature are still under
66
development.
77

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

1115
[source,js]
1216
--------------------------------------------------
@@ -30,44 +34,27 @@ POST twitter/_search
3034
// CONSOLE
3135
// TEST[setup:twitter]
3236

33-
Suggest requests executed against the `_suggest` endpoint should omit
34-
the surrounding `suggest` element which is only used if the suggest
35-
request is part of a search.
36-
37-
[source,js]
38-
--------------------------------------------------
39-
POST _suggest
40-
{
41-
"my-suggestion" : {
42-
"text" : "tring out Elasticsearch",
43-
"term" : {
44-
"field" : "message"
45-
}
46-
}
47-
}
48-
--------------------------------------------------
49-
// CONSOLE
50-
// TEST[setup:twitter]
51-
5237
Several suggestions can be specified per request. Each suggestion is
5338
identified with an arbitrary name. In the example below two suggestions
5439
are requested. Both `my-suggest-1` and `my-suggest-2` suggestions use
5540
the `term` suggester, but have a different `text`.
5641

5742
[source,js]
5843
--------------------------------------------------
59-
POST _suggest
44+
POST _search
6045
{
61-
"my-suggest-1" : {
62-
"text" : "tring out Elasticsearch",
63-
"term" : {
64-
"field" : "message"
65-
}
66-
},
67-
"my-suggest-2" : {
68-
"text" : "kmichy",
69-
"term" : {
70-
"field" : "user"
46+
"suggest": {
47+
"my-suggest-1" : {
48+
"text" : "tring out Elasticsearch",
49+
"term" : {
50+
"field" : "message"
51+
}
52+
},
53+
"my-suggest-2" : {
54+
"text" : "kmichy",
55+
"term" : {
56+
"field" : "user"
57+
}
7158
}
7259
}
7360
}
@@ -85,27 +72,34 @@ in the suggest text and if found an arbitrary number of options.
8572
--------------------------------------------------
8673
{
8774
"_shards": ...
88-
"my-suggest-1": [ {
89-
"text": "tring",
90-
"offset": 0,
91-
"length": 5,
92-
"options": [ {"text": "trying", "score": 0.8, "freq": 1 } ]
93-
}, {
94-
"text": "out",
95-
"offset": 6,
96-
"length": 3,
97-
"options": []
98-
}, {
99-
"text": "elasticsearch",
100-
"offset": 10,
101-
"length": 13,
102-
"options": []
103-
} ],
104-
"my-suggest-2": ...
75+
"hits": ...
76+
"took": 2,
77+
"timed_out": false,
78+
"suggest": {
79+
"my-suggest-1": [ {
80+
"text": "tring",
81+
"offset": 0,
82+
"length": 5,
83+
"options": [ {"text": "trying", "score": 0.8, "freq": 1 } ]
84+
}, {
85+
"text": "out",
86+
"offset": 6,
87+
"length": 3,
88+
"options": []
89+
}, {
90+
"text": "elasticsearch",
91+
"offset": 10,
92+
"length": 13,
93+
"options": []
94+
} ],
95+
"my-suggest-2": ...
96+
}
10597
}
10698
--------------------------------------------------
10799
// TESTRESPONSE[s/"_shards": \.\.\./"_shards": "$body._shards",/]
108-
// TESTRESPONSE[s/"my-suggest-2": \.\.\./"my-suggest-2": "$body.my-suggest-2"/]
100+
// TESTRESPONSE[s/"hits": .../"hits": "$body.hits",/]
101+
// TESTRESPONSE[s/"took": 2,/"took": "$body.took",/]
102+
// TESTRESPONSE[s/"my-suggest-2": \.\.\./"my-suggest-2": "$body.suggest.my-suggest-2"/]
109103

110104

111105
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.
123117

124118
[source,js]
125119
--------------------------------------------------
126-
POST _suggest
120+
POST _search
127121
{
128-
"text" : "tring out Elasticsearch",
129-
"my-suggest-1" : {
130-
"term" : {
131-
"field" : "message"
132-
}
133-
},
134-
"my-suggest-2" : {
135-
"term" : {
136-
"field" : "user"
122+
"suggest": {
123+
"text" : "tring out Elasticsearch",
124+
"my-suggest-1" : {
125+
"term" : {
126+
"field" : "message"
127+
}
128+
},
129+
"my-suggest-2" : {
130+
"term" : {
131+
"field" : "user"
132+
}
137133
}
138134
}
139135
}

‎docs/reference/search/suggesters/completion-suggest.asciidoc

Lines changed: 44 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -152,12 +152,14 @@ documents once deleted are never shown. This request:
152152

153153
[source,js]
154154
--------------------------------------------------
155-
POST music/_suggest?pretty
155+
POST music/_search?pretty
156156
{
157-
"song-suggest" : {
158-
"prefix" : "nir",
159-
"completion" : {
160-
"field" : "suggest"
157+
"suggest": {
158+
"song-suggest" : {
159+
"prefix" : "nir",
160+
"completion" : {
161+
"field" : "suggest"
162+
}
161163
}
162164
}
163165
}
@@ -175,24 +177,30 @@ returns this response:
175177
"successful" : 5,
176178
"failed" : 0
177179
},
178-
"song-suggest" : [ {
179-
"text" : "nir",
180-
"offset" : 0,
181-
"length" : 3,
182-
"options" : [ {
183-
"text" : "Nirvana",
184-
"_index": "music",
185-
"_type": "song",
186-
"_id": "1",
187-
"_score": 1.0,
188-
"_source": {
189-
"suggest": ["Nevermind", "Nirvana"]
190-
}
180+
"hits": ...
181+
"took": 2,
182+
"timed_out": false,
183+
"suggest": {
184+
"song-suggest" : [ {
185+
"text" : "nir",
186+
"offset" : 0,
187+
"length" : 3,
188+
"options" : [ {
189+
"text" : "Nirvana",
190+
"_index": "music",
191+
"_type": "song",
192+
"_id": "1",
193+
"_score": 1.0,
194+
"_source": {
195+
"suggest": ["Nevermind", "Nirvana"]
196+
}
197+
} ]
191198
} ]
192-
} ]
199+
}
193200
}
194201
--------------------------------------------------
195-
// TESTRESPONSE
202+
// TESTRESPONSE[s/"hits": .../"hits": "$body.hits",/]
203+
// TESTRESPONSE[s/"took": 2,/"took": "$body.took",/]
196204

197205

198206
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.
289297

290298
[source,js]
291299
--------------------------------------------------
292-
POST music/_suggest?pretty
300+
POST music/_search?pretty
293301
{
294-
"song-suggest" : {
295-
"prefix" : "nor",
296-
"completion" : {
297-
"field" : "suggest",
298-
"fuzzy" : {
299-
"fuzziness" : 2
302+
"suggest": {
303+
"song-suggest" : {
304+
"prefix" : "nor",
305+
"completion" : {
306+
"field" : "suggest",
307+
"fuzzy" : {
308+
"fuzziness" : 2
309+
}
300310
}
301311
}
302312
}
@@ -346,12 +356,14 @@ you can express a prefix as a regular expression
346356

347357
[source,js]
348358
--------------------------------------------------
349-
POST music/_suggest?pretty
359+
POST music/_search?pretty
350360
{
351-
"song-suggest" : {
352-
"regex" : "n[ever|i]r",
353-
"completion" : {
354-
"field" : "suggest"
361+
"suggest": {
362+
"song-suggest" : {
363+
"regex" : "n[ever|i]r",
364+
"completion" : {
365+
"field" : "suggest"
366+
}
355367
}
356368
}
357369
}

0 commit comments

Comments
 (0)