Skip to content

Commit

Permalink
[DOCS] Create top-level "Search your data" page (#56058) (#57463)
Browse files Browse the repository at this point in the history
**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
  • Loading branch information
jrodewig authored Jun 1, 2020
1 parent ceb4b29 commit 50a8779
Show file tree
Hide file tree
Showing 4 changed files with 347 additions and 20 deletions.
14 changes: 7 additions & 7 deletions docs/reference/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]

Expand All @@ -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[]
Expand Down
25 changes: 12 additions & 13 deletions docs/reference/modules/cross-cluster-search.asciidoc
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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}:

Expand All @@ -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.

Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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.

Expand Down
39 changes: 39 additions & 0 deletions docs/reference/search/index.asciidoc
Original file line number Diff line number Diff line change
@@ -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[]
Loading

0 comments on commit 50a8779

Please sign in to comment.