From 46819abe0a835659c59fa7d19c021ca981ed12e5 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 29 Aug 2019 09:44:58 -0400 Subject: [PATCH] [DOCS] Add get index alias API docs (#46046) --- docs/reference/indices.asciidoc | 3 + docs/reference/indices/alias-exists.asciidoc | 3 +- docs/reference/indices/aliases.asciidoc | 117 ----------- docs/reference/indices/get-alias.asciidoc | 185 ++++++++++++++++++ docs/reference/rest-api/common-parms.asciidoc | 5 + 5 files changed, 194 insertions(+), 119 deletions(-) create mode 100644 docs/reference/indices/get-alias.asciidoc diff --git a/docs/reference/indices.asciidoc b/docs/reference/indices.asciidoc index 6769d786a6917..7d1bf2fb30fb9 100644 --- a/docs/reference/indices.asciidoc +++ b/docs/reference/indices.asciidoc @@ -34,6 +34,7 @@ index settings, aliases, mappings, and index templates. [float] [[alias-management]] === Alias management: +* <> * <> * <> @@ -93,6 +94,8 @@ include::indices/get-field-mapping.asciidoc[] include::indices/types-exists.asciidoc[] +include::indices/get-alias.asciidoc[] + include::indices/alias-exists.asciidoc[] include::indices/aliases.asciidoc[] diff --git a/docs/reference/indices/alias-exists.asciidoc b/docs/reference/indices/alias-exists.asciidoc index c7790e6a6037c..e1398f079952e 100644 --- a/docs/reference/indices/alias-exists.asciidoc +++ b/docs/reference/indices/alias-exists.asciidoc @@ -37,8 +37,7 @@ HEAD /_alias/alias1 ``:: (Required, string) -Comma-separated list or wildcard expression of index alias names -used to limit the request. +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias] include::{docdir}/rest-api/common-parms.asciidoc[tag=index] diff --git a/docs/reference/indices/aliases.asciidoc b/docs/reference/indices/aliases.asciidoc index bc207b9f226b0..03ef3a4ca5c2a 100644 --- a/docs/reference/indices/aliases.asciidoc +++ b/docs/reference/indices/aliases.asciidoc @@ -458,120 +458,3 @@ DELETE /logs_20162801/_alias/current_day -------------------------------------------------- // CONSOLE // TEST[continued] - -[float] -[[alias-retrieving]] -==== Retrieving existing aliases - -The get index alias API allows to filter by -alias name and index name. This api redirects to the master and fetches -the requested index aliases, if available. This api only serialises the -found index aliases. - -Possible options: -[horizontal] -`index`:: - The index name to get aliases for. Partial names are - supported via wildcards, also multiple index names can be specified - separated with a comma. Also the alias name for an index can be used. - -`alias`:: - The name of alias to return in the response. Like the index - option, this option supports wildcards and the option the specify - multiple alias names separated by a comma. - -`ignore_unavailable`:: - What to do if an specified index name doesn't - exist. If set to `true` then those indices are ignored. - -The rest endpoint is: `/{index}/_alias/{alias}`. - -[float] -===== Examples: - -All aliases for the index `logs_20162801`: - -[source,js] --------------------------------------------------- -GET /logs_20162801/_alias/* --------------------------------------------------- -// CONSOLE -// TEST[continued] - -Response: - -[source,js] --------------------------------------------------- -{ - "logs_20162801" : { - "aliases" : { - "2016" : { - "filter" : { - "term" : { - "year" : 2016 - } - } - } - } - } -} --------------------------------------------------- -// TESTRESPONSE - -All aliases with the name 2016 in any index: - -[source,js] --------------------------------------------------- -GET /_alias/2016 --------------------------------------------------- -// CONSOLE -// TEST[continued] - -Response: - -[source,js] --------------------------------------------------- -{ - "logs_20162801" : { - "aliases" : { - "2016" : { - "filter" : { - "term" : { - "year" : 2016 - } - } - } - } - } -} --------------------------------------------------- -// TESTRESPONSE - -All aliases that start with 20 in any index: - -[source,js] --------------------------------------------------- -GET /_alias/20* --------------------------------------------------- -// CONSOLE -// TEST[continued] - -Response: - -[source,js] --------------------------------------------------- -{ - "logs_20162801" : { - "aliases" : { - "2016" : { - "filter" : { - "term" : { - "year" : 2016 - } - } - } - } - } -} --------------------------------------------------- -// TESTRESPONSE diff --git a/docs/reference/indices/get-alias.asciidoc b/docs/reference/indices/get-alias.asciidoc new file mode 100644 index 0000000000000..9a66eb65d4d54 --- /dev/null +++ b/docs/reference/indices/get-alias.asciidoc @@ -0,0 +1,185 @@ +[[indices-get-alias]] +=== Get index alias API +++++ +Get index alias +++++ + +Returns information about one or more index aliases. + +include::alias-exists.asciidoc[tag=index-alias-def] + +[source,js] +---- +GET /twitter/_alias/alias1 +---- +// CONSOLE +// TEST[setup:twitter] +// TEST[s/^/PUT twitter\/_alias\/alias1\n/] + + +[[get-alias-api-request]] +==== {api-request-title} + +`GET /_alias` + +`GET /_alias/` + +`GET //_alias/` + + +[[get-alias-api-path-params]] +==== {api-path-parms-title} + +``:: +(Optional, string) +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias] ++ +To retrieve information for all index aliases, +use a value of `_all` or `*`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] + + +[[get-alias-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] ++ +Defaults to `all`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] + +include::{docdir}/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 <> 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,js] +-------------------------------------------------- +PUT /logs_20302801 +{ + "aliases" : { + "current_day" : {}, + "2030" : { + "filter" : { + "term" : {"year" : 2030 } + } + } + } +} +-------------------------------------------------- +// CONSOLE + +The following get index alias API request returns all aliases +for the index `logs_20302801`: + +[source,js] +-------------------------------------------------- +GET /logs_20302801/_alias/* +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +The API returns the following response: + +[source,js] +-------------------------------------------------- +{ + "logs_20302801" : { + "aliases" : { + "current_day" : { + }, + "2030" : { + "filter" : { + "term" : { + "year" : 2030 + } + } + } + } + } +} +-------------------------------------------------- +// TESTRESPONSE + + +[[get-alias-api-named-ex]] +===== Get a specific alias + +The following index alias API request returns the `2030` alias: + +[source,js] +-------------------------------------------------- +GET /_alias/2030 +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +The API returns the following response: + +[source,js] +-------------------------------------------------- +{ + "logs_20302801" : { + "aliases" : { + "2030" : { + "filter" : { + "term" : { + "year" : 2030 + } + } + } + } + } +} +-------------------------------------------------- +// TESTRESPONSE + +[[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,js] +-------------------------------------------------- +GET /_alias/20* +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +The API returns the following response: + +[source,js] +-------------------------------------------------- +{ + "logs_20302801" : { + "aliases" : { + "2030" : { + "filter" : { + "term" : { + "year" : 2030 + } + } + } + } + } +} +-------------------------------------------------- +// TESTRESPONSE diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 971aa386e4ed6..d9ff7626e0a1f 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -1,4 +1,9 @@ +tag::index-alias[] +Comma-separated list or wildcard expression of index alias names +used to limit the request. +end::index-alias[] + tag::allow-no-indices[] `allow_no_indices`:: (Optional, boolean) If `true`, the request returns an error if a wildcard