From 62afd076ef5fe443bcf96dd60b80e40f749f0a36 Mon Sep 17 00:00:00 2001 From: gaobinlong Date: Tue, 23 Jan 2024 17:25:15 +0800 Subject: [PATCH 1/9] Create or Update alias API supports must_exist parameter Signed-off-by: gaobinlong --- _im-plugin/index-alias.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index 97e10f6569..919df75b8a 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -126,6 +126,23 @@ POST _aliases } ``` +In addition, `remove` action supports `must_exist` paramater, if it is `true` and the specified alias doesn't exist, an exception will be thrown, if it is `false`, nothing happens if the specified alias doesn't exist. The default value of `must_exist` is `null`, only if all of the specified aliases don't exist, an exception will be thrown. + +```json +POST _aliases +{ + "actions": [ + { + "remove": { + "index": "index-1", + "alias": "alias1", + "must_exist": true + } + } + ] +} +``` + ## Manage aliases To list the mapping of aliases to indexes, run the following command: @@ -247,4 +264,4 @@ For example, if `alias1` refers to `index-1` and `index-2`, you can run the foll DELETE index-1/_alias/alias1 ``` -After you run the request above, `alias1` no longer refers to `index-1`, but still refers to `index-2`. \ No newline at end of file +After you run the request above, `alias1` no longer refers to `index-1`, but still refers to `index-2`. From 83d918582791357fad2554347f73d512a866d961 Mon Sep 17 00:00:00 2001 From: gaobinlong Date: Tue, 30 Jan 2024 13:35:50 +0800 Subject: [PATCH 2/9] Update _im-plugin/index-alias.md Co-authored-by: Melissa Vagi Signed-off-by: gaobinlong --- _im-plugin/index-alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index 919df75b8a..8da6f3caa9 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -126,7 +126,7 @@ POST _aliases } ``` -In addition, `remove` action supports `must_exist` paramater, if it is `true` and the specified alias doesn't exist, an exception will be thrown, if it is `false`, nothing happens if the specified alias doesn't exist. The default value of `must_exist` is `null`, only if all of the specified aliases don't exist, an exception will be thrown. +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. ```json POST _aliases From 2fa9230ef63f393d4b6b2c3eebb278ec796ea7c2 Mon Sep 17 00:00:00 2001 From: gaobinlong Date: Tue, 30 Jan 2024 13:35:56 +0800 Subject: [PATCH 3/9] Update _im-plugin/index-alias.md Co-authored-by: Melissa Vagi Signed-off-by: gaobinlong --- _im-plugin/index-alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index 8da6f3caa9..71fe549989 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -264,4 +264,4 @@ For example, if `alias1` refers to `index-1` and `index-2`, you can run the foll DELETE index-1/_alias/alias1 ``` -After you run the request above, `alias1` no longer refers to `index-1`, but still refers to `index-2`. +After running the previous request, `alias1` no longer refers to `index-1`, but still refers to `index-2`. From 22a5639d1401b03876b5c0af17a18c4a727eef7f Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 30 Jan 2024 11:53:06 -0700 Subject: [PATCH 4/9] Update index-alias.md Add copy tags --- _im-plugin/index-alias.md | 55 ++++++++++++++++++++++----------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index 71fe549989..37eb857c02 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -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 /_aliases/ PUT /_alias/ POST /_alias/ ``` +{% include copy-curl.html %} The `` 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 that the alias references, 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 in 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,8 +120,11 @@ 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 `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 `must_exist` parameter set to `true`: ```json POST _aliases @@ -142,6 +140,7 @@ POST _aliases ] } ``` +{% include copy-curl.html %} ## Manage aliases @@ -150,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 @@ -157,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 @@ -175,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: @@ -195,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 like that shown in the following PUT request: ```json PUT index-1 @@ -208,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 from the underlying indexes. This command adds only a specific timestamp field to `alias1`. The following shows a POST request example: ```json POST _aliases @@ -233,6 +238,7 @@ POST _aliases ] } ``` +{% include copy-curl.html %} ## Index alias options @@ -246,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: @@ -255,6 +260,7 @@ To delete one or more aliases from an index, use the following request: DELETE /_alias/ DELETE /_aliases/ ``` +{% include copy-curl.html %} Both `` and `` in the above request support comma-separated lists and wildcard expressions. Use `_all` in place of `` to delete all aliases for the indexes listed in ``. @@ -263,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 running the previous request, `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`. From 5d1f48a2055d4718dafe759a01b6614c4bcb16ed Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 30 Jan 2024 12:21:05 -0700 Subject: [PATCH 5/9] Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _im-plugin/index-alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index 37eb857c02..31950541ca 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -73,7 +73,7 @@ GET /index-1/_alias/alias1 ``` {% include copy-curl.html %} -To get the indexes' mappings and settings information 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 From 5a3a51faf079dbb297e398081131864bb5919e62 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 30 Jan 2024 12:21:15 -0700 Subject: [PATCH 6/9] Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _im-plugin/index-alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index 31950541ca..e78cad2d63 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -82,7 +82,7 @@ GET alias1 ## 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 From 25946cf75dd7ce44e9fecd6471df85cb5823c7e8 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 30 Jan 2024 12:21:28 -0700 Subject: [PATCH 7/9] Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _im-plugin/index-alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index e78cad2d63..cd4b6938e6 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -124,7 +124,7 @@ POST _aliases 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 `must_exist` parameter set to `true`: +The following POST request uses the `remove` action with the `must_exist` parameter set to `true`: ```json POST _aliases From d66001f66654c4c950f8c672f3022743dbfd431c Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 30 Jan 2024 12:21:38 -0700 Subject: [PATCH 8/9] Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _im-plugin/index-alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index cd4b6938e6..ed310f1c2e 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -204,7 +204,7 @@ HEAD index-1/_alias/alias1/ ## Add aliases at index creation -You can add an index to an alias as you create the index like that shown in the following PUT request: +You can add an index to an alias as you create the index, as shown in the following PUT request: ```json PUT index-1 From c5229639e9283218531afb8c57e13a2c2ce4a2ce Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 30 Jan 2024 12:21:47 -0700 Subject: [PATCH 9/9] Update _im-plugin/index-alias.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _im-plugin/index-alias.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-alias.md b/_im-plugin/index-alias.md index ed310f1c2e..1816b0e0d2 100644 --- a/_im-plugin/index-alias.md +++ b/_im-plugin/index-alias.md @@ -218,7 +218,7 @@ PUT index-1 ## 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`. The following shows a POST request example: +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