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

[DOCS] Relocate search API's request body parameters #56304

Merged
merged 2 commits into from
May 7, 2020
+143 −106
Merged

[DOCS] Relocate search API's request body parameters #56304

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
df2053b
[DOCS] Relocate search API's request body parameters
jrodewig May 6, 2020
013cca6
Update css_minimize_roundtrips and request_cache defs
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
99 changes: 1 addition & 98 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,106 +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`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the pages this is moved to, cross-cluster search ({ccs}) as a term isn't mentioned explicitly and the link to the network delays is missing. I don't know if this was left out on purpose to simplify things, but at least spelling out the abreviation might be a good addition.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching this. I agree this is the better definition and moved it over with 013cca6. As a note: {ccs} expands to cross-cluster search, not CCS, so the full wording renders in the final HTML.


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>>.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is enabled for requests where size is 0
I don't know if this is useful information, seems to be missing from the target page

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another good catch. Moved over with 013cca6.


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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does this in reverse mean the batched_reduce_size and ccs_minimize_roundtrips should also go to the "body" section on the target page? Currently they seem to be only listed under Query Parameters. I don't know if they are allowed in both places tbh but we can check...

Copy link
Contributor Author

@jrodewig jrodewig May 7, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested this by running off the master branch and it appears that neither batched_reduce_size nor ccs_minimize_roundtrips are valid request body parameters. Both work fine as query parameters though.

Setup

PUT /my_index/_doc/0
{
  "user": "kimchy"
}

ccs_minimize_roundtrips

GET /my_index/_search
{
    "ccs_minimize_roundtrips": false,
    "query" : {
        "term" : { "user" : "kimchy" }
    }
}

Response:

{
  "error" : {
    "root_cause" : [
      {
        "type" : "parsing_exception",
        "reason" : "Unknown key for a VALUE_BOOLEAN in [ccs_minimize_roundtrips].",
        "line" : 3,
        "col" : 32
      }
    ],
    "type" : "parsing_exception",
    "reason" : "Unknown key for a VALUE_BOOLEAN in [ccs_minimize_roundtrips].",
    "line" : 3,
    "col" : 32
  },
  "status" : 400
}

batched_reduce_size

GET /my_index/_search
{
    "batched_reduce_size": 512,
    "query" : {
        "term" : { "user" : "kimchy" }
    }
}

Response:

{
  "error" : {
    "root_cause" : [
      {
        "type" : "parsing_exception",
        "reason" : "Unknown key for a VALUE_NUMBER in [batched_reduce_size].",
        "line" : 3,
        "col" : 28
      }
    ],
    "type" : "parsing_exception",
    "reason" : "Unknown key for a VALUE_NUMBER in [batched_reduce_size].",
    "line" : 3,
    "col" : 28
  },
  "status" : 400
}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for checking.

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",
"_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
140 changes: 136 additions & 4 deletions docs/reference/search/search.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ 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`.
Expand All @@ -75,6 +76,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 @@ -139,7 +148,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 @@ -171,12 +188,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 @@ -201,11 +235,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 @@ -422,3 +503,54 @@ 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",
"_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/]