Skip to content

Commit 79f26f8

Browse files
jrodewigjrodewig
committed
[DOCS] Separate add index alias API docs (#46086)
1 parent 3e62cf9 commit 79f26f8

File tree

4 files changed

+167
-129
lines changed

4 files changed

+167
-129
lines changed

‎docs/reference/indices.asciidoc‎

Lines changed: 3 additions & 0 deletions
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-add-alias>>
3738
* <<indices-get-alias>>
3839
* <<indices-alias-exists>>
3940
* <<indices-aliases>>
@@ -94,6 +95,8 @@ include::indices/get-field-mapping.asciidoc[]
9495

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

98+
include::indices/add-alias.asciidoc[]
99+
97100
include::indices/get-alias.asciidoc[]
98101

99102
include::indices/alias-exists.asciidoc[]

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

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
[[indices-add-alias]]
2+
=== Add index alias API
3+
++++
4+
<titleabbrev>Add index alias</titleabbrev>
5+
++++
6+
7+
Creates or updates an index alias.
8+
9+
include::alias-exists.asciidoc[tag=index-alias-def]
10+
11+
[source,js]
12+
----
13+
PUT /twitter/_alias/alias1
14+
----
15+
// CONSOLE
16+
// TEST[setup:twitter]
17+
18+
19+
[[add-alias-api-request]]
20+
==== {api-request-title}
21+
22+
`PUT /<index>/_alias/<alias>`
23+
24+
`POST /<index>/_alias/<alias>`
25+
26+
`PUT /<index>/_aliases/<alias>`
27+
28+
`POST /<index>/_aliases/<alias>`
29+
30+
31+
[[add-alias-api-path-params]]
32+
==== {api-path-parms-title}
33+
34+
`<index>`::
35+
(Required, string)
36+
Comma-separated list or wildcard expression of index names
37+
to add to the alias.
38+
+
39+
To add all indices in the cluster to the alias,
40+
use a value of `_all`.
41+
42+
`<alias>`::
43+
(Required, string)
44+
Name of the index alias to create or update.
45+
46+
47+
[[add-alias-api-query-params]]
48+
==== {api-query-parms-title}
49+
50+
include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
51+
52+
53+
[[add-alias-api-request-body]]
54+
==== {api-request-body-title}
55+
56+
`filter`::
57+
(Required, query object)
58+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-alias-filter]
59+
60+
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-routing]
61+
62+
[[add-alias-api-example]]
63+
==== {api-examples-title}
64+
65+
[[alias-adding]]
66+
===== Add a time-based alias
67+
68+
The following request creates an alias, `2030`,
69+
for the `logs_20302801` index.
70+
71+
[source,js]
72+
--------------------------------------------------
73+
PUT /logs_20302801/_alias/2030
74+
--------------------------------------------------
75+
// CONSOLE
76+
// TEST[s/^/PUT logs_20302801\n/]
77+
78+
[[add-alias-api-user-ex]]
79+
===== Add a user-based alias
80+
81+
First, create an index, `users`,
82+
with a mapping for the `user_id` field:
83+
84+
[source,js]
85+
--------------------------------------------------
86+
PUT /users
87+
{
88+
"mappings" : {
89+
"properties" : {
90+
"user_id" : {"type" : "integer"}
91+
}
92+
}
93+
}
94+
--------------------------------------------------
95+
// CONSOLE
96+
97+
Then add the index alias for a specific user, `user_12`:
98+
99+
[source,js]
100+
--------------------------------------------------
101+
PUT /users/_alias/user_12
102+
{
103+
"routing" : "12",
104+
"filter" : {
105+
"term" : {
106+
"user_id" : 12
107+
}
108+
}
109+
}
110+
--------------------------------------------------
111+
// CONSOLE
112+
// TEST[continued]
113+
114+
[[alias-index-creation]]
115+
===== Add an alias during index creation
116+
117+
You can use the <<create-index-aliases,create index API>>
118+
to add an index alias during index creation.
119+
120+
[source,js]
121+
--------------------------------------------------
122+
PUT /logs_20302801
123+
{
124+
"mappings" : {
125+
"properties" : {
126+
"year" : {"type" : "integer"}
127+
}
128+
},
129+
"aliases" : {
130+
"current_day" : {},
131+
"2030" : {
132+
"filter" : {
133+
"term" : {"year" : 2030 }
134+
}
135+
}
136+
}
137+
}
138+
--------------------------------------------------
139+
// CONSOLE

‎docs/reference/indices/aliases.asciidoc‎

Lines changed: 0 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -339,122 +339,3 @@ only reference one index, will have that referenced index behave as if it is the
339339
until an additional index is referenced. At that point, there will be no write index and
340340
writes will be rejected.
341341
=====================================
342-
343-
[float]
344-
[[alias-adding]]
345-
==== Add a single alias
346-
347-
An alias can also be added with the endpoint
348-
349-
`PUT /{index}/_alias/{name}`
350-
351-
352-
where
353-
354-
[horizontal]
355-
`index`:: The index the alias refers to. Can be any of `* | _all | glob pattern | name1, name2, …`
356-
`name`:: The name of the alias. This is a required option.
357-
`routing`:: An optional routing that can be associated with an alias.
358-
`filter`:: An optional filter that can be associated with an alias.
359-
360-
You can also use the plural `_aliases`.
361-
362-
[float]
363-
===== Examples:
364-
365-
Adding time based alias::
366-
+
367-
--
368-
[source,js]
369-
--------------------------------------------------
370-
PUT /logs_201305/_alias/2013
371-
--------------------------------------------------
372-
// CONSOLE
373-
// TEST[s/^/PUT logs_201305\n/]
374-
--
375-
376-
Adding a user alias::
377-
+
378-
--
379-
First create the index and add a mapping for the `user_id` field:
380-
381-
[source,js]
382-
--------------------------------------------------
383-
PUT /users
384-
{
385-
"mappings" : {
386-
"properties" : {
387-
"user_id" : {"type" : "integer"}
388-
}
389-
}
390-
}
391-
--------------------------------------------------
392-
// CONSOLE
393-
394-
Then add the alias for a specific user:
395-
396-
[source,js]
397-
--------------------------------------------------
398-
PUT /users/_alias/user_12
399-
{
400-
"routing" : "12",
401-
"filter" : {
402-
"term" : {
403-
"user_id" : 12
404-
}
405-
}
406-
}
407-
--------------------------------------------------
408-
// CONSOLE
409-
// TEST[continued]
410-
411-
--
412-
413-
[float]
414-
[[alias-index-creation]]
415-
==== Aliases during index creation
416-
417-
Aliases can also be specified during <<create-index-aliases,index creation>>:
418-
419-
[source,js]
420-
--------------------------------------------------
421-
PUT /logs_20162801
422-
{
423-
"mappings" : {
424-
"properties" : {
425-
"year" : {"type" : "integer"}
426-
}
427-
},
428-
"aliases" : {
429-
"current_day" : {},
430-
"2016" : {
431-
"filter" : {
432-
"term" : {"year" : 2016 }
433-
}
434-
}
435-
}
436-
}
437-
--------------------------------------------------
438-
// CONSOLE
439-
440-
[float]
441-
[[deleting]]
442-
==== Delete aliases
443-
444-
445-
The rest endpoint is: `/{index}/_alias/{name}`
446-
447-
where
448-
449-
[horizontal]
450-
`index`:: `* | _all | glob pattern | name1, name2, …`
451-
`name`:: `* | _all | glob pattern | name1, name2, …`
452-
453-
Alternatively you can use the plural `_aliases`. Example:
454-
455-
[source,js]
456-
--------------------------------------------------
457-
DELETE /logs_20162801/_alias/current_day
458-
--------------------------------------------------
459-
// CONSOLE
460-
// TEST[continued]

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

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -38,22 +38,19 @@ Wildcard expressions are not accepted.
3838
--
3939
end::expand-wildcards[]
4040

41-
tag::cat-h[]
42-
`h`::
43-
(Optional, string) Comma-separated list of column names to display.
44-
end::cat-h[]
45-
4641
tag::flat-settings[]
4742
`flat_settings`::
4843
(Optional, boolean) If `true`, returns settings in flat format. Defaults to
4944
`false`.
5045
end::flat-settings[]
5146

52-
tag::help[]
53-
`help`::
54-
(Optional, boolean) If `true`, the response returns help information. Defaults
55-
to `false`.
56-
end::help[]
47+
tag::index-alias-filter[]
48+
<<query-dsl-bool-query, Filter query>>
49+
used to limit the index alias.
50+
+
51+
If specified,
52+
the index alias only applies to documents returned by the filter.
53+
end::index-alias-filter[]
5754

5855
tag::http-format[]
5956
`format`::
@@ -62,6 +59,17 @@ https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html[HTTP accept header].
6259
Valid values include JSON, YAML, etc.
6360
end::http-format[]
6461

62+
tag::cat-h[]
63+
`h`::
64+
(Optional, string) Comma-separated list of column names to display.
65+
end::cat-h[]
66+
67+
tag::help[]
68+
`help`::
69+
(Optional, boolean) If `true`, the response returns help information. Defaults
70+
to `false`.
71+
end::help[]
72+
6573
tag::include-defaults[]
6674
`include_defaults`::
6775
(Optional, string) If `true`, return all default settings in the response.
@@ -153,6 +161,13 @@ tag::doc-routing[]
153161
(Optional, string) Target the specified primary shard.
154162
end::doc-routing[]
155163

164+
tag::index-routing[]
165+
`routing`::
166+
(Optional, string)
167+
Custom <<mapping-routing-field, routing value>>
168+
used to route operations to a specific shard.
169+
end::index-routing[]
170+
156171
tag::doc-version[]
157172
`version`::
158173
(Optional, integer) Explicit version number for concurrency control.

0 commit comments

Comments
 (0)