Create or Update alias API supports must_exist parameter (#6245)
* Create or Update alias API supports must_exist parameter Signed-off-by: gaobinlong <gbinlong@amazon.com> * Update _im-plugin/index-alias.md Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: gaobinlong <gbinlong@amazon.com> * Update _im-plugin/index-alias.md Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: gaobinlong <gbinlong@amazon.com> * Update index-alias.md Add copy tags * Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower <nbower@amazon.com> Signed-off-by: Melissa Vagi <vagimeli@amazon.com> --------- Signed-off-by: gaobinlong <gbinlong@amazon.com> Signed-off-by: Melissa Vagi <vagimeli@amazon.com> Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Co-authored-by: Nathan Bower <nbower@amazon.com>
This commit is contained in:
gaobinlong
GitHub
parent
52afeb1065
commit
acd5ba5ed1
|
|
@ -16,15 +16,6 @@ For example, if you’re storing logs into indexes based on the month and you fr
|
|||
|
||||
Because you can change the indexes an alias points to at any time, referring to indexes using aliases in your applications allows you to reindex your data without any downtime.
|
||||
|
||||
---
|
||||
|
||||
#### Table of contents
|
||||
1. TOC
|
||||
{:toc}
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Create aliases
|
||||
|
||||
To create an alias, use a POST request:
|
||||
|
|
@ -32,6 +23,7 @@ To create an alias, use a POST request:
|
|||
```json
|
||||
POST _aliases
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
Use the `actions` method to specify the list of actions that you want to perform. This command creates an alias named `alias1` and adds `index-1` to this alias:
|
||||
|
||||
|
|
@ -48,16 +40,18 @@ POST _aliases
|
|||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
You should see the following response:
|
||||
The following response is returned:
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
If this request fails, make sure the index that you're adding to the alias already exists.
|
||||
If the request fails, make sure the index that you're adding to the alias already exists.
|
||||
|
||||
You can also create an alias using one of the following requests:
|
||||
|
||||
|
|
@ -67,6 +61,7 @@ POST <index>/_aliases/<alias name>
|
|||
PUT <index>/_alias/<alias name>
|
||||
POST <index>/_alias/<alias name>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The `<index>` in the above requests can be an index name, a comma-separated list of index names, or a wildcard expression. Use `_all` to refer to all indexes.
|
||||
|
||||
|
|
@ -76,17 +71,18 @@ To check if `alias1` refers to `index-1`, run one of the following commands:
|
|||
GET /_alias/alias1
|
||||
GET /index-1/_alias/alias1
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
To get the mappings and settings information of the indexes that the alias references, run the following command:
|
||||
To get the indexes' mappings and settings information referenced by the alias, run the following command:
|
||||
|
||||
```json
|
||||
GET alias1
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
## Add or remove indexes
|
||||
|
||||
You can perform multiple actions in the same `_aliases` operation.
|
||||
For example, the following command removes `index-1` and adds `index-2` to `alias1`:
|
||||
You can perform multiple actions using the same `_aliases` operation. For example, the following command removes `index-1` and adds `index-2` to `alias1`:
|
||||
|
||||
```json
|
||||
POST _aliases
|
||||
|
|
@ -107,10 +103,9 @@ POST _aliases
|
|||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The `add` and `remove` actions occur atomically, which means that at no point will `alias1` point to both `index-1` and `index-2`.
|
||||
|
||||
You can also add indexes based on an index pattern:
|
||||
The `add` and `remove` actions occur atomically, which means that at no point will `alias1` point to both `index-1` and `index-2`. You can also add indexes based on an index pattern, as shown in the following POST request:
|
||||
|
||||
```json
|
||||
POST _aliases
|
||||
|
|
@ -125,6 +120,27 @@ POST _aliases
|
|||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The `remove` action also supports the `must_exist` parameter. If the parameter is set to `true` and the specified alias does not exist, an exception is thrown. If the parameter is set to `false`, then no action is taken if the specified alias does not exist. The default value for `must_exist` is `null`. An exception will be thrown only if none of the specified aliases exist.
|
||||
|
||||
The following POST request uses the `remove` action with the `must_exist` parameter set to `true`:
|
||||
|
||||
```json
|
||||
POST _aliases
|
||||
{
|
||||
"actions": [
|
||||
{
|
||||
"remove": {
|
||||
"index": "index-1",
|
||||
"alias": "alias1",
|
||||
"must_exist": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
## Manage aliases
|
||||
|
||||
|
|
@ -133,6 +149,7 @@ To list the mapping of aliases to indexes, run the following command:
|
|||
```json
|
||||
GET _cat/aliases?v
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example response
|
||||
|
||||
|
|
@ -140,12 +157,14 @@ GET _cat/aliases?v
|
|||
alias index filter routing.index routing.search
|
||||
alias1 index-1 * - -
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
To check which indexes an alias points to, run the following command:
|
||||
|
||||
```json
|
||||
GET _alias/alias1
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example response
|
||||
|
||||
|
|
@ -158,18 +177,21 @@ GET _alias/alias1
|
|||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
Conversely, to find which alias points to a specific index, run the following command:
|
||||
|
||||
```json
|
||||
GET /index-2/_alias/*
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
To get all index names and their aliases, run the following command:
|
||||
|
||||
```json
|
||||
GET /_alias
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
To check if an alias exists, run one of the following commands:
|
||||
|
||||
|
|
@ -178,10 +200,11 @@ HEAD /alias1/_alias/
|
|||
HEAD /_alias/alias1/
|
||||
HEAD index-1/_alias/alias1/
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
## Add aliases at index creation
|
||||
|
||||
You can add an index to an alias as you create the index:
|
||||
You can add an index to an alias as you create the index, as shown in the following PUT request:
|
||||
|
||||
```json
|
||||
PUT index-1
|
||||
|
|
@ -191,12 +214,11 @@ PUT index-1
|
|||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
## Create filtered aliases
|
||||
|
||||
You can create a filtered alias to access a subset of documents or fields from the underlying indexes.
|
||||
|
||||
This command adds only a specific timestamp field to `alias1`:
|
||||
You can create a filtered alias to access a subset of documents or fields in the underlying indexes. This command adds only a specific timestamp field to `alias1`. The following shows an example POST request:
|
||||
|
||||
```json
|
||||
POST _aliases
|
||||
|
|
@ -216,6 +238,7 @@ POST _aliases
|
|||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
## Index alias options
|
||||
|
||||
|
|
@ -229,7 +252,6 @@ Option | Valid values | Description | Required
|
|||
`routing` | String | Limit search to an associated shard value. You can specify `search_routing` and `index_routing` independently. | No
|
||||
`is_write_index` | String | Specify the index that accepts any write operations to the alias. If this value is not specified, then no write operations are allowed. | No
|
||||
|
||||
|
||||
## Delete aliases
|
||||
|
||||
To delete one or more aliases from an index, use the following request:
|
||||
|
|
@ -238,6 +260,7 @@ To delete one or more aliases from an index, use the following request:
|
|||
DELETE <index>/_alias/<alias>
|
||||
DELETE <index>/_aliases/<alias>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
Both `<index>` and `<alias>` in the above request support comma-separated lists and wildcard expressions. Use `_all` in place of `<alias>` to delete all aliases for the indexes listed in `<index>`.
|
||||
|
||||
|
|
@ -246,5 +269,6 @@ For example, if `alias1` refers to `index-1` and `index-2`, you can run the foll
|
|||
```json
|
||||
DELETE index-1/_alias/alias1
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
After you run the request above, `alias1` no longer refers to `index-1`, but still refers to `index-2`.
|
||||
After running the request, `alias1` no longer refers to `index-1` but still refers to `index-2`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue