[DOCS] Reformats URI search request (#45844)
* [DOCS] Reformats URI search request. Co-Authored-By: James Rodewig <james.rodewig@elastic.co> Co-Authored-By: debadair <debadair@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
0425f6a327
commit
7f11c32400
|
|
@ -1,10 +1,7 @@
|
||||||
[[search-uri-request]]
|
[[search-uri-request]]
|
||||||
=== URI Search
|
=== URI Search
|
||||||
|
|
||||||
A search request can be executed purely using a URI by providing request
|
Specifies search criteria as query parameters in the request URI.
|
||||||
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]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
@ -13,7 +10,115 @@ GET twitter/_search?q=user:kimchy
|
||||||
// CONSOLE
|
// CONSOLE
|
||||||
// TEST[setup:twitter]
|
// TEST[setup:twitter]
|
||||||
|
|
||||||
And here is a sample response:
|
|
||||||
|
[[search-uri-request-api-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`GET /<index>/_search?q=<parameter>`
|
||||||
|
|
||||||
|
|
||||||
|
[[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 <<request-body-search-track-total-hits, request body>>
|
||||||
|
documentation for more details).
|
||||||
|
|
||||||
|
`timeout`::
|
||||||
|
(Optional, <<time-units, time units>>) 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]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
@ -50,86 +155,3 @@ And here is a sample response:
|
||||||
}
|
}
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// TESTRESPONSE[s/"took": 62/"took": "$body.took"/]
|
// 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
|
|
||||||
<<query-dsl-query-string-query,_Query String
|
|
||||||
Query_>> 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 <<request-body-search-source-filtering, request body>>
|
|
||||||
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 <<request-body-search-track-total-hits, request body>> 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
|
|
||||||
<<request-body-search-search-type,_Search Type_>> 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`.
|
|
||||||
|=======================================================================
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue