Browse Source

[DOCS] Add data streams to multi search API docs (#58610)

Makes the existing multi search API docs aware of data streams.
James Rodewig 5 years ago
parent
commit
a7aa3da3bf
1 changed files with 27 additions and 14 deletions
  1. 27 14
      docs/reference/search/multi-search.asciidoc

+ 27 - 14
docs/reference/search/multi-search.asciidoc

@@ -1,5 +1,8 @@
 [[search-multi-search]]
-=== Multi Search API
+=== Multi search API
+++++
+<titleabbrev>Multi search</titleabbrev>
+++++
 
 Executes several searches with a single API request.
 
@@ -16,7 +19,7 @@ GET twitter/_msearch
 [[search-multi-search-api-request]]
 ==== {api-request-title}
 
-`GET /<index>/_msearch`
+`GET /<target>/_msearch`
 
 
 [[search-multi-search-api-desc]]
@@ -50,9 +53,15 @@ this endpoint the `Content-Type` header should be set to `application/x-ndjson`.
 [[search-multi-search-api-path-params]]
 ==== {api-path-parms-title}
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
+`<target>`::
+(Optional, string)
+Comma-separated list of data streams, indices, and index aliases to search.
++
+This list acts as a fallback if a search in the request body does not specify an
+`index` target.
 +
-To search all indices, use `_all` or omit this parameter.
+Wildcard (`*`) expressions are supported. To search all data streams and indices
+in a cluster, omit this parameter or use `_all` or `*`.
 
 [[search-multi-search-api-query-params]]
 ==== {api-query-parms-title}
@@ -89,8 +98,8 @@ Maximum number of concurrent shard requests that each sub-search request
 executes per node.  Defaults to `5`.
 
 You can use this parameter to prevent a request from overloading a cluster. For
-example, a default request hits all indices in a cluster. This could cause shard
-request rejections if the number of shards per node is high.
+example, a default request hits all data streams and indices in a cluster. This
+could cause shard request rejections if the number of shards per node is high.
 
 In certain scenarios, parallelism isn't achieved through concurrent requests. In
 those cases, a low value in this  parameter could result in poor performance.
@@ -180,8 +189,11 @@ included in the response. Defaults to `false`.
 
 `index`:::
 (Optional, string or array of strings)
-Index name or <<indices-aliases,alias>> used to limit the request. Wildcard
-expressions are supported. You can specify multiple indices as an array.
+Data streams, indices, and index aliases to search. Wildcard (`*`) expressions
+are supported. You can specify multiple targets as an array.
++
+If this parameter is not specified, the `<target>` request path parameter
+is used as a fallback.
 
 `preference`:::
 (Optional, string)
@@ -250,7 +262,8 @@ Number of hits to return. Defaults to `10`.
 [[search-multi-search-api-example]]
 ==== {api-examples-title}
 
-The header part includes which index / indices to search on, the `search_type`,
+The header part includes which data streams, indices, and index aliases to
+search. The header also indicates the `search_type`,
 `preference`, and `routing`. The body includes the typical search body request
 (including the `query`, `aggregations`, `from`, `size`, and so on).
 
@@ -280,9 +293,9 @@ Note, the above includes an example of an empty header (can also be just
 without any content) which is supported as well.
 
 
-The endpoint allows to also search against an index/indices in the URI itself,
-in which case it will be used as the default unless explicitly defined otherwise
-in the header. For example:
+The endpoint also allows you to search against data streams, indices, and index
+aliases in the request path. In this case, it will be used as the default target
+unless explicitly specified in the header's `index` parameter. For example:
 
 [source,console]
 --------------------------------------------------
@@ -297,8 +310,8 @@ GET twitter/_msearch
 // TEST[setup:twitter]
 
 The above will execute the search against the `twitter` index for all the
-requests that don't define an index, and the last one will be executed
-against the `twitter2` index.
+requests that don't define an `index` target in the request body. The last
+search will be executed against the `twitter2` index.
 
 The `search_type` can be set in a similar manner to globally apply to
 all search requests.