Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOCS] Reformats URI search request #45844

Merged
merged 12 commits into from Aug 29, 2019
Merged

[DOCS] Reformats URI search request #45844

Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
607f447
[DOCS] Reformats URI search request.
szabosteve Aug 22, 2019
ec07540
Update docs/reference/search/uri-request.asciidoc
szabosteve Aug 26, 2019
f4fb2d0
Update docs/reference/search/uri-request.asciidoc
szabosteve Aug 28, 2019
cfa037c
Update docs/reference/search/uri-request.asciidoc
szabosteve Aug 28, 2019
89fe8f1
Update docs/reference/search/uri-request.asciidoc
szabosteve Aug 28, 2019
5ef5a45
Update docs/reference/search/uri-request.asciidoc
szabosteve Aug 28, 2019
d7c6b7a
Update docs/reference/search/uri-request.asciidoc
szabosteve Aug 28, 2019
edeed21
Update docs/reference/search/uri-request.asciidoc
szabosteve Aug 28, 2019
5baa069
Update docs/reference/search/uri-request.asciidoc
szabosteve Aug 28, 2019
2464829
[DOCS] Addresses feedback.
szabosteve Aug 28, 2019
bfa656e
[DOCS] Addresses feedback pt. 2.
szabosteve Aug 28, 2019
7ae5fc8
[DOCS] Uses search-related common param tags.
szabosteve Aug 28, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
198 changes: 110 additions & 88 deletions docs/reference/search/uri-request.asciidoc
View file
Open in desktop
@@ -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.

szabosteve marked this conversation as resolved.
Show resolved Hide resolved
[source,js]
--------------------------------------------------
Expand All @@ -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 /<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]


szabosteve marked this conversation as resolved.
Show resolved Hide resolved
[[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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of "return an overall failure" I'd probably just say "fail the request if only partial results are available." I'd stick with the present tense for the following sentence, too: "Defaults to true, which returns partial results in the event of
timeouts or partial failures." I'd probably also use "override" instead of "control"--maybe, "You can override the default behavior for all requests by setting search.default_allow_partial_results to false in the cluster settings."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why I really came here is...do we want to add all of the search-related query parameters to the common parameters? They apply to the search API, delete by query, and update by query.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@debadair @jrodewig I think it's worth to add the search-related query parameters to the common parameters. I'll do it in a separate PR and add both of you as reviewers.

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]
--------------------------------------------------
Expand Down Expand Up @@ -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
<<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`.
|=======================================================================