Aliases in Elasticsearch

Nobody is perfect and my name is not nobody. Elasticsearch mapping, as mappings of another storage engines, is rarely immutable. Because of that, index changes can provoke service downtime, according to size of reindexed data. But there are a trick to avoid this dead times.

Looking for a better data engineering position and skills?

You have been working as a data engineer but feel stuck? You don't have any new challenges and are still writing the same jobs all over again? You have now different options. You can try to look for a new job, now or later, or learn from the others! "Become a Better Data Engineer" initiative is one of these places where you can find online learning resources where the theory meets the practice. They will help you prepare maybe for the next job, or at least, improve your current skillset without looking for something else.

👉 I'm interested in improving my data engineering skillset

See you there, Bartosz

This article covers the subject of aliases which can be helpful to limit server downtime. The first part explains the idea of alias. It also lists main use cases. The next part shows how to make aliases.

What aliases are ?

To understand the utility of aliases, we need first to understand how indexed documents are stored by Elasticsearch. Indices are immutable, so they never change. If we want to update one document, a new one is created in its place and the old one is marked as deleted. Documents are stored in segments. Each segment can contain documents of any type. It means that the changing of mapping in one type will need the reindexing of all documents. Reindexing is only necessary when fields definition changes or elements influencing indexation (as analyzers) change. If new fields are added, reindexing is not mandatory.

Reindexing is pretty trivial task. We only need to create new index and copy documents from old index, for example with bulk API. Next step is consist on calling this new index in consumer application. But it requires a lot of actions which can take some time. To avoid this kind of problems, aliases were created.

Alias can be though in term of symlink links in Elasticsearch. So alias is a supplementary layer between user and documents, so far presented as (from the bottom level): shard - index - user. This new layer is placed between index and user. In reality when user calls alias, it calls an index. And it's very useful in the case of reindexing because after this process we can simply switch alias to newly created index, without interrupting the service. Use cases of aliases can be resumed to:

Elasticsearch guide advises itself to use aliases instead of indices because they are cheap and help to avoid some problems, as the one presented with documents reindexing.

Aliases example

To set up an alias, we need to call _alias endpoint of aliased index. So, if we created index called "january", and we want to alias it with the name "month", we should send a PUT request on: /january/_alias/month. Aliases can be managed through _aliases endpoint which body is based on words representing actions to do on edited alias:

{"actions": [
  {"remove": {"alias": "alias_1", "index": "index_1"}}, 
  {"add": {"alias": "alias_2", "index": "index_2"}}

In the case of our sample project, we create an alias on index called waitingforcode by sending this request http://localhost:9200/waitingforcode/_alias/french_football. The response should be:

{"acknowledged": true}

To confirm that this acknowledgment was correctly send, we can also send a GET request on http://localhost:9200/waitingforcode/_alias/*. It should list all aliases related to index waitingforcode:


In Java API, there are no differences between aliases and indices. Method used to generate request for given type stored in the index doesn't change. prepareSearch(String..indices) method supports as well index name as alias name:

private SearchRequestBuilder buildSearchRequestForType(String type) {
  return elasticSearchClient.prepareSearch(ElasticSearchConfig.ALIAS).setTypes(type);

This short article presents very important concept from the maintainability point of view - aliases. Thanks to them we can refactor our mapping without any downtime. They are also useful in the situations when we need to group logically related indexes together. And we also saw that adding or modifying alias is the question of one simple HTTP request. We also discovered that the use of aliases is transparent for Java API code.

If you liked it, you should read:

📚 Newsletter Get new posts, recommended reading and other exclusive information every week. SPAM free - no 3rd party ads, only the information about waitingforcode!