mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-06 21:18:31 +00:00
156393be0e
This tracks the snippets that probably should be converted to `// CONSOLE` or `// TESTRESPONSE` and fails the build if the list of files with such snippets doesn't match the list in `docs/build.gradle`. Setting the file looks like ``` /* List of files that have snippets that probably should be converted to * `// CONSOLE` and `// TESTRESPONSE` but have yet to be converted. Try and * only remove entries from this list. When it is empty we'll remove it * entirely and have a party! There will be cake and everything.... */ buildRestTests.expectedUnconvertedCandidates = [ 'plugins/discovery-azure-classic.asciidoc', ... 'reference/search/suggesters/completion-suggest.asciidoc', ] ``` This list is in `build.gradle` because we expect it to be fairly temporary. In a few months we'll have converted all of the docs and won't ned it any more. From now on if you add now docs that contain a snippet that shows an interaction with elasticsearch you have three choices: 1. Stick `// CONSOLE` on the interactions and `// TESTRESPONSE` on the responses. The build (specifically (`gradle docs:check`) will test that these interactions "work". If there isn't a `// TESTRESPONSE` snippet then "work" just means "Elasticsearch responds with a 200-level response code and no `WARNING` headers. This is way better than nothing. 2. Add `// NOTCONSOLE` if the snippet isn't actually interacting with Elasticsearch. This should only be required for stuff like javascript source code or `curl` against an external service like AWS or GCE. The snippet will not get "OPEN IN CONSOLE" or "COPY AS CURL" buttons or be tested. 3. Add `// TEST[skip:reason]` under the snippet. This will just skip the snippet in the test phase. This should really be reserved for snippets where we can't test them because they require an external service that we don't have at testing time. Please, please, please, please don't add more things to the list. After all, it sais there'll be cake when we remove it entirely! Relates to #18160
122 lines
3.2 KiB
Plaintext
122 lines
3.2 KiB
Plaintext
[[search]]
|
|
= Search APIs
|
|
|
|
[partintro]
|
|
--
|
|
|
|
Most search APIs are <<search-multi-index-type,multi-index, multi-type>>, with the
|
|
exception of the <<search-explain>> endpoints.
|
|
|
|
[float]
|
|
[[search-routing]]
|
|
== Routing
|
|
|
|
When executing a search, it will be broadcast to all the index/indices
|
|
shards (round robin between replicas). Which shards will be searched on
|
|
can be controlled by providing the `routing` parameter. For example,
|
|
when indexing tweets, the routing value can be the user name:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /twitter/tweet?routing=kimchy
|
|
{
|
|
"user" : "kimchy",
|
|
"postDate" : "2009-11-15T14:12:12",
|
|
"message" : "trying out Elasticsearch"
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
|
|
In such a case, if we want to search only on the tweets for a specific
|
|
user, we can specify it as the routing, resulting in the search hitting
|
|
only the relevant shard:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /twitter/tweet/_search?routing=kimchy
|
|
{
|
|
"query": {
|
|
"bool" : {
|
|
"must" : {
|
|
"query_string" : {
|
|
"query" : "some query string here"
|
|
}
|
|
},
|
|
"filter" : {
|
|
"term" : { "user" : "kimchy" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[continued]
|
|
|
|
The routing parameter can be multi valued represented as a comma
|
|
separated string. This will result in hitting the relevant shards where
|
|
the routing values match to.
|
|
|
|
[float]
|
|
[[stats-groups]]
|
|
== Stats Groups
|
|
|
|
A search can be associated with stats groups, which maintains a
|
|
statistics aggregation per group. It can later be retrieved using the
|
|
<<indices-stats,indices stats>> API
|
|
specifically. For example, here is a search body request that associate
|
|
the request with two different groups:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
POST /_search
|
|
{
|
|
"query" : {
|
|
"match_all" : {}
|
|
},
|
|
"stats" : ["group1", "group2"]
|
|
}
|
|
--------------------------------------------------
|
|
// CONSOLE
|
|
// TEST[setup:twitter]
|
|
|
|
[float]
|
|
[[global-search-timeout]]
|
|
== Global Search Timeout
|
|
|
|
Individual searches can have a timeout as part of the
|
|
<<search-request-body>>. Since search requests can originate from many
|
|
sources, Elasticsearch has a dynamic cluster-level setting for a global
|
|
search timeout that applies to all search requests that do not set a
|
|
timeout in the <<search-request-body>>. The default value is no global
|
|
timeout. The setting key is `search.default_search_timeout` and can be
|
|
set using the <<cluster-update-settings>> endpoints. Setting this value
|
|
to `-1` resets the global search timeout to no timeout.
|
|
|
|
--
|
|
|
|
include::search/search.asciidoc[]
|
|
|
|
include::search/uri-request.asciidoc[]
|
|
|
|
include::search/request-body.asciidoc[]
|
|
|
|
include::search/search-template.asciidoc[]
|
|
|
|
include::search/search-shards.asciidoc[]
|
|
|
|
include::search/suggesters.asciidoc[]
|
|
|
|
include::search/multi-search.asciidoc[]
|
|
|
|
include::search/count.asciidoc[]
|
|
|
|
include::search/validate.asciidoc[]
|
|
|
|
include::search/explain.asciidoc[]
|
|
|
|
include::search/profile.asciidoc[]
|
|
|
|
include::search/percolate.asciidoc[]
|
|
|
|
include::search/field-stats.asciidoc[]
|