mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-02 17:09:18 +00:00
da89ff87bb
Changes: * Removes narrative around URI searches. These aren't commonly used in production. The `q` param is already covered in the search API docs: https://www.elastic.co/guide/en/elasticsearch/reference/master/search-search.html#search-api-query-params-q * Adds a common options section that highlights narrative docs for query DSL, aggregations, multi-index search, search fields, pagination, sorting, and async search. * Adds a `Search shard routing` page. Moves narrative docs for adaptive replica selection, preference, routing , and shard limits to that section. * Moves search timeout and cancellation content to the `Search your data` page. * Creates a `Search multiple data streams and indices` page. Moves related narrative docs for multi-target syntax searches and `indices_boost` to that page. * Removes narrative examples for the `search_type` parameters. Moves documentation for this parameter to the search API docs.
223 lines
7.2 KiB
Plaintext
223 lines
7.2 KiB
Plaintext
[[search-your-data]]
|
|
= Search your data
|
|
|
|
[[search-query]]
|
|
A _search query_, or _query_, is a request for information about data in
|
|
{es} data streams or indices.
|
|
|
|
You can think of a query as a question, written in a way {es} understands.
|
|
Depending on your data, you can use a query to get answers to questions like:
|
|
|
|
* What processes on my server take longer than 500 milliseconds to respond?
|
|
* What users on my network ran `regsvr32.exe` within the last week?
|
|
* What pages on my website contain a specific word or phrase?
|
|
|
|
A _search_ consists of one or more queries that are combined and sent to {es}.
|
|
Documents that match a search's queries are returned in the _hits_, or
|
|
_search results_, of the response.
|
|
|
|
A search may also contain additional information used to better process its
|
|
queries. For example, a search may be limited to a specific index or only return
|
|
a specific number of results.
|
|
|
|
[discrete]
|
|
[[run-an-es-search]]
|
|
== Run a search
|
|
|
|
You can use the <<search-search,search API>> to search and
|
|
<<search-aggregations,aggregate>> data stored in {es} data streams or indices.
|
|
The API's `query` request body parameter accepts queries written in
|
|
<<query-dsl,Query DSL>>.
|
|
|
|
The following request searches `my-index-000001` using a
|
|
<<query-dsl-match-query,`match`>> query. This query matches documents with a
|
|
`user.id` value of `kimchy`.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my-index-000001/_search
|
|
{
|
|
"query": {
|
|
"match": {
|
|
"user.id": "kimchy"
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[setup:my_index]
|
|
|
|
The API response returns the top 10 documents matching the query in the
|
|
`hits.hits` property.
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"took": 5,
|
|
"timed_out": false,
|
|
"_shards": {
|
|
"total": 1,
|
|
"successful": 1,
|
|
"skipped": 0,
|
|
"failed": 0
|
|
},
|
|
"hits": {
|
|
"total": {
|
|
"value": 1,
|
|
"relation": "eq"
|
|
},
|
|
"max_score": 1.3862942,
|
|
"hits": [
|
|
{
|
|
"_index": "my-index-000001",
|
|
"_type": "_doc",
|
|
"_id": "kxWFcnMByiguvud1Z8vC",
|
|
"_score": 1.3862942,
|
|
"_source": {
|
|
"@timestamp": "2099-11-15T14:12:12",
|
|
"http": {
|
|
"request": {
|
|
"method": "get"
|
|
},
|
|
"response": {
|
|
"bytes": 1070000,
|
|
"status_code": 200
|
|
},
|
|
"version": "1.1"
|
|
},
|
|
"message": "GET /search HTTP/1.1 200 1070000",
|
|
"source": {
|
|
"ip": "127.0.0.1"
|
|
},
|
|
"user": {
|
|
"id": "kimchy"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"took": 5/"took": "$body.took"/]
|
|
// TESTRESPONSE[s/"_id": "kxWFcnMByiguvud1Z8vC"/"_id": "$body.hits.hits.0._id"/]
|
|
|
|
[discrete]
|
|
[[common-search-options]]
|
|
=== Common search options
|
|
|
|
You can use the following options to customize your searches.
|
|
|
|
*Query DSL* +
|
|
<<query-dsl,Query DSL>> supports a variety of query types you can mix and match
|
|
to get the results you want. Query types include:
|
|
|
|
* <<query-dsl-bool-query,Boolean>> and other <<compound-queries,compound
|
|
queries>>, which let you combine queries and match results based on multiple
|
|
criteria
|
|
* <<term-level-queries,Term-level queries>> for filtering and finding exact matches
|
|
* <<full-text-queries,Full text queries>>, which are commonly used in search
|
|
engines
|
|
* <<geo-queries,Geo>> and <<shape-queries,spatial queries>>
|
|
|
|
*Aggregations* +
|
|
You can use <<search-aggregations,search aggregations>> to get statistics and
|
|
other analytics for your search results. Aggregations help you answer questions
|
|
like:
|
|
|
|
* What's the average response time for my servers?
|
|
* What are the top IP addresses hit by users on my network?
|
|
* What is the total transaction revenue by customer?
|
|
|
|
*Search multiple data streams and indices* +
|
|
You can use comma-separated values and grep-like index patterns to search
|
|
several data streams and indices in the same request. You can even boost search
|
|
results from specific indices. See <<search-multiple-indices>>.
|
|
|
|
*Paginate search results* +
|
|
By default, searches return only the top 10 matching hits. To retrieve
|
|
more or fewer documents, see <<paginate-search-results>>.
|
|
|
|
*Retrieve selected fields* +
|
|
The search response's `hit.hits` property includes the full document
|
|
<<mapping-source-field,`_source`>> for each hit. To retrieve only a subset of
|
|
the `_source` or other fields, see <<search-fields>>.
|
|
|
|
*Sort search results* +
|
|
By default, search hits are sorted by `_score`, a <<relevance-scores,relevance
|
|
score>> that measures how well each document matches the query. To customize the
|
|
calculation of these scores, use the
|
|
<<query-dsl-script-score-query,`script_score`>> query. To sort search hits by
|
|
other field values, see <<sort-search-results>>.
|
|
|
|
*Run an async search* +
|
|
{es} searches are designed to run on large volumes of data quickly, often
|
|
returning results in milliseconds. For this reason, searches are
|
|
_synchronous_ by default. The search request waits for complete results before
|
|
returning a response.
|
|
|
|
However, complete results can take longer for searches across
|
|
<<frozen-indices,frozen indices>> or <<modules-cross-cluster-search,multiple
|
|
clusters>>.
|
|
|
|
To avoid long waits, you can use run an _asynchronous_, or _async_, search
|
|
instead. An <<async-search-intro,async search>> lets you retrieve partial
|
|
results for a long-running search now and get complete results later.
|
|
|
|
[discrete]
|
|
[[search-timeout]]
|
|
=== Search timeout
|
|
|
|
By default, search requests don't time out. The request waits for complete
|
|
results before returning a response.
|
|
|
|
While <<async-search-intro,async search>> is designed for long-running
|
|
searches, you can also use the `timeout` parameter to specify a duration you'd
|
|
like to wait for a search to complete. If no response is received before this
|
|
period ends, the request fails and returns an error.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my-index-000001/_search
|
|
{
|
|
"timeout": "2s",
|
|
"query": {
|
|
"match": {
|
|
"user.id": "kimchy"
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[setup:my_index]
|
|
|
|
To set a cluster-wide default timeout for all search requests, configure
|
|
`search.default_search_timeout` using the <<cluster-update-settings,cluster
|
|
settings API>>. This global timeout duration is used if no `timeout` argument is
|
|
passed in the request. If the global search timeout expires before the search
|
|
request finishes, the request is cancelled using <<task-cancellation,task
|
|
cancellation>>. The `search.default_search_timeout` setting defaults to `-1` (no
|
|
timeout).
|
|
|
|
[discrete]
|
|
[[global-search-cancellation]]
|
|
=== Search cancellation
|
|
|
|
You can cancel a search request using the <<task-cancellation,task management
|
|
API>>. {es} also automatically cancels a search request when your client's HTTP
|
|
connection closes. We recommend you set up your client to close HTTP connections
|
|
when a search request is aborted or times out.
|
|
|
|
include::request/track-total-hits.asciidoc[]
|
|
include::quickly-check-for-matching-docs.asciidoc[]
|
|
|
|
include::request/collapse.asciidoc[]
|
|
include::filter-search-results.asciidoc[]
|
|
include::request/highlighting.asciidoc[]
|
|
include::{es-repo-dir}/async-search.asciidoc[]
|
|
include::{es-repo-dir}/search/near-real-time.asciidoc[]
|
|
include::paginate-search-results.asciidoc[]
|
|
include::request/inner-hits.asciidoc[]
|
|
include::search-fields.asciidoc[]
|
|
include::{es-repo-dir}/modules/cross-cluster-search.asciidoc[]
|
|
include::search-multiple-indices.asciidoc[]
|
|
include::search-shard-routing.asciidoc[]
|
|
include::request/sort.asciidoc[]
|