Skip to content

Commit 4d169fa

Browse files
szabostevedebadair
authored and
jkakavas
committed
[DOCS] Reformats URI search request (elastic#45844)
* [DOCS] Reformats URI search request. Co-Authored-By: James Rodewig <[email protected]> Co-Authored-By: debadair <[email protected]>
1 parent 27023b5 commit 4d169fa

File tree

1 file changed

+110
-88
lines changed

1 file changed

+110
-88
lines changed

‎docs/reference/search/uri-request.asciidoc

Lines changed: 110 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,7 @@
11
[[search-uri-request]]
22
=== URI Search
33

4-
A search request can be executed purely using a URI by providing request
5-
parameters. Not all search options are exposed when executing a search
6-
using this mode, but it can be handy for quick "curl tests". Here is an
7-
example:
4+
Specifies search criteria as query parameters in the request URI.
85

96
[source,js]
107
--------------------------------------------------
@@ -13,7 +10,115 @@ GET twitter/_search?q=user:kimchy
1310
// CONSOLE
1411
// TEST[setup:twitter]
1512

16-
And here is a sample response:
13+
14+
[[search-uri-request-api-request]]
15+
==== {api-request-title}
16+
17+
`GET /<index>/_search?q=<parameter>`
18+
19+
20+
[[search-uri-request-api-desc]]
21+
==== {api-description-title}
22+
23+
You can use query parameters to define your search criteria directly in the
24+
request URI, rather than in the request body. Request URI searches do not
25+
support the full {es} Query DSL, but are handy for testing.
26+
27+
28+
[[search-uri-request-api-path-params]]
29+
==== {api-path-parms-title}
30+
31+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
32+
33+
34+
[[search-uri-request-api-query-params]]
35+
==== {api-query-parms-title}
36+
37+
`allow_partial_search_results`::
38+
(Optional, boolean) Set to `false` to fail the request if only partial results
39+
are available. Defaults to `true`, which returns partial results in the event
40+
of timeouts or partial failures You can override the default behavior for all
41+
requests by setting `search.default_allow_partial_results` to `false` in the
42+
cluster settings.
43+
44+
include::{docdir}/rest-api/common-parms.asciidoc[tag=analyze_wildcard]
45+
46+
include::{docdir}/rest-api/common-parms.asciidoc[tag=analyzer]
47+
48+
`batched_reduce_size`::
49+
(Optional, integer) The number of shard results that should be reduced at once
50+
on the coordinating node. This value should be used as a protection mechanism
51+
to reduce the memory overhead per search request if the potential number of
52+
shards in the request can be large.
53+
54+
include::{docdir}/rest-api/common-parms.asciidoc[tag=default_operator]
55+
56+
include::{docdir}/rest-api/common-parms.asciidoc[tag=df]
57+
58+
`explain`::
59+
(Optional, string) For each hit, include an explanation of how the score was
60+
computed.
61+
62+
include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
63+
64+
include::{docdir}/rest-api/common-parms.asciidoc[tag=lenient]
65+
66+
include::{docdir}/rest-api/common-parms.asciidoc[tag=search-q]
67+
68+
include::{docdir}/rest-api/common-parms.asciidoc[tag=search_type]
69+
70+
`size`::
71+
(Optional, integer) The number of hits to return. Defaults to `10`.
72+
73+
include::{docdir}/rest-api/common-parms.asciidoc[tag=source]
74+
75+
include::{docdir}/rest-api/common-parms.asciidoc[tag=source_excludes]
76+
77+
include::{docdir}/rest-api/common-parms.asciidoc[tag=source_includes]
78+
79+
`stored_fields`::
80+
(Optional, string) The selective stored fields of the document to return for
81+
each hit, comma delimited. Not specifying any value will cause no fields to
82+
return.
83+
84+
`sort`::
85+
(Optional, string) Sorting to perform. Can either be in the form of
86+
`fieldName`, or `fieldName:asc`/`fieldName:desc`. The fieldName can either be
87+
an actual field within the document, or the special `_score` name to indicate
88+
sorting based on scores. There can be several `sort` parameters (order is
89+
important).
90+
91+
`track_scores`::
92+
(Optional, boolean) When sorting, set to `true` in order to still track scores
93+
and return them as part of each hit.
94+
95+
`track_total_hits`::
96+
(Optional, integer) Defaults to `10,000`. Set to `false` in order to disable
97+
the tracking of the total number of hits that match the query. It also accepts
98+
an integer which in this case represents the number of hits to count
99+
accurately. (See the <<request-body-search-track-total-hits, request body>>
100+
documentation for more details).
101+
102+
`timeout`::
103+
(Optional, <<time-units, time units>>) A search timeout, bounding the search
104+
request to be executed within the specified time value and bail with the hits
105+
accumulated up to that point when expired. Defaults to no timeout.
106+
107+
include::{docdir}/rest-api/common-parms.asciidoc[tag=terminate_after]
108+
109+
110+
[[search-uri-request-api-example]]
111+
==== {api-examples-title}
112+
113+
[source,js]
114+
--------------------------------------------------
115+
GET twitter/_search?q=user:kimchy
116+
--------------------------------------------------
117+
// CONSOLE
118+
// TEST[setup:twitter]
119+
120+
121+
The API returns the following response:
17122

18123
[source,js]
19124
--------------------------------------------------
@@ -50,86 +155,3 @@ And here is a sample response:
50155
}
51156
--------------------------------------------------
52157
// TESTRESPONSE[s/"took": 62/"took": "$body.took"/]
53-
54-
[float]
55-
==== Parameters
56-
57-
The parameters allowed in the URI are:
58-
59-
[cols="<,<",options="header",]
60-
|=======================================================================
61-
|Name |Description
62-
|`q` |The query string (maps to the `query_string` query, see
63-
<<query-dsl-query-string-query,_Query String
64-
Query_>> for more details).
65-
66-
|`df` |The default field to use when no field prefix is defined within the
67-
query.
68-
69-
|`analyzer` |The analyzer name to be used when analyzing the query string.
70-
71-
|`analyze_wildcard` |Should wildcard and prefix queries be analyzed or
72-
not. Defaults to `false`.
73-
74-
|`batched_reduce_size` | The number of shard results that should be reduced
75-
at once on the coordinating node. This value should be used as a protection
76-
mechanism to reduce the memory overhead per search request if the potential
77-
number of shards in the request can be large.
78-
79-
|`default_operator` |The default operator to be used, can be `AND` or
80-
`OR`. Defaults to `OR`.
81-
82-
|`lenient` |If set to true will cause format based failures (like
83-
providing text to a numeric field) to be ignored. Defaults to false.
84-
85-
|`explain` |For each hit, contain an explanation of how scoring of the
86-
hits was computed.
87-
88-
|`_source`|Set to `false` to disable retrieval of the `_source` field. You can also retrieve
89-
part of the document by using `_source_includes` & `_source_excludes` (see the <<request-body-search-source-filtering, request body>>
90-
documentation for more details)
91-
92-
|`stored_fields` |The selective stored fields of the document to return for each hit,
93-
comma delimited. Not specifying any value will cause no fields to return.
94-
95-
|`sort` |Sorting to perform. Can either be in the form of `fieldName`, or
96-
`fieldName:asc`/`fieldName:desc`. The fieldName can either be an actual
97-
field within the document, or the special `_score` name to indicate
98-
sorting based on scores. There can be several `sort` parameters (order
99-
is important).
100-
101-
|`track_scores` |When sorting, set to `true` in order to still track
102-
scores and return them as part of each hit.
103-
104-
|`track_total_hits` |Defaults to `10,000`. Set to `false` in order to disable the tracking
105-
of the total number of hits that match the query.
106-
It also accepts an integer which in this case represents the number of
107-
hits to count accurately.
108-
(See the <<request-body-search-track-total-hits, request body>> documentation
109-
for more details).
110-
111-
|`timeout` |A search timeout, bounding the search request to be executed
112-
within the specified time value and bail with the hits accumulated up to
113-
that point when expired. Defaults to no timeout.
114-
115-
|`terminate_after` |The maximum number of documents to collect for
116-
each shard, upon reaching which the query execution will terminate early.
117-
If set, the response will have a boolean field `terminated_early` to
118-
indicate whether the query execution has actually terminated_early.
119-
Defaults to no terminate_after.
120-
121-
|`from` |The starting from index of the hits to return. Defaults to `0`.
122-
123-
|`size` |The number of hits to return. Defaults to `10`.
124-
125-
|`search_type` |The type of the search operation to perform. Can be
126-
`dfs_query_then_fetch` or `query_then_fetch`.
127-
Defaults to `query_then_fetch`. See
128-
<<request-body-search-search-type,_Search Type_>> for
129-
more details on the different types of search that can be performed.
130-
131-
|`allow_partial_search_results` |Set to `false` to return an overall failure if the request would produce
132-
partial results. Defaults to true, which will allow partial results in the case of timeouts
133-
or partial failures. This default can be controlled using the cluster-level setting
134-
`search.default_allow_partial_results`.
135-
|=======================================================================

0 commit comments

Comments
 (0)