Skip to content

Commit 947fccb

Browse files
jrodewigjrodewig
authored
[DOCS] Add get index alias API docs (#46046)
1 parent 676433e commit 947fccb

File tree

5 files changed

+194
-119
lines changed

5 files changed

+194
-119
lines changed

‎docs/reference/indices.asciidoc

+3
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ index settings, aliases, mappings, and index templates.
3434
[float]
3535
[[alias-management]]
3636
=== Alias management:
37+
* <<indices-get-alias>>
3738
* <<indices-alias-exists>>
3839
* <<indices-aliases>>
3940

@@ -93,6 +94,8 @@ include::indices/get-field-mapping.asciidoc[]
9394

9495
include::indices/types-exists.asciidoc[]
9596

97+
include::indices/get-alias.asciidoc[]
98+
9699
include::indices/alias-exists.asciidoc[]
97100

98101
include::indices/aliases.asciidoc[]

‎docs/reference/indices/alias-exists.asciidoc

+1-2
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,7 @@ HEAD /_alias/alias1
3737

3838
`<alias>`::
3939
(Required, string)
40-
Comma-separated list or wildcard expression of index alias names
41-
used to limit the request.
40+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias]
4241

4342
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
4443

‎docs/reference/indices/aliases.asciidoc

-117
Original file line numberDiff line numberDiff line change
@@ -458,120 +458,3 @@ DELETE /logs_20162801/_alias/current_day
458458
--------------------------------------------------
459459
// CONSOLE
460460
// TEST[continued]
461-
462-
[float]
463-
[[alias-retrieving]]
464-
==== Retrieving existing aliases
465-
466-
The get index alias API allows to filter by
467-
alias name and index name. This api redirects to the master and fetches
468-
the requested index aliases, if available. This api only serialises the
469-
found index aliases.
470-
471-
Possible options:
472-
[horizontal]
473-
`index`::
474-
The index name to get aliases for. Partial names are
475-
supported via wildcards, also multiple index names can be specified
476-
separated with a comma. Also the alias name for an index can be used.
477-
478-
`alias`::
479-
The name of alias to return in the response. Like the index
480-
option, this option supports wildcards and the option the specify
481-
multiple alias names separated by a comma.
482-
483-
`ignore_unavailable`::
484-
What to do if an specified index name doesn't
485-
exist. If set to `true` then those indices are ignored.
486-
487-
The rest endpoint is: `/{index}/_alias/{alias}`.
488-
489-
[float]
490-
===== Examples:
491-
492-
All aliases for the index `logs_20162801`:
493-
494-
[source,js]
495-
--------------------------------------------------
496-
GET /logs_20162801/_alias/*
497-
--------------------------------------------------
498-
// CONSOLE
499-
// TEST[continued]
500-
501-
Response:
502-
503-
[source,js]
504-
--------------------------------------------------
505-
{
506-
"logs_20162801" : {
507-
"aliases" : {
508-
"2016" : {
509-
"filter" : {
510-
"term" : {
511-
"year" : 2016
512-
}
513-
}
514-
}
515-
}
516-
}
517-
}
518-
--------------------------------------------------
519-
// TESTRESPONSE
520-
521-
All aliases with the name 2016 in any index:
522-
523-
[source,js]
524-
--------------------------------------------------
525-
GET /_alias/2016
526-
--------------------------------------------------
527-
// CONSOLE
528-
// TEST[continued]
529-
530-
Response:
531-
532-
[source,js]
533-
--------------------------------------------------
534-
{
535-
"logs_20162801" : {
536-
"aliases" : {
537-
"2016" : {
538-
"filter" : {
539-
"term" : {
540-
"year" : 2016
541-
}
542-
}
543-
}
544-
}
545-
}
546-
}
547-
--------------------------------------------------
548-
// TESTRESPONSE
549-
550-
All aliases that start with 20 in any index:
551-
552-
[source,js]
553-
--------------------------------------------------
554-
GET /_alias/20*
555-
--------------------------------------------------
556-
// CONSOLE
557-
// TEST[continued]
558-
559-
Response:
560-
561-
[source,js]
562-
--------------------------------------------------
563-
{
564-
"logs_20162801" : {
565-
"aliases" : {
566-
"2016" : {
567-
"filter" : {
568-
"term" : {
569-
"year" : 2016
570-
}
571-
}
572-
}
573-
}
574-
}
575-
}
576-
--------------------------------------------------
577-
// TESTRESPONSE

‎docs/reference/indices/get-alias.asciidoc

+185
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
[[indices-get-alias]]
2+
=== Get index alias API
3+
++++
4+
<titleabbrev>Get index alias</titleabbrev>
5+
++++
6+
7+
Returns information about one or more index aliases.
8+
9+
include::alias-exists.asciidoc[tag=index-alias-def]
10+
11+
[source,js]
12+
----
13+
GET /twitter/_alias/alias1
14+
----
15+
// CONSOLE
16+
// TEST[setup:twitter]
17+
// TEST[s/^/PUT twitter\/_alias\/alias1\n/]
18+
19+
20+
[[get-alias-api-request]]
21+
==== {api-request-title}
22+
23+
`GET /_alias`
24+
25+
`GET /_alias/<alias>`
26+
27+
`GET /<index>/_alias/<alias>`
28+
29+
30+
[[get-alias-api-path-params]]
31+
==== {api-path-parms-title}
32+
33+
`<alias>`::
34+
(Optional, string)
35+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias]
36+
+
37+
To retrieve information for all index aliases,
38+
use a value of `_all` or `*`.
39+
40+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
41+
42+
43+
[[get-alias-api-query-params]]
44+
==== {api-query-parms-title}
45+
46+
include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
47+
48+
include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
49+
+
50+
Defaults to `all`.
51+
52+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
53+
54+
include::{docdir}/rest-api/common-parms.asciidoc[tag=local]
55+
56+
57+
[[get-alias-api-example]]
58+
==== {api-examples-title}
59+
60+
[[get-alias-api-all-ex]]
61+
===== Get all aliases for an index
62+
63+
You can add index aliases during index creation
64+
using a <<indices-create-index,create index API>> request.
65+
66+
The following create index API request creates the `logs_20302801` index
67+
with two aliases:
68+
69+
* `current_day`
70+
* `2030`, which only returns documents
71+
in the `logs_20302801` index
72+
with a `year` field value of `2030`
73+
74+
[source,js]
75+
--------------------------------------------------
76+
PUT /logs_20302801
77+
{
78+
"aliases" : {
79+
"current_day" : {},
80+
"2030" : {
81+
"filter" : {
82+
"term" : {"year" : 2030 }
83+
}
84+
}
85+
}
86+
}
87+
--------------------------------------------------
88+
// CONSOLE
89+
90+
The following get index alias API request returns all aliases
91+
for the index `logs_20302801`:
92+
93+
[source,js]
94+
--------------------------------------------------
95+
GET /logs_20302801/_alias/*
96+
--------------------------------------------------
97+
// CONSOLE
98+
// TEST[continued]
99+
100+
The API returns the following response:
101+
102+
[source,js]
103+
--------------------------------------------------
104+
{
105+
"logs_20302801" : {
106+
"aliases" : {
107+
"current_day" : {
108+
},
109+
"2030" : {
110+
"filter" : {
111+
"term" : {
112+
"year" : 2030
113+
}
114+
}
115+
}
116+
}
117+
}
118+
}
119+
--------------------------------------------------
120+
// TESTRESPONSE
121+
122+
123+
[[get-alias-api-named-ex]]
124+
===== Get a specific alias
125+
126+
The following index alias API request returns the `2030` alias:
127+
128+
[source,js]
129+
--------------------------------------------------
130+
GET /_alias/2030
131+
--------------------------------------------------
132+
// CONSOLE
133+
// TEST[continued]
134+
135+
The API returns the following response:
136+
137+
[source,js]
138+
--------------------------------------------------
139+
{
140+
"logs_20302801" : {
141+
"aliases" : {
142+
"2030" : {
143+
"filter" : {
144+
"term" : {
145+
"year" : 2030
146+
}
147+
}
148+
}
149+
}
150+
}
151+
}
152+
--------------------------------------------------
153+
// TESTRESPONSE
154+
155+
[[get-alias-api-wildcard-ex]]
156+
===== Get aliases based on a wildcard
157+
158+
The following index alias API request returns any alias that begin with `20`:
159+
160+
[source,js]
161+
--------------------------------------------------
162+
GET /_alias/20*
163+
--------------------------------------------------
164+
// CONSOLE
165+
// TEST[continued]
166+
167+
The API returns the following response:
168+
169+
[source,js]
170+
--------------------------------------------------
171+
{
172+
"logs_20302801" : {
173+
"aliases" : {
174+
"2030" : {
175+
"filter" : {
176+
"term" : {
177+
"year" : 2030
178+
}
179+
}
180+
}
181+
}
182+
}
183+
}
184+
--------------------------------------------------
185+
// TESTRESPONSE

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

+5
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11

2+
tag::index-alias[]
3+
Comma-separated list or wildcard expression of index alias names
4+
used to limit the request.
5+
end::index-alias[]
6+
27
tag::allow-no-indices[]
38
`allow_no_indices`::
49
(Optional, boolean) If `true`, the request returns an error if a wildcard

0 commit comments

Comments
 (0)