diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 53b15703049d..9bc5e3c8b51e 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -493,3 +493,8 @@ See <>. === {ilm-init} policy definition See <>. + +[role="exclude",id="search-uri-request"] +=== URI Search + +See <>. \ No newline at end of file diff --git a/docs/reference/search.asciidoc b/docs/reference/search.asciidoc index 606a19dc14ad..045f39df3e66 100644 --- a/docs/reference/search.asciidoc +++ b/docs/reference/search.asciidoc @@ -154,8 +154,6 @@ include::search/search.asciidoc[] include::search/async-search.asciidoc[] -include::search/uri-request.asciidoc[] - include::search/request-body.asciidoc[] include::search/search-template.asciidoc[] diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc index 0723000b184d..9fddf28bdd61 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -1,48 +1,40 @@ [[search-search]] -=== Search +=== Search API +++++ +Search +++++ Returns search hits that match the query defined in the request. [source,console] ---- -GET /twitter/_search?q=tag:wow +GET /twitter/_search ---- // TEST[setup:twitter] - [[search-search-api-request]] ==== {api-request-title} `GET //_search` -`POST //_search` - `GET /_search` -`POST /_search` +`POST //_search` +`POST /_search` [[search-search-api-desc]] ==== {api-description-title} Allows you to execute a search query and get back search hits that match the -query. The query can either be provided using a simple -<>, or using a -<>. - -[[search-partial-responses]] -===== Partial responses - -To ensure fast responses, the search API will respond with partial results if -one or more shards fail. See <> for more -information. +query. You can provide search queries using the <> or <>. [[search-search-api-path-params]] ==== {api-path-parms-title} include::{docdir}/rest-api/common-parms.asciidoc[tag=index] - [[search-search-api-query-params]] ==== {api-query-parms-title} @@ -50,16 +42,15 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + Defaults to `true`. +[[search-partial-responses]] `allow_partial_search_results`:: - (Optional, boolean) Indicates if an error should be returned if there is a - partial search failure or timeout. Defaults to `true`. - -`analyzer`:: - (Optional, string) Defines the analyzer to use for the query string. - -`analyze_wildcard`:: - (Optional, boolean) If `true`, wildcard and prefix queries will also be - analyzed. Defaults to `false`. +(Optional, boolean) +If `true`, returns partial results if there are request timeouts or +<>. If `false`, returns an error with +no partial results. Defaults to `true`. ++ +To override the default for this field, set the +`search.default_allow_partial_results` cluster setting to `false`. `batched_reduce_size`:: (Optional, integer) The number of shard results that should be reduced at once @@ -71,14 +62,6 @@ Defaults to `true`. (Optional, boolean) Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution. Defaults to `true`. -`default_operator`:: - (Optional, string) The default operator for query string query (AND or OR). - Defaults to `OR`. - -`df`:: - (Optional, string) Defines the field to use as default where no field prefix - is given in the query string. - `docvalue_fields`:: (Optional, string) A comma-separated list of fields to return as the docvalue representation of a field for each hit. @@ -91,8 +74,7 @@ Defaults to `open`. (Optional, boolean) If `true`, returns detailed information about score computation as part of a hit. Defaults to `false`. -`from`:: - (Optional, integer) Defines the starting offset. Defaults to `0`. +include::{docdir}/rest-api/common-parms.asciidoc[tag=from] `ignore_throttled`:: (Optional, boolean) If `true`, concrete, expanded or aliased indices will be @@ -100,10 +82,6 @@ Defaults to `open`. include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] -`lenient`:: - (Optional, boolean) If `true`, format-based query failures (such as - providing text to a numeric field) will be ignored. Defaults to `false`. - `max_concurrent_shard_requests`:: (Optional, integer) Defines the number of concurrent shard requests per node this search executes concurrently. This value should be used to limit the @@ -127,8 +105,20 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] performed on. Random by default. [[search-api-query-params-q]] -`q`:: - (Optional, string) Query in the Lucene query string syntax. +include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q] ++ +-- +You can use the `q` parameter to run a query parameter search. Query parameter +searches do not support the full {es} <> but are handy for +testing. + +[IMPORTANT] +==== +The `q` parameter overrides the <> +parameter in the request body. If both parameters are specified, documents +matching the `query` request body parameter are not returned. +==== +-- `request_cache`:: (Optional, boolean) If `true`, request cache will be used for this request. @@ -142,11 +132,7 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] (Optional, <>) Specifies how long a consistent view of the index should be maintained for scrolled search. -`search_type`:: - (Optional, string) Defines the type of the search operation. Available - options: - * `query_then_fetch` - * `dfs_query_then_fetch` +include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type] `seq_no_primary_term`:: (Optional, boolean) If `true`, returns sequence number and primary term of the @@ -159,16 +145,13 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] (Optional, string) A comma-separated list of : pairs. `_source`:: - (Optional, string) True or false to return the `_source` field or not, or a - list of fields to return. +(Optional, boolean) +If `true`, the response includes the `_source` of matching documents under +`hits`. Defaults to `true`. -`_source_excludes`:: - (Optional, string) A list of fields to exclude from the returned `_source` - field. +include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes] -`_source_includes`:: - (Optional, string) A list of fields to extract and return from the `_source` - field. +include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes] `stats`:: (Optional, string) Specific `tag` of the request for logging and statistical @@ -176,28 +159,19 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] `stored_fields`:: (Optional, string) A comma-separated list of stored fields to return as part - of a hit. + of a hit. If no fields are specified, no stored fields are included in the + response. `suggest_field`:: (Optional, string) Specifies which field to use for suggestions. -`suggest_mode`:: - (Optional, string) Specifies suggest mode. Defaults to `missing`. Available - options: - * `always` - * `missing` - * `popular` - -`suggest_size`:: - (Optional, integer) Defines how many suggestions to return in response. - `suggest_text`:: (Optional, string) The source text for which the suggestions should be returned. -`terminate_after`:: - (Optional, integer) The maximum number of documents to collect for each shard, - upon reaching which the query execution will terminate early. +include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after] ++ +Defaults to `0`, which does not terminate query execution early. `timeout`:: (Optional, <>) Specifies the period of time to wait @@ -205,19 +179,23 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] request fails and returns an error. Defaults to no timeout. `track_scores`:: - (Optional, boolean) If `true`, then calculates and returns scores even if they - are not used for sorting. + (Optional, boolean) If `true`, calculate and return document scores, even if + the scores are not used for sorting. Defaults to `false`. `track_total_hits`:: - (Optional, boolean) Indicates if the number of documents that match the query - should be tracked. + (Optional, integer or boolean) + Number of hits matching the query to count accurately. Defaults to `10,000`. + + + If `true`, the default value is used. If `false`, the response does not + include the total number of hits matching the query. `typed_keys`:: - (Optional, boolean) Specifies whether aggregation and suggester names should - be prefixed by their respective types in the response. + (Optional, boolean) If `true`, aggregation and suggester names are be prefixed + by their respective types in the response. Defaults to `true`. `version`:: - (Optional, boolean) If `true`, returns document version as part of a hit. + (Optional, boolean) + If `true`, returns document version as part of a hit. Defaults to `false. [[search-search-api-request-body]] @@ -364,7 +342,7 @@ Original JSON body passed for the document at index time. ==== {api-examples-title} [[search-api-specific-ex]] -===== Search a specific index +===== Search an index using the `q` query parameter [source,console] ---- @@ -410,7 +388,7 @@ The API returns the following response: // TESTRESPONSE[s/"took" : 5/"took": $body.took/] [[search-multi-index]] -===== Search several indices +===== Search several indices using the `q` query parameter [source,console] ---- @@ -419,7 +397,7 @@ GET /kimchy,elasticsearch/_search?q=user:kimchy // TEST[s/^/PUT kimchy\nPUT elasticsearch\n/] [[search-api-all-ex]] -===== Search all indices +===== Search all indices using the `q` query parameter To search all indices in a cluster, omit the `` parameter. diff --git a/docs/reference/search/uri-request.asciidoc b/docs/reference/search/uri-request.asciidoc deleted file mode 100644 index 695c4a6ada11..000000000000 --- a/docs/reference/search/uri-request.asciidoc +++ /dev/null @@ -1,154 +0,0 @@ -[[search-uri-request]] -=== URI Search - -Specifies search criteria as query parameters in the request URI. - -[source,console] --------------------------------------------------- -GET twitter/_search?q=user:kimchy --------------------------------------------------- -// 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,console] --------------------------------------------------- -GET twitter/_search?q=user:kimchy --------------------------------------------------- -// TEST[setup:twitter] - - -The API returns the following response: - -[source,console-result] --------------------------------------------------- -{ - "timed_out": false, - "took": 62, - "_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", - "date" : "2009-11-15T14:12:12", - "message" : "trying out Elasticsearch", - "likes": 0 - } - } - ] - } -} --------------------------------------------------- -// TESTRESPONSE[s/"took": 62/"took": "$body.took"/]