[DOCS] Update alias API docs for data stream aliases (#73419)

Updates the docs for several alias APIs for data stream aliases. Also
removes some redundant examples now covered in the [aliases guide][0].

[0]: https://www.elastic.co/guide/en/elasticsearch/reference/master/alias.html

docs/reference/alias.asciidoc

@@ -45,9 +45,8 @@ POST _aliases
 ----
 // TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\n/]
 
-The API's `index` and `indices` parameters support wildcards (`*`). If a
-wildcard pattern matches both data streams and indices, the action only uses
-matching data streams.
+The API's `index` and `indices` parameters support wildcards (`*`). Wildcard
+patterns that match both data streams and indices return an error.
 
 [source,console]
 ----

docs/reference/indices/add-alias.asciidoc

@@ -8,158 +8,47 @@ Adds a data stream or index to an <<alias,alias>>.
 
 [source,console]
 ----
-PUT /my-index-000001/_alias/alias1
+PUT my-data-stream/_alias/my-alias
 ----
-// TEST[setup:my_index]
-
+// TEST[setup:my_data_stream]
+// TEST[teardown:data_stream_cleanup]
 
 [[add-alias-api-request]]
 ==== {api-request-title}
 
-`PUT /<index>/_alias/<alias>`
+`POST <target>/_alias/<alias>`
 
-`POST /<index>/_alias/<alias>`
+`POST <target>/_aliases/<alias>`
 
-`PUT /<index>/_aliases/<alias>`
+`PUT <target>/_alias/<alias>`
 
-`POST /<index>/_aliases/<alias>`
+`PUT <target>/_aliases/<alias>`
 
 [[add-alias-api-prereqs]]
 ==== {api-prereq-title}
 
 * If the {es} {security-features} are enabled, you must have the `manage`
-<<privileges-list-indices,index privilege>> for both the index and index alias.
+<<privileges-list-indices,index privilege>> for the alias and its data streams
+or indices.
 
 [[add-alias-api-path-params]]
 ==== {api-path-parms-title}
 
-`<index>`::
-(Required, string)
-Comma-separated list or wildcard expression of index names
-to add to the alias.
-+
-To add all indices in the cluster to the alias,
-use a value of `_all`.
-+
-NOTE: You cannot add <<data-streams,data streams>> to an index alias.
-
 `<alias>`::
-(Required, string)
-Name of the index alias to create or update. Supports
-<<date-math-index-names,date math>>.
+(Required, string) Alias to update. If the alias doesn't exist, the request
+creates it. Index alias names support <<date-math-index-names,date math>>.
 
+`<target>`::
+(Required, string) Comma-separated list of data streams or indices to add.
+Supports wildcards (`*`). Wildcard patterns that match both data streams and
+indices return an error.
 
 [[add-alias-api-query-params]]
 ==== {api-query-parms-title}
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-
 [[add-alias-api-request-body]]
 ==== {api-request-body-title}
 
-`filter`::
-(Optional, query object)
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias-filter]
-
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]
-
-[[add-alias-api-example]]
-==== {api-examples-title}
-
-[[alias-date-math-support]]
-===== Date math support
-
-Index alias names support <<date-math-index-names,date math>>.
-
-[source,console]
-----
-# POST /logs/_alias/<logs_{now/M}>
-POST /logs/_alias/%3Clogs_%7Bnow%2FM%7D%3E
-----
-// TEST[s/^/PUT logs\n/]
-
-[[alias-adding]]
-===== Add a time-based alias
-
-The following request creates an alias, `2030`,
-for the `logs_20302801` index.
-
-[source,console]
---------------------------------------------------
-PUT /logs_20302801/_alias/2030
---------------------------------------------------
-// TEST[s/^/PUT logs_20302801\n/]
-
-[[add-alias-api-user-ex]]
-===== Add a user-based alias
-
-First, create an index, `users`,
-with a mapping for the `user_id` field:
-
-[source,console]
---------------------------------------------------
-PUT /users
-{
-  "mappings" : {
-    "properties" : {
-      "user_id" : {"type" : "integer"}
-    }
-  }
-}
---------------------------------------------------
-
-Then add the index alias for a specific user, `user_12`:
-
-[source,console]
---------------------------------------------------
-PUT /users/_alias/user_12
-{
-  "routing" : "12",
-  "filter" : {
-    "term" : {
-      "user_id" : 12
-    }
-  }
-}
---------------------------------------------------
-// TEST[continued]
-
-[[alias-index-creation]]
-===== Add an alias during index creation
-
-You can use the <<create-index-aliases,create index API>>
-to add an index alias during index creation.
-
-[source,console]
---------------------------------------------------
-PUT /logs_20302801
-{
-  "mappings": {
-    "properties": {
-      "year": { "type": "integer" }
-    }
-  },
-  "aliases": {
-    "current_day": {},
-    "2030": {
-      "filter": {
-        "term": { "year": 2030 }
-      }
-    }
-  }
-}
---------------------------------------------------
-
-The create index API also supports <<date-math-index-names,date math>> in index
-alias names.
-
-[source,console]
-----
-PUT /logs
-{
-  "aliases": {
-    "<logs_{now/M}>": {}
-  }
-}
-----
+include::aliases.asciidoc[tag=alias-options]

docs/reference/indices/alias-exists.asciidoc

@@ -8,35 +8,38 @@ Checks if an <<alias,alias>> exists.
 
 [source,console]
 ----
-HEAD /_alias/alias1
+HEAD _alias/my-alias
 ----
-// TEST[setup:my_index]
-// TEST[s/^/PUT my-index-000001\/_alias\/alias1\n/]
-
+// TEST[setup:my_data_stream]
+// TEST[s/^/PUT my-data-stream\/_alias\/my-alias\n/]
+// TEST[teardown:data_stream_cleanup]
 
 [[alias-exists-api-request]]
 ==== {api-request-title}
 
-`HEAD /_alias/<alias>`
+`HEAD _alias/<alias>`
 
-`HEAD /<index>/_alias/<alias>`
+`HEAD <target>/_alias/<alias>`
 
 [[alias-exists-api-prereqs]]
 ==== {api-prereq-title}
 
 * If the {es} {security-features} are enabled, you must have the
 `view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
-for the index alias. If you specify an index, you must also have
-`view_index_metadata` or `manage` index privilege for the index.
+for the alias. If you specify a target, you must also have the
+`view_index_metadata` or `manage` index privilege for the target.
 
 [[alias-exists-api-path-params]]
 ==== {api-path-parms-title}
 
 `<alias>`::
-(Required, string)
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias]
+(Optional, string) Comma-separated list of aliases to check. Supports wildcards
+(`*`).
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
+`<target>`::
+(Optional, string) Comma-separated list of data streams or indices used to limit
+the request. Supports wildcards (`*`). To target all data streams and indices,
+omit this parameter or use `*` or `_all`.
 
 [[alias-exists-api-query-params]]
 ==== {api-query-parms-title}
@@ -45,28 +48,17 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
 +
 Defaults to `all`.
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+`ignore_unavailable`::
+(Optional, Boolean) If `false`, requests that include a missing data stream or
+index in the `<target>` return an error. Defaults to `false`.
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]
 
-
 [[alias-exists-api-response-codes]]
 ==== {api-response-codes-title}
 
 `200`::
-Indicates all specified index aliases exist.
-
- `404`::
-Indicates one or more specified index aliases **do not** exist.
-
+All specified aliases exist.
 
-[[alias-exists-api-example]]
-==== {api-examples-title}
-
-[source,console]
-----
-HEAD /_alias/2030
-HEAD /_alias/20*
-HEAD /logs_20302801/_alias/*
-----
-// TEST[s/^/PUT logs_20302801\nPUT logs_20302801\/_alias\/2030\n/]
+`404`::
+One or more of the specified aliases don't exist.

docs/reference/indices/aliases.asciidoc

@@ -8,20 +8,25 @@ Performs one or more <<alias,alias>> actions in a single atomic operation.
 
 [source,console]
 ----
-POST /_aliases
+POST _aliases
 {
-  "actions" : [
-    { "add" : { "index" : "my-index-000001", "alias" : "alias1" } }
+  "actions": [
+    {
+      "add": {
+        "index": "my-data-stream",
+        "alias": "my-alias"
+      }
+    }
   ]
 }
 ----
-// TEST[setup:my_index]
-
+// TEST[setup:my_data_stream]
+// TEST[teardown:data_stream_cleanup]
 
 [[indices-aliases-api-request]]
 ==== {api-request-title}
 
-`POST /_aliases`
+`POST _aliases`
 
 [[indices-aliases-api-prereqs]]
 ==== {api-prereq-title}
@@ -30,138 +35,124 @@ POST /_aliases
 <<privileges-list-indices,index privileges>>:
 
 ** To use the `add` or `remove` action, you must have the `manage` index
-privilege for both the index and index alias.
+privilege for the alias and its data streams or indices.
 
 ** To use the `remove_index` action, you must have the `manage` index privilege
 for the index.
 
-[[indices-aliases-api-desc]]
-==== {api-description-title}
-
-APIs in Elasticsearch accept an index name when working against a
-specific index, and several indices when applicable. The index aliases
-API allows aliasing an index with a name, with all APIs automatically
-converting the alias name to the actual index name. An alias can also be
-mapped to more than one index, and when specifying it, the alias will
-automatically expand to the aliased indices. An alias can also be
-associated with a filter that will automatically be applied when
-searching, and routing values. An alias cannot have the same name as an index.
-
-
 [[indices-aliases-api-query-params]]
 ==== {api-query-parms-title}
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-
+[role="child_attributes"]
 [[indices-aliases-api-request-body]]
 ==== {api-request-body-title}
 
 `actions`::
+(Required, array of objects) Actions to perform.
 +
---
-(Required, array of actions)
-Set of actions to perform.
-Valid actions include:
-
+.Properties of `actions` objects
+[%collapsible%open]
+====
+`<action>`::
+(Required, object) The key is the action type. At least one action is required.
++
+.Valid `<action>` keys
+[%collapsible%open]
+=====
 `add`::
-Adds an alias to an index.
+Adds a data stream or index to an alias. If the alias doesn't exist, the `add`
+action creates it.
 
 `remove`::
-Removes an alias from an index.
+Removes a data stream or index from an alias.
 
 `remove_index`::
-Deletes a concrete index, similar to the <<indices-delete-index, delete index
-API>>. Attempts to remove an index alias will fail.
-
-You can perform these actions on alias objects.
-Valid parameters for alias objects include:
-
-`index`::
-(String)
-Wildcard expression of index names
-used to perform the action.
-+
-If the `indices` parameter is not specified,
-this parameter is required.
-+
-NOTE: You cannot add <<data-streams,data streams>> to an index alias.
-
-`indices`::
-(Array)
-Array of index names
-used to perform the action.
+Deletes an index. You cannot use this action on aliases or data streams.
+=====
 +
-If the `index` parameter is not specified,
-this parameter is required.
+The object body contains options for the alias. Supports an empty object.
 +
-NOTE: You cannot add <<data-streams,data streams>> to an index alias.
-
+.Properties of `<action>`
+[%collapsible%open]
+=====
 `alias`::
-(String)
-Comma-separated list or wildcard expression of index alias names to add, remove,
-or delete. Supports <<date-math-index-names,date math>>.
-+
-If the `aliases` parameter is not specified,
-this parameter is required for the `add` or `remove` action.
+(Required*, string) Alias for the action. Index alias names support
+<<date-math-index-names,date math>>. If `aliases` is not specified, the `add`
+and `remove` actions require this parameter. The `remove_index` action doesn't
+support this parameter.
 
 `aliases`::
-(Array of strings)
-Array of index alias names to add, remove, or delete. Supports
-<<date-math-index-names,date math>>.
-+
-If the `alias` parameter is not specified, this parameter is required for the
-`add` or `remove` action.
+(Required*, array of strings) Aliases for the action. Index alias names support
+<<date-math-index-names,date math>>. If `alias` is not specified, the `add` and
+`remove` actions require this parameter. The `remove_index` action doesn't
+support this parameter.
 
+// tag::alias-options[]
 `filter`::
-(Optional, query object)
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias-filter]
+(Optional, <<query-dsl,Query DSL object>> Query used to limit documents the
+alias can access. Data stream aliases don't support this parameter.
+// end::alias-options[]
 +
-See <<filter-alias>> for an example.
+Only the `add` action supports this parameter.
 
-`is_hidden`::
-(Optional, Boolean)
-If `true`, the alias will be excluded from wildcard expressions by default,
-unless overridden in the request using the `expand_wildcards` parameter,
-similar to <<index-hidden,hidden indices>>. This property must be set to the
-same value on all indices that share an alias. Defaults to `false`.
+`index`::
+(Required*, string) Data stream or index for the action. Supports wildcards
+(`*`). Wildcard patterns that match both data streams and indices return an
+error. If `indices` is not specified, this parameter is required.
 
-`must_exist`::
-(Optional, Boolean)
-If `true`, the alias to remove must exist. Defaults to `false`.
+`indices`::
+(Required*, array of strings) Data streams or indices for the action. Supports
+wildcards (`*`). Wildcard patterns that match both data streams and indices
+return an error. If `index` is not specified, this parameter is required.
 
-`is_write_index`::
-(Optional, Boolean)
-If `true`, assigns the index as an alias's write index.
-Defaults to `false`.
-+
-An alias can have one write index at a time.
+// tag::alias-options[]
+`index_routing`::
+(Optional, string) Value used to route indexing operations to a specific shard.
+If specified, this overwrites the `routing` value for indexing operations. Data
+stream aliases don't support this parameter.
+// end::alias-options[]
 +
-See <<write-index>> for an example.
+Only the `add` action supports this parameter.
+
+// tag::alias-options[]
+`is_hidden`::
+(Optional, Boolean) If `true`, the alias is <<hidden,hidden>>. Defaults to
+`false`. All data streams or indices for the alias must have the same
+`is_hidden` value.
+// end::alias-options[]
 +
-[IMPORTANT]
-====
-Aliases that do not explicitly set `is_write_index: true` for an index, and
-only reference one index, will have that referenced index behave as if it is the write index
-until an additional index is referenced. At that point, there will be no write index and
-writes will be rejected.
-====
+Only the `add` action supports this parameter.
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]
+// tag::alias-options[]
+`is_write_index`::
+(Optional, Boolean) If `true`, sets the <<write-index,write index or data
+stream>> for the alias. Defaults to `false`.
+// end::alias-options[]
 +
-See <<alias-routing>> for an example.
+Only the `add` action supports this parameter.
 
-`index_routing`::
-(Optional, string)
-Custom <<mapping-routing-field, routing value>> used
-for the alias's indexing operations.
+`must_exist`::
+(Optional, Boolean)
+If `true`, the alias must exist to perform the action. Defaults to `false`. Only
+the `remove` action supports this parameter. 
+
+// tag::alias-options[]
+`routing`::
+(Optional, string) Value used to route indexing and search operations to a
+specific shard. Data stream aliases don't support this parameter.
+// end::alias-options[]
 +
-See <<alias-routing>> for an example.
+Only the `add` action supports this parameter.
 
+// tag::alias-options[]
 `search_routing`::
-(Optional, string)
-Custom <<mapping-routing-field, routing value>> used
-for the alias's search operations.
+(Optional, string) Value used to route search operations to a specific shard. If
+specified, this overwrites the `routing` value for search operations. Data
+stream aliases don't support this parameter.
+// end::alias-options[]
 +
-See <<alias-routing>> for an example.
---
+Only the `add` action supports this parameter.
+=====
+====

docs/reference/indices/delete-alias.asciidoc

@@ -4,46 +4,41 @@
 <titleabbrev>Delete alias</titleabbrev>
 ++++
 
-Deletes an <<alias,alias>>.
+Removes a data stream or index from an <<alias,alias>>.
 
 [source,console]
 ----
-DELETE /my-index-000001/_alias/alias1
+DELETE my-data-stream/_alias/my-alias
 ----
-// TEST[setup:my_index]
-// TEST[s/^/PUT my-index-000001\/_alias\/alias1\n/]
+// TEST[setup:my_data_stream]
+// TEST[s/^/PUT my-data-stream\/_alias\/my-alias\n/]
+// TEST[teardown:data_stream_cleanup]
 
 [[delete-alias-api-request]]
 ==== {api-request-title}
 
-`DELETE /<index>/_alias/<alias>`
+`DELETE <target>/_alias/<alias>`
 
-`DELETE /<index>/_aliases/<alias>`
+`DELETE <target>/_aliases/<alias>`
 
 [[delete-alias-api-prereqs]]
 ==== {api-prereq-title}
 
 * If the {es} {security-features} are enabled, you must have the `manage`
-<<privileges-list-indices,index privilege>> for both the index and index alias.
+<<privileges-list-indices,index privilege>> for the alias and it data streams or
+indices.
 
 [[delete-alias-api-path-params]]
 ==== {api-path-parms-title}
 
-`<index>`::
-(Required, string)
-Comma-separated list or wildcard expression of index names
-used to limit the request.
-+
-To include all indices in the cluster,
-use a value of `_all` or `*`.
-
 `<alias>`::
-(Required, string)
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias]
-+
-To delete all aliases,
-use a value of `_all` or `*`.
+(Required, string) Comma-separated list of aliases to remove. Supports wildcards
+(`*`). To remove all aliases, use `*` or `_all`.
 
+`<target>`::
+(Required, string) Comma-separated list of data streams or indices used to limit
+the request. Supports wildcards (`*`). Wildcard patterns that match both data
+streams and indices return an error.
 
 [[delete-alias-api-query-params]]
 ==== {api-query-parms-title}

docs/reference/indices/get-alias.asciidoc

@@ -8,42 +8,41 @@ Retrieves information for one or more <<alias,aliases>>.
 
 [source,console]
 ----
-GET /my-index-000001/_alias/alias1
+GET my-data-stream/_alias/my-alias
 ----
-// TEST[setup:my_index]
-// TEST[s/^/PUT my-index-000001\/_alias\/alias1\n/]
-
+// TEST[setup:my_data_stream]
+// TEST[s/^/PUT my-data-stream\/_alias\/my-alias\n/]
+// TEST[teardown:data_stream_cleanup]
 
 [[get-alias-api-request]]
 ==== {api-request-title}
 
-`GET /_alias`
+`GET _alias/<alias>`
 
-`GET /_alias/<alias>`
+`GET _alias`
 
-`GET /<index>/_alias/<alias>`
+`GET <target>/_alias/<alias>`
 
 [[get-alias-api-api-prereqs]]
 ==== {api-prereq-title}
 
 * If the {es} {security-features} are enabled, you must have the
 `view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
-for the index alias. If you specify an index, you must also have
-`view_index_metadata` or `manage` index privilege for the index.
-
+for the alias. If you specify a target, you must also have `view_index_metadata`
+or `manage` index privilege for the target.
 
 [[get-alias-api-path-params]]
 ==== {api-path-parms-title}
 
 `<alias>`::
-(Optional, string)
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias]
-+
-To retrieve information for all index aliases,
-use a value of `_all` or `*`.
-
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
+(Optional, string) Comma-separated list of aliases to retrieve. Supports
+wildcards (`*`). To retrieve all aliases, omit this parameter or use `*` or
+`_all`.
 
+`<target>`::
+(Optional, string) Comma-separated list of data streams or indices used to limit
+the request. Supports wildcards (`*`). To target all data streams and indices,
+omit this parameter or use `*` or `_all`.
 
 [[get-alias-api-query-params]]
 ==== {api-query-parms-title}
@@ -57,133 +56,7 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
 Defaults to `all`.
 
 `ignore_unavailable`::
-(Optional, Boolean)
-If `false`, requests that include a missing index in the `<index>` argument
-return an error. Defaults to `false`.
+(Optional, Boolean) If `false`, requests that include a missing data stream or
+index in the `<target>` return an error. Defaults to `false`.
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]
-
-
-[[get-alias-api-example]]
-==== {api-examples-title}
-
-[[get-alias-api-all-ex]]
-===== Get all aliases for an index
-
-You can add index aliases during index creation
-using a <<indices-create-index,create index API>> request.
-
-The following create index API request creates the `logs_20302801` index
-with two aliases:
-
-* `current_day`
-* `2030`, which only returns documents
-in the `logs_20302801` index
-with a `year` field value of `2030`
-
-[source,console]
---------------------------------------------------
-PUT /logs_20302801
-{
-  "aliases" : {
-    "current_day" : {},
-    "2030" : {
-      "filter" : {
-          "term" : {"year" : 2030 }
-      }
-    }
-  }
-}
---------------------------------------------------
-
-The following get index alias API request returns all aliases
-for the index `logs_20302801`:
-
-[source,console]
---------------------------------------------------
-GET /logs_20302801/_alias/*
---------------------------------------------------
-// TEST[continued]
-
-The API returns the following response:
-
-[source,console-result]
---------------------------------------------------
-{
- "logs_20302801" : {
-   "aliases" : {
-    "current_day" : {
-    },
-     "2030" : {
-       "filter" : {
-         "term" : {
-           "year" : 2030
-         }
-       }
-     }
-   }
- }
-}
---------------------------------------------------
-
-
-[[get-alias-api-named-ex]]
-===== Get a specific alias
-
-The following index alias API request returns the `2030` alias:
-
-[source,console]
---------------------------------------------------
-GET /_alias/2030
---------------------------------------------------
-// TEST[continued]
-
-The API returns the following response:
-
-[source,console-result]
---------------------------------------------------
-{
-  "logs_20302801" : {
-    "aliases" : {
-      "2030" : {
-        "filter" : {
-          "term" : {
-            "year" : 2030
-          }
-        }
-      }
-    }
-  }
-}
---------------------------------------------------
-
-
-[[get-alias-api-wildcard-ex]]
-===== Get aliases based on a wildcard
-
-The following index alias API request returns any alias that begin with `20`:
-
-[source,console]
---------------------------------------------------
-GET /_alias/20*
---------------------------------------------------
-// TEST[continued]
-
-The API returns the following response:
-
-[source,console-result]
---------------------------------------------------
-{
-  "logs_20302801" : {
-    "aliases" : {
-      "2030" : {
-        "filter" : {
-          "term" : {
-            "year" : 2030
-          }
-        }
-      }
-    }
-  }
-}
---------------------------------------------------

docs/reference/rest-api/common-parms.asciidoc

@@ -18,11 +18,6 @@ the response only includes ongoing shard recoveries.
 Defaults to `false`.
 end::active-only[]
 
-tag::index-alias[]
-Comma-separated list or wildcard expression of index alias names
-used to limit the request.
-end::index-alias[]
-
 tag::aliases[]
 `aliases`::
 (Optional, <<alias,alias object>>) Index aliases which include the index. Index
@@ -297,14 +292,6 @@ in the `completion_fields` or `fielddata_fields` parameters.
 --
 end::fields[]
 
-tag::index-alias-filter[]
-<<query-dsl-bool-query, Filter query>>
-used to limit the index alias.
-+
-If specified,
-the index alias only applies to documents returned by the filter.
-end::index-alias-filter[]
-
 tag::flat-settings[]
 `flat_settings`::
 (Optional, Boolean) If `true`, returns settings in flat format. Defaults to