Skip to content

Commit bb381ea

Browse files
jrodewigjrodewig
authored
[DOCS] Relocate search API's request body parameters (elastic#56304)
Changes: * Moves the document request body parameters for the search API from the Request body search page to the Search API reference page. * Relocates a search request body example from the Request body search page to the Search API reference page. * Adds a note to any duplicated query and request body parameters.
1 parent 371226e commit bb381ea

File tree

2 files changed

+144
-107
lines changed

2 files changed

+144
-107
lines changed

‎docs/reference/search/request-body.asciidoc

Lines changed: 1 addition & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ GET /twitter/_search
1818
[[search-request-body-api-request]]
1919
==== {api-request-title}
2020

21-
2221
`GET /<index>/_search
2322
{
2423
"query": {<parameters>}
@@ -37,107 +36,10 @@ The search request can be executed with a search DSL, which includes the
3736

3837
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
3938

40-
4139
[[search-request-body-api-request-body]]
4240
==== {api-request-body-title}
4341

44-
`allow_partial_search_results`::
45-
(Optional, boolean) Set to `false` to fail the request if only partial results
46-
are available. Defaults to `true`, which returns partial results in the event
47-
of timeouts or partial failures You can override the default behavior for all
48-
requests by setting `search.default_allow_partial_results` to `false` in the
49-
cluster settings.
50-
51-
`batched_reduce_size`::
52-
(Optional, integer) The number of shard results that should be reduced at once
53-
on the coordinating node. This value should be used as a protection mechanism
54-
to reduce the memory overhead per search request if the potential number of
55-
shards in the request can be large.
56-
57-
[[ccs-minimize-roundtrips]]
58-
`ccs_minimize_roundtrips`::
59-
(Optional, boolean) If `true`, the network round-trips between the
60-
coordinating node and the remote clusters ewill be minimized when executing
61-
{ccs} requests. See <<ccs-network-delays>>. Defaults to `true`.
62-
63-
include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
64-
65-
`request_cache`::
66-
(Optional, boolean) If `true`, the caching of search results is enabled for
67-
requests where `size` is `0`. See <<shard-request-cache>>.
68-
69-
include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
70-
71-
`size`::
72-
(Optional, integer) The number of hits to return. Defaults to `10`.
73-
74-
include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]
75-
76-
include::{docdir}/rest-api/common-parms.asciidoc[tag=search_timeout]
77-
78-
79-
Out of the above, the `search_type`, `request_cache` and the
80-
`allow_partial_search_results` settings must be passed as query-string
81-
parameters. The rest of the search request should be passed within the body
82-
itself. The body content can also be passed as a REST parameter named `source`.
83-
84-
Both HTTP GET and HTTP POST can be used to execute search with body. Since not
85-
all clients support GET with body, POST is allowed as well.
86-
87-
88-
[[search-request-body-api-example]]
89-
==== {api-examples-title}
90-
91-
[source,console]
92-
--------------------------------------------------
93-
GET /twitter/_search
94-
{
95-
"query" : {
96-
"term" : { "user" : "kimchy" }
97-
}
98-
}
99-
--------------------------------------------------
100-
// TEST[setup:twitter]
101-
102-
103-
The API returns the following response:
104-
105-
[source,console-result]
106-
--------------------------------------------------
107-
{
108-
"took": 1,
109-
"timed_out": false,
110-
"_shards":{
111-
"total" : 1,
112-
"successful" : 1,
113-
"skipped" : 0,
114-
"failed" : 0
115-
},
116-
"hits":{
117-
"total" : {
118-
"value": 1,
119-
"relation": "eq"
120-
},
121-
"max_score": 1.3862942,
122-
"hits" : [
123-
{
124-
"_index" : "twitter",
125-
"_type" : "_doc",
126-
"_id" : "0",
127-
"_score": 1.3862942,
128-
"_source" : {
129-
"user" : "kimchy",
130-
"message": "trying out Elasticsearch",
131-
"date" : "2009-11-15T14:12:12",
132-
"likes" : 0
133-
}
134-
}
135-
]
136-
}
137-
}
138-
--------------------------------------------------
139-
// TESTRESPONSE[s/"took": 1/"took": $body.took/]
140-
42+
See the search API's <<search-search-api-request-body,request body parameters>>.
14143

14244
==== Fast check for any matching docs
14345

‎docs/reference/search/search.asciidoc

Lines changed: 143 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -60,9 +60,11 @@ To override the default for this field, set the
6060
to reduce the memory overhead per search request if the potential number of
6161
shards in the request can be large. Defaults to `512`.
6262

63+
[[ccs-minimize-roundtrips]]
6364
`ccs_minimize_roundtrips`::
64-
(Optional, boolean) Indicates whether network round-trips should be minimized
65-
as part of cross-cluster search requests execution. Defaults to `true`.
65+
(Optional, boolean) If `true`, network round-trips between the
66+
coordinating node and the remote clusters are minimized when executing
67+
{ccs} (CCS) requests. See <<ccs-network-delays>>. Defaults to `true`.
6668

6769
`docvalue_fields`::
6870
(Optional, string) A comma-separated list of fields to return as the docvalue
@@ -77,6 +79,14 @@ Defaults to `open`.
7779
computation as part of a hit. Defaults to `false`.
7880

7981
include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
82+
+
83+
--
84+
[IMPORTANT]
85+
====
86+
You can also specify this value using the `from` request body parameter. If
87+
both parameters are specified, only the query parameter is used.
88+
====
89+
--
8090

8191
`ignore_throttled`::
8292
(Optional, boolean) If `true`, concrete, expanded or aliased indices will be
@@ -123,8 +133,9 @@ matching the `query` request body parameter are not returned.
123133
--
124134

125135
`request_cache`::
126-
(Optional, boolean) If `true`, request cache will be used for this request.
127-
Defaults to index level settings.
136+
(Optional, boolean) If `true`, the caching of search results is enabled for
137+
requests where `size` is `0`. See <<shard-request-cache>>. Defaults to index
138+
level settings.
128139

129140
`rest_total_hits_as_int`::
130141
(Optional, boolean) Indicates whether hits.total should be rendered as an
@@ -141,7 +152,15 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
141152
last modification of each hit.
142153

143154
`size`::
144-
(Optional, integer) Defines the number of hits to return. Defaults to `10`.
155+
(Optional, integer) Defines the number of hits to return. Defaults to `10`.
156+
+
157+
--
158+
[IMPORTANT]
159+
====
160+
You can also specify this value using the `size` request body parameter. If
161+
both parameters are specified, only the query parameter is used.
162+
====
163+
--
145164

146165
`sort`::
147166
(Optional, string) A comma-separated list of <field>:<direction> pairs.
@@ -173,12 +192,29 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
173192

174193
include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]
175194
+
195+
--
176196
Defaults to `0`, which does not terminate query execution early.
177197

198+
[IMPORTANT]
199+
====
200+
You can also specify this value using the `terminate_after` request body
201+
parameter. If both parameters are specified, only the query parameter is used.
202+
====
203+
--
204+
178205
`timeout`::
179-
(Optional, <<time-units, time units>>) Specifies the period of time to wait
180-
for a response. If no response is received before the timeout expires, the
181-
request fails and returns an error. Defaults to no timeout.
206+
+
207+
--
208+
(Optional, <<time-units, time units>>) Specifies the period of time to wait
209+
for a response. If no response is received before the timeout expires, the
210+
request fails and returns an error. Defaults to no timeout.
211+
212+
[IMPORTANT]
213+
====
214+
You can also specify this value using the `timeout` request body
215+
parameter. If both parameters are specified, only the query parameter is used.
216+
====
217+
--
182218

183219
`track_scores`::
184220
(Optional, boolean) If `true`, calculate and return document scores, even if
@@ -203,11 +239,58 @@ include the total number of hits matching the query.
203239
[[search-search-api-request-body]]
204240
==== {api-request-body-title}
205241

242+
include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
243+
+
244+
--
245+
[IMPORTANT]
246+
====
247+
You can also specify this value using the `from` query parameter. If both
248+
parameters are specified, only the query parameter is used.
249+
====
250+
--
251+
206252
[[search-api-request-body-query]]
207253
`query`::
208254
(Optional, <<query-dsl,query object>>) Defines the search definition using the
209255
<<query-dsl,Query DSL>>.
210256

257+
`size`::
258+
(Optional, integer) The number of hits to return. Defaults to `10`.
259+
+
260+
--
261+
[IMPORTANT]
262+
====
263+
You can also specify this value using the `size` query parameter. If both
264+
parameters are specified, only the query parameter is used.
265+
====
266+
--
267+
268+
include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]
269+
+
270+
--
271+
Defaults to `0`, which does not terminate query execution early.
272+
273+
[IMPORTANT]
274+
====
275+
You can also specify this value using the `terminate_after` query parameter. If
276+
both parameters are specified, only the query parameter is used.
277+
====
278+
--
279+
280+
`timeout`::
281+
+
282+
--
283+
(Optional, <<time-units, time units>>) Specifies the period of time to wait
284+
for a response. If no response is received before the timeout expires, the
285+
request fails and returns an error. Defaults to no timeout.
286+
287+
[IMPORTANT]
288+
====
289+
You can also specify this value using the `timeout` query parameter. If both
290+
parameters are specified, only the query parameter is used.
291+
====
292+
--
293+
211294
[role="child_attributes"]
212295
[[search-api-response-body]]
213296
==== {api-response-body-title}
@@ -430,3 +513,55 @@ GET /_all/_search?q=user:kimchy
430513
GET /*/_search?q=user:kimchy
431514
----
432515
// TEST[continued]
516+
517+
[[search-request-body-api-example]]
518+
===== Search an index using the `query` request body parameter
519+
520+
[source,console]
521+
--------------------------------------------------
522+
GET /twitter/_search
523+
{
524+
"query" : {
525+
"term" : { "user" : "kimchy" }
526+
}
527+
}
528+
--------------------------------------------------
529+
// TEST[setup:twitter]
530+
531+
The API returns the following response:
532+
533+
[source,console-result]
534+
--------------------------------------------------
535+
{
536+
"took": 1,
537+
"timed_out": false,
538+
"_shards":{
539+
"total" : 1,
540+
"successful" : 1,
541+
"skipped" : 0,
542+
"failed" : 0
543+
},
544+
"hits":{
545+
"total" : {
546+
"value": 1,
547+
"relation": "eq"
548+
},
549+
"max_score": 1.3862942,
550+
"hits" : [
551+
{
552+
"_index" : "twitter",
553+
"_type" : "_doc",
554+
"_id" : "0",
555+
"_score": 1.3862942,
556+
"_source" : {
557+
"user" : "kimchy",
558+
"message": "trying out Elasticsearch",
559+
"date" : "2009-11-15T14:12:12",
560+
"likes" : 0
561+
}
562+
}
563+
]
564+
}
565+
}
566+
--------------------------------------------------
567+
// TESTRESPONSE[s/"took": 1/"took": $body.took/]

0 commit comments

Comments
 (0)