[DOCS] add docs for async search (elastic#53675)

Relates to elastic#49091

Co-Authored-By: James Rodewig <[email protected]>

Author: javanna

buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy

@@ -314,10 +314,7 @@ class RestTestsFromSnippetsTask extends SnippetsTask {
             if (path == null) {
                 path = '' // Catch requests to the root...
             } else {
-                // Escape some characters that are also escaped by sense
                 path = path.replace('<', '%3C').replace('>', '%3E')
-                path = path.replace('{', '%7B').replace('}', '%7D')
-                path = path.replace('|', '%7C')
             }
             current.println("  - do:")
             if (catchPart != null) {

docs/reference/api-conventions.asciidoc

@@ -87,7 +87,7 @@ GET /%3Clogstash-%7Bnow%2Fd%7D%3E/_search
 }
 ----------------------------------------------------------------------
 // TEST[s/^/PUT logstash-2016.09.20\n/]
-// TEST[s/now/2016.09.20||/]
+// TEST[s/now/2016.09.20%7C%7C/]
 
 [NOTE]
 .Percent encoding of date math characters
@@ -141,7 +141,7 @@ GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogs
 }
 ----------------------------------------------------------------------
 // TEST[s/^/PUT logstash-2016.09.20\nPUT logstash-2016.09.19\nPUT logstash-2016.09.18\n/]
-// TEST[s/now/2016.09.20||/]
+// TEST[s/now/2016.09.20%7C%7C/]
 
 [[common-options]]
 === Common options
@@ -367,7 +367,7 @@ GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc
 [float]
 ==== Flat Settings
 
-The `flat_settings` flag affects rendering of the lists of settings. When the 
+The `flat_settings` flag affects rendering of the lists of settings. When the
 `flat_settings` flag is `true`, settings are returned in a flat format:
 
 [source,console]

docs/reference/async-search.asciidoc

@@ -0,0 +1,22 @@
+[role="xpack"]
+[testenv="basic"]
+[[async-search-intro]]
+== Long-running searches
+
+{es} generally allows you to quickly search across big amounts of data. There are
+situations where a search executes on many many shards, possibly against
+<<frozen-indices,frozen indices>> and spanning multiple
+<<modules-remote-clusters,remote clusters>>, for which
+results are not expected to be returned in milliseconds. When you need to
+execute long-running searches, synchronously
+waiting for its results to be returned is not ideal. Instead, Async search lets
+you submit a search request that gets executed _asynchronously_,
+monitor the progress of the request, and retrieve results at a later stage.
+You can also retrieve partial results as they become available but
+before the search has completed.
+
+You can submit an async search request using the <<submit-async-search,submit
+async search>> API. The <<get-async-search,get async search>> API allows you to
+monitor the progress of an async search request and retrieve its results. An
+ongoing async search can be deleted through the <<delete-async-search,delete
+async search>> API.

docs/reference/index.asciidoc

@@ -26,6 +26,8 @@ include::query-dsl.asciidoc[]
 
 include::modules/cross-cluster-search.asciidoc[]
 
+include::async-search.asciidoc[]
+
 include::scripting.asciidoc[]
 
 include::mapping.asciidoc[]

docs/reference/indices/rollover-index.asciidoc

@@ -300,7 +300,7 @@ POST /logs_write/_rollover <2>
   }
 }
 --------------------------------------------------
-// TEST[s/now/2016.10.31||/]
+// TEST[s/now/2016.10.31%7C%7C/]
 
 <1> Creates an index named with today's date (e.g.) `logs-2016.10.31-1`
 <2> Rolls over to a new index with today's date, e.g. `logs-2016.10.31-000002` if run immediately, or `logs-2016.11.01-000002` if run after 24 hours
@@ -339,7 +339,7 @@ over indices created in the last three days, you could do the following:
 GET /%3Clogs-%7Bnow%2Fd%7D-*%3E%2C%3Clogs-%7Bnow%2Fd-1d%7D-*%3E%2C%3Clogs-%7Bnow%2Fd-2d%7D-*%3E/_search
 --------------------------------------------------
 // TEST[continued]
-// TEST[s/now/2016.10.31||/]
+// TEST[s/now/2016.10.31%7C%7C/]
 
 
 [[rollover-index-api-dry-run-ex]]

docs/reference/redirects.asciidoc

@@ -120,7 +120,7 @@ See <<native-realm-configuration>>.
 [role="exclude",id="native-settings"]
 ==== Native realm settings
 
-See <<ref-native-settings>>. 
+See <<ref-native-settings>>.
 
 [role="exclude",id="configuring-saml-realm"]
 === Configuring a SAML realm
@@ -130,27 +130,27 @@ See <<saml-guide>>.
 [role="exclude",id="saml-settings"]
 ==== SAML realm settings
 
-See <<ref-saml-settings>>. 
+See <<ref-saml-settings>>.
 
 [role="exclude",id="_saml_realm_signing_settings"]
 ==== SAML realm signing settings
 
-See <<ref-saml-signing-settings>>. 
+See <<ref-saml-signing-settings>>.
 
 [role="exclude",id="_saml_realm_encryption_settings"]
 ==== SAML realm encryption settings
 
-See <<ref-saml-encryption-settings>>. 
+See <<ref-saml-encryption-settings>>.
 
 [role="exclude",id="_saml_realm_ssl_settings"]
 ==== SAML realm SSL settings
 
-See <<ref-saml-ssl-settings>>. 
+See <<ref-saml-ssl-settings>>.
 
 [role="exclude",id="configuring-file-realm"]
 === Configuring a file realm
 
-See <<file-realm-configuration>>. 
+See <<file-realm-configuration>>.
 
 [role="exclude",id="ldap-user-search"]
 === User search mode and user DN templates mode
@@ -170,7 +170,7 @@ See <<ref-ldap-settings>>.
 [role="exclude",id="ldap-ssl"]
 === Setting up SSL between Elasticsearch and LDAP
 
-See <<tls-ldap>>. 
+See <<tls-ldap>>.
 
 [role="exclude",id="configuring-kerberos-realm"]
 === Configuring a Kerberos realm
@@ -211,7 +211,7 @@ See <<ref-ad-settings>>.
 [role="exclude",id="mapping-roles-ad"]
 === Mapping Active Directory users and groups to roles
 
-See <<ad-realm-configuration>>. 
+See <<ad-realm-configuration>>.
 
 [role="exclude",id="how-security-works"]
 === How security works
@@ -237,9 +237,9 @@ See the details in
 
 This page was deleted.
 [[ml-datafeed-chunking-config]]
-See the details in <<ml-put-datafeed>>, <<ml-update-datafeed>>, 
+See the details in <<ml-put-datafeed>>, <<ml-update-datafeed>>,
 [[ml-datafeed-delayed-data-check-config]]
-<<ml-get-datafeed>>, 
+<<ml-get-datafeed>>,
 [[ml-datafeed-counts]]
 <<ml-get-datafeed-stats>>.
 
@@ -323,7 +323,7 @@ See <<snapshots-register-repository>>.
 [role="exclude",id="ml-dfa-analysis-objects"]
 === Analysis configuration objects
 
-This page was deleted. 
+This page was deleted.
 See <<put-dfanalytics>>.
 
 [role="exclude",id="slm-api-delete"]
@@ -376,11 +376,6 @@ See <<slm-api-stop>>.
 
 See <<ccs-gateway-seed-nodes>> and <<ccs-min-roundtrips>>.
 
-[role="exclude",id="async-search"]
-=== Asynchronous search
-
-coming::[7.x]
-
 [role="exclude",id="indices-component-templates"]
 === Component template APIs
 

docs/reference/search.asciidoc

@@ -152,6 +152,8 @@ high). This default value is `5`.
 
 include::search/search.asciidoc[]
 
+include::search/async-search.asciidoc[]
+
 include::search/uri-request.asciidoc[]
 
 include::search/request-body.asciidoc[]