mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
409 lines
8.9 KiB
Text
409 lines
8.9 KiB
Text
[chapter]
|
|
[[aliases]]
|
|
= Aliases
|
|
|
|
An alias is a secondary name for a group of data streams or indices. Most {es}
|
|
APIs accept an alias in place of a data stream or index name.
|
|
|
|
You can change the data streams or indices of an alias at any time. If you use
|
|
aliases in your application's {es} requests, you can reindex data with no
|
|
downtime or changes to your app's code.
|
|
|
|
[discrete]
|
|
[[alias-types]]
|
|
=== Alias types
|
|
|
|
There are two types of aliases:
|
|
|
|
* A **data stream alias** points to one or more data streams.
|
|
* An **index alias** points to one or more indices.
|
|
|
|
An alias cannot point to both data streams and indices. You also cannot add a
|
|
data stream's backing index to an index alias.
|
|
|
|
[discrete]
|
|
[[add-alias]]
|
|
=== Add an alias
|
|
|
|
To add an existing data stream or index to an alias, use the
|
|
<<indices-aliases,aliases API>>'s `add` action. If the alias doesn't exist, the
|
|
request creates it.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"add": {
|
|
"index": "logs-nginx.access-prod",
|
|
"alias": "logs"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\n/]
|
|
|
|
The API's `index` and `indices` parameters support wildcards (`*`). Wildcard
|
|
patterns that match both data streams and indices return an error.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"add": {
|
|
"index": "logs-*",
|
|
"alias": "logs"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\n/]
|
|
|
|
[discrete]
|
|
[[remove-alias]]
|
|
=== Remove an alias
|
|
|
|
To remove an alias, use the aliases API's `remove` action.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"remove": {
|
|
"index": "logs-nginx.access-prod",
|
|
"alias": "logs"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
[discrete]
|
|
[[multiple-actions]]
|
|
=== Multiple actions
|
|
|
|
You can use the aliases API to perform multiple actions in a single atomic
|
|
operation.
|
|
|
|
// tag::alias-multiple-actions-example[]
|
|
For example, the `logs` alias points to a single data stream. The following
|
|
request swaps the stream for the alias. During this swap, the `logs` alias has
|
|
no downtime and never points to both streams at the same time.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"remove": {
|
|
"index": "logs-nginx.access-prod",
|
|
"alias": "logs"
|
|
}
|
|
},
|
|
{
|
|
"add": {
|
|
"index": "logs-my_app-default",
|
|
"alias": "logs"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT _data_stream\/logs-my_app-default\n/]
|
|
// end::alias-multiple-actions-example[]
|
|
|
|
[discrete]
|
|
[[multiple-action-results]]
|
|
=== Multiple action results
|
|
|
|
When using multiple actions, if some succeed and some fail, a list of per-action results will be returned.
|
|
|
|
Consider a similar action list to the previous example, but now with an alias `log-non-existing`, which does not yet exist.
|
|
In this case, the `remove` action will fail, but the `add` action will succeed.
|
|
The response will contain the list `action_results`, with a result for every requested action.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"remove": {
|
|
"index": "index1",
|
|
"alias": "logs-non-existing"
|
|
}
|
|
},
|
|
{
|
|
"add": {
|
|
"index": "index2",
|
|
"alias": "logs-non-existing"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[s/^/PUT \/index1\nPUT \/index2\n/]
|
|
|
|
The API returns the following result:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"acknowledged": true,
|
|
"errors": true,
|
|
"action_results": [
|
|
{
|
|
"action": {
|
|
"type": "remove",
|
|
"indices": [ "index1" ],
|
|
"aliases": [ "logs-non-existing" ],
|
|
},
|
|
"status": 404,
|
|
"error": {
|
|
"type": "aliases_not_found_exception",
|
|
"reason": "aliases [logs-non-existing] missing",
|
|
"resource.type": "aliases",
|
|
"resource.id": "logs-non-existing"
|
|
}
|
|
},
|
|
{
|
|
"action": {
|
|
"type": "add",
|
|
"indices": [ "index2" ],
|
|
"aliases": [ "logs-non-existing" ],
|
|
},
|
|
"status": 200
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
Allowing the action list to succeed partially may not provide the desired result.
|
|
It may be more appropriate to set `must_exist` to `true`, which will cause the entire action
|
|
list to fail if a single action fails.
|
|
|
|
|
|
[discrete]
|
|
[[add-alias-at-creation]]
|
|
=== Add an alias at index creation
|
|
|
|
You can also use a <<indices-component-template,component>> or
|
|
<<indices-put-template,index template>> to add index or data stream aliases
|
|
when they are created.
|
|
|
|
[source,console]
|
|
----
|
|
# Component template with index aliases
|
|
PUT _component_template/my-aliases
|
|
{
|
|
"template": {
|
|
"aliases": {
|
|
"my-alias": {}
|
|
}
|
|
}
|
|
}
|
|
|
|
# Index template with index aliases
|
|
PUT _index_template/my-index-template
|
|
{
|
|
"index_patterns": [
|
|
"my-index-*"
|
|
],
|
|
"composed_of": [
|
|
"my-aliases",
|
|
"my-mappings",
|
|
"my-settings"
|
|
],
|
|
"template": {
|
|
"aliases": {
|
|
"yet-another-alias": {}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[s/,\n "my-mappings",\n "my-settings"//]
|
|
// TEST[teardown:data_stream_cleanup]
|
|
|
|
You can also specify index aliases in <<indices-create-index,create index API>>
|
|
requests.
|
|
|
|
[source,console]
|
|
----
|
|
# PUT <my-index-{now/d}-000001>
|
|
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
|
|
{
|
|
"aliases": {
|
|
"my-alias": {}
|
|
}
|
|
}
|
|
----
|
|
|
|
[discrete]
|
|
[[view-aliases]]
|
|
=== View aliases
|
|
|
|
To get a list of your cluster's aliases, use the <<indices-get-alias,get alias
|
|
API>> with no argument.
|
|
|
|
[source,console]
|
|
----
|
|
GET _alias
|
|
----
|
|
// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT logs-nginx.access-prod\/_alias\/logs\n/]
|
|
|
|
Specify a data stream or index before `_alias` to view its aliases.
|
|
|
|
[source,console]
|
|
----
|
|
GET my-data-stream/_alias
|
|
----
|
|
// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT logs-nginx.access-prod\/_alias\/logs\n/]
|
|
// TEST[s/my-data-stream/logs-nginx.access-prod/]
|
|
|
|
Specify an alias after `_alias` to view its data streams or indices.
|
|
|
|
[source,console]
|
|
----
|
|
GET _alias/logs
|
|
----
|
|
// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT logs-nginx.access-prod\/_alias\/logs\n/]
|
|
|
|
[discrete]
|
|
[[write-index]]
|
|
=== Write index
|
|
|
|
You can use `is_write_index` to specify a write index or data stream for an
|
|
alias. {es} routes any write requests for the alias to this index or data
|
|
stream.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"add": {
|
|
"index": "logs-nginx.access-prod",
|
|
"alias": "logs"
|
|
}
|
|
},
|
|
{
|
|
"add": {
|
|
"index": "logs-my_app-default",
|
|
"alias": "logs",
|
|
"is_write_index": true
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[s/^/PUT _data_stream\/logs-nginx.access-prod\nPUT _data_stream\/logs-my_app-default\n/]
|
|
|
|
include::{es-ref-dir}/indices/aliases.asciidoc[tag=write-index-defaults]
|
|
|
|
TIP: We recommend using data streams to store append-only time series data. If
|
|
you need to update or delete existing time series data, you can perform update or delete operations
|
|
directly on the data stream backing index. If you frequently send multiple documents using the same
|
|
`_id` expecting last-write-wins, you may want to use an index alias with a write index instead. See
|
|
<<manage-time-series-data-without-data-streams>>.
|
|
|
|
[discrete]
|
|
[[filter-alias]]
|
|
=== Filter an alias
|
|
|
|
The `filter` option uses <<query-dsl,Query DSL>> to limit the documents an alias
|
|
can access.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"add": {
|
|
"index": "my-index-2099.05.06-000001",
|
|
"alias": "my-alias",
|
|
"filter": {
|
|
"bool": {
|
|
"filter": [
|
|
{
|
|
"range": {
|
|
"@timestamp": {
|
|
"gte": "now-1d/d",
|
|
"lt": "now/d"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"term": {
|
|
"user.id": "kimchy"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[s/^/PUT my-index-2099.05.06-000001\n/]
|
|
|
|
NOTE: Filters are only applied when using the <<query-dsl,Query DSL>>, and are not applied when <<docs-get,retrieving a document by ID>>.
|
|
|
|
[discrete]
|
|
[[alias-routing]]
|
|
=== Routing
|
|
|
|
Use the `routing` option to <<mapping-routing-field,route>> requests for an
|
|
alias to a specific shard. This lets you take advantage of
|
|
<<shard-request-cache,shard caches>> to speed up searches. Data stream aliases
|
|
do not support routing options.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"add": {
|
|
"index": "my-index-2099.05.06-000001",
|
|
"alias": "my-alias",
|
|
"routing": "1"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[s/^/PUT my-index-2099.05.06-000001\n/]
|
|
|
|
Use `index_routing` and `search_routing` to specify different routing values for
|
|
indexing and search. If specified, these options overwrite the `routing` value
|
|
for their respective operations.
|
|
|
|
[source,console]
|
|
----
|
|
POST _aliases
|
|
{
|
|
"actions": [
|
|
{
|
|
"add": {
|
|
"index": "my-index-2099.05.06-000001",
|
|
"alias": "my-alias",
|
|
"search_routing": "1",
|
|
"index_routing": "2"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TEST[s/^/PUT my-index-2099.05.06-000001\n/]
|