mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-03-28 02:48:38 +00:00
**Goal** Create a top-level search section. This will let us clean up our search API reference docs, particularly content from [`Request body search`][0]. **Changes** * Creates a top-level `Search your data` page. This page is designed to house concept and tutorial docs related to search. * Creates a `Run a search` page under `Search your data`. For now, This contains a basic search tutorial. The goal is to add content from [`Request body search`][0] to this in the future. * Relocates `Long-running searches` and `Search across clusters` under `Search your data`. Increments several headings in that content. * Reorders the top-level TOC to move `Search your data` higher. Also moves the `Query DSL`, `EQL`, and `SQL access` chapters immediately after. Relates to #48194 [0]: https://www.elastic.co/guide/en/elasticsearch/reference/master/search-request-body.html
This commit is contained in:
James Rodewig
GitHub
parent
ceb4b29b98
commit
50a8779c94
docs/reference
@ -18,13 +18,17 @@ include::setup.asciidoc[]
|
||||
|
||||
include::upgrade.asciidoc[]
|
||||
|
||||
include::aggregations.asciidoc[]
|
||||
include::search/index.asciidoc[]
|
||||
|
||||
include::query-dsl.asciidoc[]
|
||||
|
||||
include::modules/cross-cluster-search.asciidoc[]
|
||||
ifdef::permanently-unreleased-branch[]
|
||||
include::eql/index.asciidoc[]
|
||||
endif::[]
|
||||
|
||||
include::async-search.asciidoc[]
|
||||
include::sql/index.asciidoc[]
|
||||
|
||||
include::aggregations.asciidoc[]
|
||||
|
||||
include::scripting.asciidoc[]
|
||||
|
||||
@ -42,12 +46,8 @@ ifdef::permanently-unreleased-branch[]
|
||||
|
||||
include::autoscaling/index.asciidoc[]
|
||||
|
||||
include::eql/index.asciidoc[]
|
||||
|
||||
endif::[]
|
||||
|
||||
include::sql/index.asciidoc[]
|
||||
|
||||
include::monitoring/index.asciidoc[]
|
||||
|
||||
include::frozen-indices.asciidoc[]
|
||||
|
||||
@ -1,6 +1,5 @@
|
||||
[chapter]
|
||||
[[modules-cross-cluster-search]]
|
||||
= Search across clusters
|
||||
== Search across clusters
|
||||
|
||||
*{ccs-cap}* lets you run a single search request against one or more
|
||||
<<modules-remote-clusters,remote clusters>>. For example, you can use a {ccs} to
|
||||
@ -10,7 +9,7 @@ IMPORTANT: {ccs-cap} requires <<modules-remote-clusters, remote clusters>>.
|
||||
|
||||
[float]
|
||||
[[ccs-supported-apis]]
|
||||
== Supported APIs
|
||||
=== Supported APIs
|
||||
|
||||
The following APIs support {ccs}:
|
||||
|
||||
@ -21,11 +20,11 @@ The following APIs support {ccs}:
|
||||
|
||||
[float]
|
||||
[[ccs-example]]
|
||||
== {ccs-cap} examples
|
||||
=== {ccs-cap} examples
|
||||
|
||||
[float]
|
||||
[[ccs-remote-cluster-setup]]
|
||||
=== Remote cluster setup
|
||||
==== Remote cluster setup
|
||||
|
||||
To perform a {ccs}, you must have at least one remote cluster configured.
|
||||
|
||||
@ -64,7 +63,7 @@ PUT _cluster/settings
|
||||
|
||||
[float]
|
||||
[[ccs-search-remote-cluster]]
|
||||
=== Search a single remote cluster
|
||||
==== Search a single remote cluster
|
||||
|
||||
The following <<search-search,search>> API request searches the
|
||||
`twitter` index on a single remote cluster, `cluster_one`.
|
||||
@ -133,7 +132,7 @@ The API returns the following response:
|
||||
|
||||
[float]
|
||||
[[ccs-search-multi-remote-cluster]]
|
||||
=== Search multiple remote clusters
|
||||
==== Search multiple remote clusters
|
||||
|
||||
The following <<search,search>> API request searches the `twitter` index on
|
||||
three clusters:
|
||||
@ -232,7 +231,7 @@ means the document came from the local cluster.
|
||||
|
||||
[float]
|
||||
[[skip-unavailable-clusters]]
|
||||
== Skip unavailable clusters
|
||||
=== Skip unavailable clusters
|
||||
|
||||
By default, a {ccs} returns an error if *any* cluster in the request is
|
||||
unavailable.
|
||||
@ -259,7 +258,7 @@ include matching documents from that cluster in the final results.
|
||||
|
||||
[discrete]
|
||||
[[ccs-gateway-seed-nodes]]
|
||||
== Selecting gateway and seed nodes in sniff mode
|
||||
=== Selecting gateway and seed nodes in sniff mode
|
||||
|
||||
For remote clusters using the <<sniff-mode,sniff connection>> mode, gateway and
|
||||
seed nodes need to be accessible from the local cluster via your network.
|
||||
@ -274,7 +273,7 @@ wanted, the seed nodes for a cluster can be a subset of these gateway nodes.
|
||||
|
||||
[discrete]
|
||||
[[ccs-proxy-mode]]
|
||||
== {ccs} in proxy mode
|
||||
=== {ccs} in proxy mode
|
||||
|
||||
<<proxy-mode,Proxy mode>> remote cluster connections support {ccs}. All remote
|
||||
connections connect to the configured `proxy_address`. Any desired connection
|
||||
@ -283,7 +282,7 @@ be implemented by the intermediate proxy at this configured address.
|
||||
|
||||
[discrete]
|
||||
[[ccs-network-delays]]
|
||||
== How {ccs} handles network delays
|
||||
=== How {ccs} handles network delays
|
||||
|
||||
Because {ccs} involves sending requests to remote clusters, any network delays
|
||||
can impact search speed. To avoid slow searches, {ccs} offers two options for
|
||||
@ -309,7 +308,7 @@ See <<ccs-unmin-roundtrips>> to learn how this option works.
|
||||
|
||||
[discrete]
|
||||
[[ccs-min-roundtrips]]
|
||||
=== Minimize network roundtrips
|
||||
==== Minimize network roundtrips
|
||||
|
||||
Here's how {ccs} works when you minimize network roundtrips.
|
||||
|
||||
@ -335,7 +334,7 @@ image:images/ccs/ccs-min-roundtrip-client-response.svg[]
|
||||
|
||||
[discrete]
|
||||
[[ccs-unmin-roundtrips]]
|
||||
=== Don't minimize network roundtrips
|
||||
==== Don't minimize network roundtrips
|
||||
|
||||
Here's how {ccs} works when you don't minimize network roundtrips.
|
||||
|
||||
|
||||
39
docs/reference/search/index.asciidoc
Normal file
39
docs/reference/search/index.asciidoc
Normal file
@ -0,0 +1,39 @@
|
||||
[[search-your-data]]
|
||||
= Search your data
|
||||
|
||||
[partintro]
|
||||
--
|
||||
|
||||
[[search-query]]
|
||||
A _search query_, or _query_, is a request for information about data in one or
|
||||
more {es} 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 pages on my website contain a specific word or phrase?
|
||||
* What processes on my server take longer than 500 milliseconds to respond?
|
||||
* What users on my network ran `regsvr32.exe` within the last week?
|
||||
* How many of my products have a price greater than $20?
|
||||
|
||||
A _search_ consists of one or more queries that are combined and sent to {es}.
|
||||
Documents that match the 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]
|
||||
[[search-toc]]
|
||||
=== In this section
|
||||
|
||||
* <<run-a-search>>
|
||||
* <<modules-cross-cluster-search>>
|
||||
* <<async-search-intro>>
|
||||
|
||||
--
|
||||
|
||||
include::run-a-search.asciidoc[]
|
||||
include::{es-repo-dir}/async-search.asciidoc[]
|
||||
include::{es-repo-dir}/modules/cross-cluster-search.asciidoc[]
|
||||
289
docs/reference/search/run-a-search.asciidoc
Normal file
289
docs/reference/search/run-a-search.asciidoc
Normal file
@ -0,0 +1,289 @@
|
||||
[[run-a-search]]
|
||||
== Run a search
|
||||
|
||||
You can use the <<search-search,search API>> to search data stored in
|
||||
one or more {es} indices.
|
||||
|
||||
The API can runs two types of searches, depending on how you provide
|
||||
<<search-query,queries>>:
|
||||
|
||||
<<run-uri-search,URI searches>>::
|
||||
Queries are provided through a query parameter. URI searches tend to be
|
||||
simpler and best suited for testing.
|
||||
|
||||
<<run-request-body-search,Request body searches>>::
|
||||
Queries are provided through the JSON body of the API request. These queries
|
||||
are written in <<query-dsl,Query DSL>>. We recommend using request body
|
||||
searches in most production use cases.
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
If you specify a query in both the URI and request body, the search API request
|
||||
runs only the URI query.
|
||||
====
|
||||
|
||||
[discrete]
|
||||
[[run-uri-search]]
|
||||
=== Run a URI search
|
||||
|
||||
You can use the search API's <<search-api-query-params-q,`q` query string
|
||||
parameter>> to run a search in the request's URI. The `q` parameter only accepts
|
||||
queries written in Lucene's <<query-string-syntax,query string syntax>>.
|
||||
|
||||
.*Example*
|
||||
[%collapsible]
|
||||
====
|
||||
To get started, ingest or add some data to an {es} index.
|
||||
|
||||
The following <<docs-bulk,bulk API>> request adds some example user log data to
|
||||
the `user_logs_000001` index.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
PUT /user_logs_000001/_bulk?refresh
|
||||
{"index":{"_index" : "user_logs_000001", "_id" : "1"}}
|
||||
{ "@timestamp": "2020-12-06T11:04:05.000Z", "user": { "id": "vlb44hny" }, "message": "Login attempt failed" }
|
||||
{"index":{"_index" : "user_logs_000001", "_id" : "2"}}
|
||||
{ "@timestamp": "2020-12-07T11:06:07.000Z", "user": { "id": "8a4f500d" }, "message": "Login successful" }
|
||||
{"index":{"_index" : "user_logs_000001", "_id" : "3"}}
|
||||
{ "@timestamp": "2020-12-07T11:07:08.000Z", "user": { "id": "l7gk7f82" }, "message": "Logout successful" }
|
||||
----
|
||||
|
||||
You can now use the search API to run a URI search on this index.
|
||||
|
||||
The following URI search matches documents with a `user.id` value of `l7gk7f82`.
|
||||
Note the query is specified using the `q` query string parameter.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
GET /user_logs_000001/_search?q=user.id:8a4f500d
|
||||
----
|
||||
// TEST[continued]
|
||||
|
||||
The API returns the following response. Note the `hits.hits` property contains
|
||||
the document that matched the query.
|
||||
|
||||
[source,console-result]
|
||||
----
|
||||
{
|
||||
"took": 2,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 1,
|
||||
"successful": 1,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 1,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 0.9808291,
|
||||
"hits": [
|
||||
{
|
||||
"_index": "user_logs_000001",
|
||||
"_type": "_doc",
|
||||
"_id": "2",
|
||||
"_score": 0.9808291,
|
||||
"_source": {
|
||||
"@timestamp": "2020-12-07T11:06:07.000Z",
|
||||
"user": {
|
||||
"id": "8a4f500d"
|
||||
},
|
||||
"message": "Login successful"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
----
|
||||
// TESTRESPONSE[s/"took": 2/"took": "$body.took"/]
|
||||
====
|
||||
|
||||
[discrete]
|
||||
[[run-request-body-search]]
|
||||
=== Run a request body search
|
||||
|
||||
You can use the search API's <<request-body-search-query,`query` request
|
||||
body parameter>> to provide a query as a JSON object, written in
|
||||
<<query-dsl,Query DSL>>.
|
||||
|
||||
.*Example*
|
||||
[%collapsible]
|
||||
====
|
||||
The following request body search uses the <<query-dsl-match-query,`match`>>
|
||||
query to match documents with a `message` value of `login successful`. Note the
|
||||
`match` query is specified as a JSON object in the `query` parameter.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
GET /user_logs_000001/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"message": "login successful"
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
// TEST[continued]
|
||||
|
||||
The API returns the following response.
|
||||
|
||||
The `hits.hits` property contains matching documents. By default, the response
|
||||
sorts these matching documents by `_score`, a <<relevance-scores,relevance
|
||||
score>> that measures how well each document matches the query.
|
||||
|
||||
[source,console-result]
|
||||
----
|
||||
{
|
||||
"took": 1,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 1,
|
||||
"successful": 1,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 3,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 0.9983525,
|
||||
"hits": [
|
||||
{
|
||||
"_index": "user_logs_000001",
|
||||
"_type": "_doc",
|
||||
"_id": "2",
|
||||
"_score": 0.9983525,
|
||||
"_source": {
|
||||
"@timestamp": "2020-12-07T11:06:07.000Z",
|
||||
"user": {
|
||||
"id": "8a4f500d"
|
||||
},
|
||||
"message": "Login successful"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index": "user_logs_000001",
|
||||
"_type": "_doc",
|
||||
"_id": "3",
|
||||
"_score": 0.49917626,
|
||||
"_source": {
|
||||
"@timestamp": "2020-12-07T11:07:08.000Z",
|
||||
"user": {
|
||||
"id": "l7gk7f82"
|
||||
},
|
||||
"message": "Logout successful"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index": "user_logs_000001",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_score": 0.42081726,
|
||||
"_source": {
|
||||
"@timestamp": "2020-12-06T11:04:05.000Z",
|
||||
"user": {
|
||||
"id": "vlb44hny"
|
||||
},
|
||||
"message": "Login attempt failed"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
----
|
||||
// TESTRESPONSE[s/"took": 1/"took": "$body.took"/]
|
||||
====
|
||||
|
||||
[discrete]
|
||||
[[search-multiple-indices]]
|
||||
=== Search multiple indices
|
||||
|
||||
To search multiple indices, add them as comma-separated values in the search API
|
||||
request path.
|
||||
|
||||
.*Example*
|
||||
[%collapsible]
|
||||
====
|
||||
The following request searches the `user_logs_000001` and `user_logs_000002`
|
||||
indices.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
GET /user_logs_000001,user_logs_000002/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"message": "login successful"
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
// TEST[continued]
|
||||
// TEST[s/^/PUT user_logs_000002\n/]
|
||||
====
|
||||
|
||||
You can also search multiple indices using an index pattern.
|
||||
|
||||
.*Example*
|
||||
[%collapsible]
|
||||
====
|
||||
The following request uses the index pattern `user_logs*` in place of the index
|
||||
name. The request searches any indices in the cluster that start with
|
||||
`user_logs`.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
GET /user_logs*/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"message": "login successful"
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
// TEST[continued]
|
||||
====
|
||||
|
||||
To search all indices in a cluster, omit the index name from the request path.
|
||||
Alternatively, you can use `_all` or `*` in place of the index name.
|
||||
|
||||
.*Example*
|
||||
[%collapsible]
|
||||
====
|
||||
The following requests are equivalent and search all indices in the cluster.
|
||||
|
||||
[source,console]
|
||||
----
|
||||
GET /_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"message": "login successful"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
GET /_all/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"message": "login successful"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
GET /*/_search
|
||||
{
|
||||
"query" : {
|
||||
"match" : { "message" : "login" }
|
||||
}
|
||||
}
|
||||
----
|
||||
// TEST[continued]
|
||||
====
|
||||
Loading…
x
Reference in New Issue
Block a user