From 4b086fbef24511eb03dde22db37d383396b083c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 29 Aug 2019 11:58:28 +0200 Subject: [PATCH] Revert "[DOCS] Reformats URI search request (#45844)" This reverts commit 7f11c3240018b4005f918c4850cc38ef23d7aeb8. --- docs/reference/search/uri-request.asciidoc | 198 +++++++++------------ 1 file changed, 88 insertions(+), 110 deletions(-) diff --git a/docs/reference/search/uri-request.asciidoc b/docs/reference/search/uri-request.asciidoc index 86e2ee4551b..d4f058f3c4d 100644 --- a/docs/reference/search/uri-request.asciidoc +++ b/docs/reference/search/uri-request.asciidoc @@ -1,7 +1,10 @@ [[search-uri-request]] === URI Search -Specifies search criteria as query parameters in the request URI. +A search request can be executed purely using a URI by providing request +parameters. Not all search options are exposed when executing a search +using this mode, but it can be handy for quick "curl tests". Here is an +example: [source,js] -------------------------------------------------- @@ -10,115 +13,7 @@ GET twitter/_search?q=user:kimchy // CONSOLE // TEST[setup:twitter] - -[[search-uri-request-api-request]] -==== {api-request-title} - -`GET //_search?q=` - - -[[search-uri-request-api-desc]] -==== {api-description-title} - -You can use query parameters to define your search criteria directly in the -request URI, rather than in the request body. Request URI searches do not -support the full {es} Query DSL, but are handy for testing. - - -[[search-uri-request-api-path-params]] -==== {api-path-parms-title} - -include::{docdir}/rest-api/common-parms.asciidoc[tag=index] - - -[[search-uri-request-api-query-params]] -==== {api-query-parms-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. - -include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard] - -include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer] - -`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. - -include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator] - -include::{docdir}/rest-api/common-parms.asciidoc[tag=df] - -`explain`:: - (Optional, string) For each hit, include an explanation of how the score was - computed. - -include::{docdir}/rest-api/common-parms.asciidoc[tag=from] - -include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient] - -include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q] - -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=source] - -include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes] - -include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes] - -`stored_fields`:: - (Optional, string) The selective stored fields of the document to return for - each hit, comma delimited. Not specifying any value will cause no fields to - return. - -`sort`:: - (Optional, string) Sorting to perform. Can either be in the form of - `fieldName`, or `fieldName:asc`/`fieldName:desc`. The fieldName can either be - an actual field within the document, or the special `_score` name to indicate - sorting based on scores. There can be several `sort` parameters (order is - important). - -`track_scores`:: - (Optional, boolean) When sorting, set to `true` in order to still track scores - and return them as part of each hit. - -`track_total_hits`:: - (Optional, integer) Defaults to `10,000`. Set to `false` in order to disable - the tracking of the total number of hits that match the query. It also accepts - an integer which in this case represents the number of hits to count - accurately. (See the <> - documentation for more details). - -`timeout`:: - (Optional, <>) A search timeout, bounding the search - request to be executed within the specified time value and bail with the hits - accumulated up to that point when expired. Defaults to no timeout. - -include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after] - - -[[search-uri-request-api-example]] -==== {api-examples-title} - -[source,js] --------------------------------------------------- -GET twitter/_search?q=user:kimchy --------------------------------------------------- -// CONSOLE -// TEST[setup:twitter] - - -The API returns the following response: +And here is a sample response: [source,js] -------------------------------------------------- @@ -155,3 +50,86 @@ The API returns the following response: } -------------------------------------------------- // TESTRESPONSE[s/"took": 62/"took": "$body.took"/] + +[float] +==== Parameters + +The parameters allowed in the URI are: + +[cols="<,<",options="header",] +|======================================================================= +|Name |Description +|`q` |The query string (maps to the `query_string` query, see +<> for more details). + +|`df` |The default field to use when no field prefix is defined within the +query. + +|`analyzer` |The analyzer name to be used when analyzing the query string. + +|`analyze_wildcard` |Should wildcard and prefix queries be analyzed or +not. Defaults to `false`. + +|`batched_reduce_size` | 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. + +|`default_operator` |The default operator to be used, can be `AND` or +`OR`. Defaults to `OR`. + +|`lenient` |If set to true will cause format based failures (like +providing text to a numeric field) to be ignored. Defaults to false. + +|`explain` |For each hit, contain an explanation of how scoring of the +hits was computed. + +|`_source`|Set to `false` to disable retrieval of the `_source` field. You can also retrieve +part of the document by using `_source_includes` & `_source_excludes` (see the <> +documentation for more details) + +|`stored_fields` |The selective stored fields of the document to return for each hit, +comma delimited. Not specifying any value will cause no fields to return. + +|`sort` |Sorting to perform. Can either be in the form of `fieldName`, or +`fieldName:asc`/`fieldName:desc`. The fieldName can either be an actual +field within the document, or the special `_score` name to indicate +sorting based on scores. There can be several `sort` parameters (order +is important). + +|`track_scores` |When sorting, set to `true` in order to still track +scores and return them as part of each hit. + +|`track_total_hits` |Defaults to `10,000`. Set to `false` in order to disable the tracking +of the total number of hits that match the query. +It also accepts an integer which in this case represents the number of +hits to count accurately. +(See the <> documentation +for more details). + +|`timeout` |A search timeout, bounding the search request to be executed +within the specified time value and bail with the hits accumulated up to +that point when expired. Defaults to no timeout. + +|`terminate_after` |The maximum number of documents to collect for +each shard, upon reaching which the query execution will terminate early. +If set, the response will have a boolean field `terminated_early` to +indicate whether the query execution has actually terminated_early. +Defaults to no terminate_after. + +|`from` |The starting from index of the hits to return. Defaults to `0`. + +|`size` |The number of hits to return. Defaults to `10`. + +|`search_type` |The type of the search operation to perform. Can be +`dfs_query_then_fetch` or `query_then_fetch`. +Defaults to `query_then_fetch`. See +<> for +more details on the different types of search that can be performed. + +|`allow_partial_search_results` |Set to `false` to return an overall failure if the request would produce +partial results. Defaults to true, which will allow partial results in the case of timeouts +or partial failures. This default can be controlled using the cluster-level setting +`search.default_allow_partial_results`. +|=======================================================================