Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.x] [DOCS] Relocate search API's request body parameters (#56304) #56347

Merged
merged 2 commits into from
May 7, 2020
Merged

[7.x] [DOCS] Relocate search API's request body parameters (#56304) #56347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5d67a3
[DOCS] Relocate search API's request body parameters (#56304)
jrodewig May 7, 2020
c06e655
add mapping type
jrodewig May 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 1 addition & 99 deletions docs/reference/search/request-body.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ GET /twitter/_search
[[search-request-body-api-request]]
==== {api-request-title}


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

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


[[search-request-body-api-request-body]]
==== {api-request-body-title}

`allow_partial_search_results`::
(Optional, boolean) Set to `false` to fail the request if only partial results
are available. Defaults to `true`, which returns partial results in the event
of timeouts or partial failures You can override the default behavior for all
requests by setting `search.default_allow_partial_results` to `false` in the
cluster settings.

`batched_reduce_size`::
(Optional, integer) The number of shard results that should be reduced at once
on the coordinating node. This value should be used as a protection mechanism
to reduce the memory overhead per search request if the potential number of
shards in the request can be large.

[[ccs-minimize-roundtrips]]
`ccs_minimize_roundtrips`::
(Optional, boolean) If `true`, the network round-trips between the
coordinating node and the remote clusters ewill be minimized when executing
{ccs} requests. See <<ccs-network-delays>>. Defaults to `true`.

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

`request_cache`::
(Optional, boolean) If `true`, the caching of search results is enabled for
requests where `size` is `0`. See <<shard-request-cache>>.

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

`size`::
(Optional, integer) The number of hits to return. Defaults to `10`.

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

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


Out of the above, the `search_type`, `request_cache` and the
`allow_partial_search_results` settings must be passed as query-string
parameters. The rest of the search request should be passed within the body
itself. The body content can also be passed as a REST parameter named `source`.

Both HTTP GET and HTTP POST can be used to execute search with body. Since not
all clients support GET with body, POST is allowed as well.


[[search-request-body-api-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
GET /twitter/_search
{
"query" : {
"term" : { "user" : "kimchy" }
}
}
--------------------------------------------------
// TEST[setup:twitter]


The API returns the following response:

[source,console-result]
--------------------------------------------------
{
"took": 1,
"timed_out": false,
"_shards":{
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits":{
"total" : {
"value": 1,
"relation": "eq"
},
"max_score": 1.3862942,
"hits" : [
{
"_index" : "twitter",
"_type" : "_doc",
"_id" : "0",
"_score": 1.3862942,
"_source" : {
"user" : "kimchy",
"message": "trying out Elasticsearch",
"date" : "2009-11-15T14:12:12",
"likes" : 0
}
}
]
}
}
--------------------------------------------------
// TESTRESPONSE[s/"took": 1/"took": $body.took/]

See the search API's <<search-search-api-request-body,request body parameters>>.

==== Fast check for any matching docs

Expand Down
151 changes: 143 additions & 8 deletions docs/reference/search/search.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,11 @@ To override the default for this field, set the
to reduce the memory overhead per search request if the potential number of
shards in the request can be large. Defaults to `512`.

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

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

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

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

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

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

`size`::
(Optional, integer) Defines the number of hits to return. Defaults to `10`.
(Optional, integer) Defines the number of hits to return. Defaults to `10`.
+
--
[IMPORTANT]
====
You can also specify this value using the `size` request body parameter. If
both parameters are specified, only the query parameter is used.
====
--

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

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

[IMPORTANT]
====
You can also specify this value using the `terminate_after` request body
parameter. If both parameters are specified, only the query parameter is used.
====
--

`timeout`::
(Optional, <<time-units, time units>>) Specifies the period of time to wait
for a response. If no response is received before the timeout expires, the
request fails and returns an error. Defaults to no timeout.
+
--
(Optional, <<time-units, time units>>) Specifies the period of time to wait
for a response. If no response is received before the timeout expires, the
request fails and returns an error. Defaults to no timeout.

[IMPORTANT]
====
You can also specify this value using the `timeout` request body
parameter. If both parameters are specified, only the query parameter is used.
====
--

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

include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
+
--
[IMPORTANT]
====
You can also specify this value using the `from` query parameter. If both
parameters are specified, only the query parameter is used.
====
--

[[search-api-request-body-query]]
`query`::
(Optional, <<query-dsl,query object>>) Defines the search definition using the
<<query-dsl,Query DSL>>.

`size`::
(Optional, integer) The number of hits to return. Defaults to `10`.
+
--
[IMPORTANT]
====
You can also specify this value using the `size` query parameter. If both
parameters are specified, only the query parameter is used.
====
--

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

[IMPORTANT]
====
You can also specify this value using the `terminate_after` query parameter. If
both parameters are specified, only the query parameter is used.
====
--

`timeout`::
+
--
(Optional, <<time-units, time units>>) Specifies the period of time to wait
for a response. If no response is received before the timeout expires, the
request fails and returns an error. Defaults to no timeout.

[IMPORTANT]
====
You can also specify this value using the `timeout` query parameter. If both
parameters are specified, only the query parameter is used.
====
--

[role="child_attributes"]
[[search-api-response-body]]
==== {api-response-body-title}
Expand Down Expand Up @@ -430,3 +513,55 @@ GET /_all/_search?q=user:kimchy
GET /*/_search?q=user:kimchy
----
// TEST[continued]

[[search-request-body-api-example]]
===== Search an index using the `query` request body parameter

[source,console]
--------------------------------------------------
GET /twitter/_search
{
"query" : {
"term" : { "user" : "kimchy" }
}
}
--------------------------------------------------
// TEST[setup:twitter]

The API returns the following response:

[source,console-result]
--------------------------------------------------
{
"took": 1,
"timed_out": false,
"_shards":{
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits":{
"total" : {
"value": 1,
"relation": "eq"
},
"max_score": 1.3862942,
"hits" : [
{
"_index" : "twitter",
"_type" : "_doc",
"_id" : "0",
"_score": 1.3862942,
"_source" : {
"user" : "kimchy",
"message": "trying out Elasticsearch",
"date" : "2009-11-15T14:12:12",
"likes" : 0
}
}
]
}
}
--------------------------------------------------
// TESTRESPONSE[s/"took": 1/"took": $body.took/]