|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Create or Update Alias |
| 4 | +parent: Index APIs |
| 5 | +nav_order: 5 |
| 6 | +--- |
| 7 | + |
| 8 | +# Create or Update Alias |
| 9 | +**Introduced 1.0** |
| 10 | +{: .label .label-purple } |
| 11 | + |
| 12 | +The Create or Update Alias API adds a data stream or index to an alias or updates the settings for an existing alias. For more alias API operations, see [Index aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias/). |
| 13 | + |
| 14 | +The Create or Update Alias API is distinct from the [Alias API]({{site.url}}{{site.baseurl}}/opensearch/rest-api/alias/), which supports the addition and removal of aliases and the removal of alias indexes. In contrast, the following API only supports adding or updating an alias without updating the index itself. Each API also uses different request body parameters. |
| 15 | +{: .note} |
| 16 | + |
| 17 | +## Path and HTTP methods |
| 18 | + |
| 19 | +``` |
| 20 | +POST /<target>/_alias/<alias-name> |
| 21 | +PUT /<target>/_alias/<alias-name> |
| 22 | +POST /_alias/<alias-name> |
| 23 | +PUT /_alias/<alias-name> |
| 24 | +POST /<target>/_aliases/<alias-name> |
| 25 | +PUT /<target>/_aliases/<alias-name> |
| 26 | +POST /_aliases/<alias-name> |
| 27 | +PUT /_aliases/<alias-name> |
| 28 | +PUT /<target>/_alias |
| 29 | +PUT /<target>/_aliases |
| 30 | +PUT /_alias |
| 31 | +``` |
| 32 | + |
| 33 | +## Path parameters |
| 34 | + |
| 35 | +| Parameter | Type | Description | |
| 36 | +:--- | :--- | :--- |
| 37 | +| `target` | String | A comma-delimited list of data streams and indexes. Wildcard expressions (`*`) are supported. To target all data streams and indexes in a cluster, use `_all` or `*`. Optional. | |
| 38 | +| `alias-name` | String | The alias name to be created or updated. Optional. | |
| 39 | + |
| 40 | +## Query parameters |
| 41 | + |
| 42 | +All query parameters are optional. |
| 43 | + |
| 44 | +Parameter | Type | Description |
| 45 | +:--- | :--- | :--- |
| 46 | +`cluster_manager_timeout` | Time | The amount of time to wait for a response from the cluster manager node. Default is `30s`. |
| 47 | +`timeout` | Time | The amount of time to wait for a response from the cluster. Default is `30s`. |
| 48 | + |
| 49 | +## Request body |
| 50 | + |
| 51 | +In the request body, you can specify the index name, the alias name, and the settings for the alias. All fields are optional. |
| 52 | + |
| 53 | +Field | Type | Description |
| 54 | +:--- | :--- | :--- | :--- |
| 55 | +`index` | String | A comma-delimited list of data streams or indexes that you want to associate with the alias. If this field is set, it will override the index name specified in the URL path. |
| 56 | +`alias` | String | The name of the alias. If this field is set, it will override the alias name specified in the URL path. |
| 57 | +`is_write_index` | Boolean | Specifies whether the index should be a write index. An alias can only have one write index at a time. If a write request is submitted to an alias that links to multiple indexes, then OpenSearch runs the request only on the write index. |
| 58 | +`routing` | String | Assigns a custom value to a shard for specific operations. |
| 59 | +`index_routing` | String | Assigns a custom value to a shard only for index operations. |
| 60 | +`search_routing` | String | Assigns a custom value to a shard only for search operations. |
| 61 | +`filter` | Object | A filter to use with the alias so that the alias points to a filtered part of the index. |
| 62 | + |
| 63 | +## Example request |
| 64 | + |
| 65 | +The following example request adds a sample alias with a custom routing value: |
| 66 | + |
| 67 | +```json |
| 68 | +POST sample-index/_alias/sample-alias |
| 69 | +{ |
| 70 | + "routing":"test" |
| 71 | +} |
| 72 | +``` |
| 73 | +{% include copy-curl.html %} |
| 74 | + |
| 75 | +## Example response |
| 76 | + |
| 77 | +```json |
| 78 | +{ |
| 79 | + "acknowledged": true |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +For more alias API operations, see [Index aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias/). |
0 commit comments