There is no rename API in Elasticsearch. The closest thing is an alias, which lets you give an existing index a second name without moving any data. For most "rename" use cases that is the right answer. If you genuinely need a different underlying index name (for example, because tooling pins on a specific naming pattern), the canonical patterns are alias swap, clone plus delete, or reindex plus delete. All three work on Elasticsearch 7.x, 8.x, and 9.x.
This guide covers each pattern, when to use it, and the operational gotchas.
Option 1: Just Use an Alias (Recommended)
In 90% of cases, an alias is what "rename" actually means. Add the new name as an alias on the existing index:
POST /_aliases
{
"actions": [
{ "add": { "index": "old-name", "alias": "new-name" } }
]
}
Applications can now refer to either name; queries against new-name are transparently routed to old-name. The underlying index keeps its original name on disk. If you cannot live with the old name on disk, you have to actually move the data, which is what the next two patterns do.
When the alias-only approach is the right answer:
- Applications query by name; you just need a different name for them to use.
- You can update application code to point at the new name (the alias).
- You do not care what the underlying index is called.
For the full alias playbook, see the aliases guide.
Option 2: Clone the Index Under the New Name
If you need the underlying index to actually have the new name (because of dashboards, snapshot policies, or tooling that hard-codes naming), the fast path is clone:
# 1. Make the source index read-only.
PUT /old-name/_settings
{ "settings": { "index.blocks.write": true } }
# 2. Clone into the new name.
POST /old-name/_clone/new-name
# 3. (Optional) Carry over aliases.
POST /_aliases
{
"actions": [
{ "add": { "index": "new-name", "alias": "my-app" } },
{ "remove": { "index": "old-name", "alias": "my-app" } }
]
}
# 4. Drop the read-only block on the new index (clone copies it across).
PUT /new-name/_settings
{ "settings": { "index.blocks.write": null } }
# 5. Verify, then delete the old index.
DELETE /old-name
Why clone over reindex:
- Clone hard-links segment files rather than re-indexing documents. It is orders of magnitude faster on large indices.
- The mapping, settings, and document IDs are identical to the source.
Constraints of clone:
- Same cluster only. You cannot clone across clusters.
- Source must be read-only during the clone.
- All shards of the source must reside on the same node, or the clone will refuse to start. Move shards if necessary with shard allocation filtering.
For the full clone playbook, see the clone index guide.
Option 3: Reindex Under the New Name
If you also want to change settings or mappings during the rename (different shard count, new field types, recombined index), reindex into the new name:
# 1. Create the new index with the desired settings/mappings.
PUT /new-name
{
"settings": { /* ... */ },
"mappings": { /* ... */ }
}
# 2. Reindex.
POST /_reindex
{
"source": { "index": "old-name" },
"dest": { "index": "new-name" }
}
# 3. Swap any aliases over.
POST /_aliases
{
"actions": [
{ "add": { "index": "new-name", "alias": "my-app" } },
{ "remove": { "index": "old-name", "alias": "my-app" } }
]
}
# 4. Delete the old index after verification.
DELETE /old-name
Reindex is slower than clone (it actually processes every document), but it is the only option when you need to change the underlying shape of the data. See the reindex guide for throttling, error handling, and remote-source patterns.
Handling Live Writes During Rename
For any of the three options, the writers need to stop pointing at the old index by the end of the operation. Two patterns:
- Maintenance window. Stop writers, perform the operation, switch writers to the new name (or the alias), resume.
- Zero downtime with aliases. Have writers already pointing at an alias. Atomically swap which underlying index the alias points at as the last step of the rename.
The zero-downtime pattern requires that you set up aliases before you ever need to rename. It is the single best reason to point every production application at an alias from day one.
Common Pitfalls
- Forgetting to copy aliases. Clone copies settings and mappings but not all aliases automatically in every version. Re-add the aliases explicitly after clone.
- Skipping the read-only step on clone. Without
index.blocks.write: trueon the source, the clone API rejects the request. - Deleting the old index before the new one is fully ready. Wait for the cluster to be green and document counts to match before deleting.
- Treating reindex as a rename. Reindex is the right tool when you need to change mappings or settings. If the names are the only thing changing, clone is faster.
How Pulse Helps With Index Migrations
Renaming an index sounds like a five-minute job until you discover the third dashboard, the fourth alert, and the saved query that still reference the old name. Pulse inventories aliases, dashboards, and active query patterns on Elasticsearch and OpenSearch clusters so that before you rename, you know everything that touches the old name. After the rename, Pulse flags traffic still hitting the old name and indices that should have been cleaned up. Connect your cluster to Pulse and run rename and migration operations with confidence about what you are actually breaking.
Frequently Asked Questions
Q: Why does Elasticsearch not have a rename API?
Indices are made up of shards on data nodes, with metadata in the cluster state. A rename would need to atomically update cluster state, file paths on every node, and any aliases or snapshots that reference the index. The clone-and-delete pattern achieves the same outcome with explicit, observable steps and zero new API surface area.
Q: What is the fastest way to rename a 1 TB index?
Clone. It hard-links segments on disk and finishes in seconds rather than the hours a reindex would take. The catch: clone requires that all shards of the source reside on the same node, which on a 1 TB index across many nodes can require shard allocation moves first.
Q: Can I rename an index without any downtime?
Yes, if the application already points at an alias. Clone or reindex into the new name, then atomically swap the alias to point at the new index. The application never notices.
Q: Does renaming a data stream work the same way?
No. Data streams have their own naming semantics, and you generally do not rename them. To get a data stream with a different name, create the new stream and either dual-write during a cutover or reindex into it.
Q: What about renaming through the snapshot/restore API?
You can restore a snapshot with rename_pattern and rename_replacement, which gives you the renamed index without touching the source. Useful for forensic copies or pre-production restores under a different name. For an in-place rename of a live index, clone is faster.
Q: Will the new index keep the same document IDs?
Clone preserves document IDs exactly. Reindex preserves them by default but can transform them via a script if you need to.
