diff --git a/docs/reference/search/uri-request.asciidoc b/docs/reference/search/uri-request.asciidoc index d4f058f3c4d..86e2ee4551b 100644 --- a/docs/reference/search/uri-request.asciidoc +++ b/docs/reference/search/uri-request.asciidoc @@ -1,10 +1,7 @@ [[search-uri-request]] === URI Search -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: +Specifies search criteria as query parameters in the request URI. [source,js] -------------------------------------------------- @@ -13,7 +10,115 @@ GET twitter/_search?q=user:kimchy // CONSOLE // TEST[setup:twitter] -And here is a sample response: + +[[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: [source,js] -------------------------------------------------- @@ -50,86 +155,3 @@ And here is a sample 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`. -|=======================================================================