« Usage example Mapping »
Elastic Docs ›Elasticsearch Guide [8.16]

Aliases

edit

Aliases

edit

An alias is a secondary name for a group of data streams or indices. Most Elasticsearch 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 Elasticsearch requests, you can reindex data with no downtime or changes to your app’s code.

Alias types

edit

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.

Add an alias

edit

To add an existing data stream or index to an alias, use the aliases API's add action. If the alias doesn’t exist, the request creates it.

resp = client.indices.update_aliases(
    actions=[
        {
            "add": {
                "index": "logs-nginx.access-prod",
                "alias": "logs"
            }
        }
    ],
)
print(resp)
response = client.indices.update_aliases(
  body: {
    actions: [
      {
        add: {
          index: 'logs-nginx.access-prod',
          alias: 'logs'
        }
      }
    ]
  }
)
puts response
const response = await client.indices.updateAliases({
  actions: [
    {
      add: {
        index: "logs-nginx.access-prod",
        alias: "logs",
      },
    },
  ],
});
console.log(response);
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    }
  ]
}

The API’s index and indices parameters support wildcards (*). Wildcard patterns that match both data streams and indices return an error.

resp = client.indices.update_aliases(
    actions=[
        {
            "add": {
                "index": "logs-*",
                "alias": "logs"
            }
        }
    ],
)
print(resp)
const response = await client.indices.updateAliases({
  actions: [
    {
      add: {
        index: "logs-*",
        alias: "logs",
      },
    },
  ],
});
console.log(response);
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-*",
        "alias": "logs"
      }
    }
  ]
}

Remove an alias

edit

To remove an alias, use the aliases API’s remove action.

resp = client.indices.update_aliases(
    actions=[
        {
            "remove": {
                "index": "logs-nginx.access-prod",
                "alias": "logs"
            }
        }
    ],
)
print(resp)
response = client.indices.update_aliases(
  body: {
    actions: [
      {
        remove: {
          index: 'logs-nginx.access-prod',
          alias: 'logs'
        }
      }
    ]
  }
)
puts response
const response = await client.indices.updateAliases({
  actions: [
    {
      remove: {
        index: "logs-nginx.access-prod",
        alias: "logs",
      },
    },
  ],
});
console.log(response);
POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    }
  ]
}

Multiple actions

edit

You can use the aliases API to perform multiple actions in a single atomic operation.

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.

resp = client.indices.update_aliases(
    actions=[
        {
            "remove": {
                "index": "logs-nginx.access-prod",
                "alias": "logs"
            }
        },
        {
            "add": {
                "index": "logs-my_app-default",
                "alias": "logs"
            }
        }
    ],
)
print(resp)
response = client.indices.update_aliases(
  body: {
    actions: [
      {
        remove: {
          index: 'logs-nginx.access-prod',
          alias: 'logs'
        }
      },
      {
        add: {
          index: 'logs-my_app-default',
          alias: 'logs'
        }
      }
    ]
  }
)
puts response
const response = await client.indices.updateAliases({
  actions: [
    {
      remove: {
        index: "logs-nginx.access-prod",
        alias: "logs",
      },
    },
    {
      add: {
        index: "logs-my_app-default",
        alias: "logs",
      },
    },
  ],
});
console.log(response);
POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    },
    {
      "add": {
        "index": "logs-my_app-default",
        "alias": "logs"
      }
    }
  ]
}

Multiple action results

edit

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.

resp = client.indices.update_aliases(
    actions=[
        {
            "remove": {
                "index": "index1",
                "alias": "logs-non-existing"
            }
        },
        {
            "add": {
                "index": "index2",
                "alias": "logs-non-existing"
            }
        }
    ],
)
print(resp)
response = client.indices.update_aliases(
  body: {
    actions: [
      {
        remove: {
          index: 'index1',
          alias: 'logs-non-existing'
        }
      },
      {
        add: {
          index: 'index2',
          alias: 'logs-non-existing'
        }
      }
    ]
  }
)
puts response
const response = await client.indices.updateAliases({
  actions: [
    {
      remove: {
        index: "index1",
        alias: "logs-non-existing",
      },
    },
    {
      add: {
        index: "index2",
        alias: "logs-non-existing",
      },
    },
  ],
});
console.log(response);
POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "index1",
        "alias": "logs-non-existing"
      }
    },
    {
      "add": {
        "index": "index2",
        "alias": "logs-non-existing"
      }
    }
  ]
}

The API returns the following 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.

Add an alias at index creation

edit

You can also use a component or index template to add index or data stream aliases when they are created.

resp = client.cluster.put_component_template(
    name="my-aliases",
    template={
        "aliases": {
            "my-alias": {}
        }
    },
)
print(resp)

resp1 = client.indices.put_index_template(
    name="my-index-template",
    index_patterns=[
        "my-index-*"
    ],
    composed_of=[
        "my-aliases",
        "my-mappings",
        "my-settings"
    ],
    template={
        "aliases": {
            "yet-another-alias": {}
        }
    },
)
print(resp1)
response = client.cluster.put_component_template(
  name: 'my-aliases',
  body: {
    template: {
      aliases: {
        "my-alias": {}
      }
    }
  }
)
puts response

response = client.indices.put_index_template(
  name: 'my-index-template',
  body: {
    index_patterns: [
      'my-index-*'
    ],
    composed_of: [
      'my-aliases',
      'my-mappings',
      'my-settings'
    ],
    template: {
      aliases: {
        "yet-another-alias": {}
      }
    }
  }
)
puts response
const response = await client.cluster.putComponentTemplate({
  name: "my-aliases",
  template: {
    aliases: {
      "my-alias": {},
    },
  },
});
console.log(response);

const response1 = await client.indices.putIndexTemplate({
  name: "my-index-template",
  index_patterns: ["my-index-*"],
  composed_of: ["my-aliases", "my-mappings", "my-settings"],
  template: {
    aliases: {
      "yet-another-alias": {},
    },
  },
});
console.log(response1);
# 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": {}
    }
  }
}

You can also specify index aliases in create index API requests.

resp = client.indices.create(
    index="<my-index-{now/d}-000001>",
    aliases={
        "my-alias": {}
    },
)
print(resp)
response = client.indices.create(
  index: '<my-index-{now/d}-000001>',
  body: {
    aliases: {
      "my-alias": {}
    }
  }
)
puts response
const response = await client.indices.create({
  index: "<my-index-{now/d}-000001>",
  aliases: {
    "my-alias": {},
  },
});
console.log(response);
# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-alias": {}
  }
}

View aliases

edit

To get a list of your cluster’s aliases, use the get alias API with no argument.

resp = client.indices.get_alias()
print(resp)
response = client.indices.get_alias
puts response
const response = await client.indices.getAlias();
console.log(response);
GET _alias

Specify a data stream or index before _alias to view its aliases.

resp = client.indices.get_alias(
    index="my-data-stream",
)
print(resp)
response = client.indices.get_alias(
  index: 'my-data-stream'
)
puts response
const response = await client.indices.getAlias({
  index: "my-data-stream",
});
console.log(response);
GET my-data-stream/_alias

Specify an alias after _alias to view its data streams or indices.

resp = client.indices.get_alias(
    name="logs",
)
print(resp)
response = client.indices.get_alias(
  name: 'logs'
)
puts response
const response = await client.indices.getAlias({
  name: "logs",
});
console.log(response);
GET _alias/logs

Write index

edit

You can use is_write_index to specify a write index or data stream for an alias. Elasticsearch routes any write requests for the alias to this index or data stream.

resp = client.indices.update_aliases(
    actions=[
        {
            "add": {
                "index": "logs-nginx.access-prod",
                "alias": "logs"
            }
        },
        {
            "add": {
                "index": "logs-my_app-default",
                "alias": "logs",
                "is_write_index": True
            }
        }
    ],
)
print(resp)
response = client.indices.update_aliases(
  body: {
    actions: [
      {
        add: {
          index: 'logs-nginx.access-prod',
          alias: 'logs'
        }
      },
      {
        add: {
          index: 'logs-my_app-default',
          alias: 'logs',
          is_write_index: true
        }
      }
    ]
  }
)
puts response
const response = await client.indices.updateAliases({
  actions: [
    {
      add: {
        index: "logs-nginx.access-prod",
        alias: "logs",
      },
    },
    {
      add: {
        index: "logs-my_app-default",
        alias: "logs",
        is_write_index: true,
      },
    },
  ],
});
console.log(response);
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "logs-nginx.access-prod",
        "alias": "logs"
      }
    },
    {
      "add": {
        "index": "logs-my_app-default",
        "alias": "logs",
        "is_write_index": true
      }
    }
  ]
}

If an alias points to multiple indices or data streams and is_write_index isn’t set, the alias rejects write requests. If an index alias points to one index and is_write_index isn’t set, the index automatically acts as the write index. Data stream aliases don’t automatically set a write data stream, even if the alias points to one data stream.

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.

Filter an alias

edit

The filter option uses Query DSL to limit the documents an alias can access.

resp = client.indices.update_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"
                                }
                            }
                        ]
                    }
                }
            }
        }
    ],
)
print(resp)
response = client.indices.update_aliases(
  body: {
    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'
                  }
                }
              ]
            }
          }
        }
      }
    ]
  }
)
puts response
const response = await client.indices.updateAliases({
  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",
                },
              },
            ],
          },
        },
      },
    },
  ],
});
console.log(response);
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"
                }
              }
            ]
          }
        }
      }
    }
  ]
}

Filters are only applied when using the Query DSL, and are not applied when retrieving a document by ID.

Routing

edit

Use the routing option to route requests for an alias to a specific shard. This lets you take advantage of shard caches to speed up searches. Data stream aliases do not support routing options.

resp = client.indices.update_aliases(
    actions=[
        {
            "add": {
                "index": "my-index-2099.05.06-000001",
                "alias": "my-alias",
                "routing": "1"
            }
        }
    ],
)
print(resp)
response = client.indices.update_aliases(
  body: {
    actions: [
      {
        add: {
          index: 'my-index-2099.05.06-000001',
          alias: 'my-alias',
          routing: '1'
        }
      }
    ]
  }
)
puts response
const response = await client.indices.updateAliases({
  actions: [
    {
      add: {
        index: "my-index-2099.05.06-000001",
        alias: "my-alias",
        routing: "1",
      },
    },
  ],
});
console.log(response);
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "my-index-2099.05.06-000001",
        "alias": "my-alias",
        "routing": "1"
      }
    }
  ]
}

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.

resp = client.indices.update_aliases(
    actions=[
        {
            "add": {
                "index": "my-index-2099.05.06-000001",
                "alias": "my-alias",
                "search_routing": "1",
                "index_routing": "2"
            }
        }
    ],
)
print(resp)
response = client.indices.update_aliases(
  body: {
    actions: [
      {
        add: {
          index: 'my-index-2099.05.06-000001',
          alias: 'my-alias',
          search_routing: '1',
          index_routing: '2'
        }
      }
    ]
  }
)
puts response
const response = await client.indices.updateAliases({
  actions: [
    {
      add: {
        index: "my-index-2099.05.06-000001",
        alias: "my-alias",
        search_routing: "1",
        index_routing: "2",
      },
    },
  ],
});
console.log(response);
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "my-index-2099.05.06-000001",
        "alias": "my-alias",
        "search_routing": "1",
        "index_routing": "2"
      }
    }
  ]
}
« Usage example Mapping »