---
title: "Rebuild an index under a new name and · Agent Wranglers"
url: https://agentwranglers.se/playbook/search/index-contents-and-sync/reindex-with-alias
id: SRH-9
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 851
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Rebuild an index under a new name and switch an alias

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Index contents and sync](https://agentwranglers.se/playbook/search/index-contents-and-sync.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: SRH-9
- Level: Recommended
- Chapter: [Index contents and sync](https://agentwranglers.se/playbook/search/index-contents-and-sync.md)
- Rule: Point the app at an alias, never at an index by name. Build each new version of the index beside the old one, compare them, then move the alias in one step.
- Check: During a full rebuild on staging, a script searches every second. No search fails or returns an empty page. The app's settings name the alias, and a code search finds no versioned index name outside the rebuild job.
- How: Changing a mapping, an analyser or the embedding model means building the index again. Rebuilding in place leaves search empty or half full for the duration. Build `products_v8` while `products_v7` serves, and replay the updates that arrived meanwhile from the queue. Run the [fixed query set](https://agentwranglers.se/playbook/search/relevance/search-quality-tests.md) against the new index, and switch only when it passes. Elasticsearch and OpenSearch move an alias in one atomic call. In PostgreSQL, build the new column and index, then swap them in one transaction. Keep the old index for a day, so a switch back is one call.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### HTTP example

```http
POST /_aliases
Content-Type: application/json

{ "actions": [
  { "remove": { "index": "products_v7", "alias": "products" } },
  { "add": { "index": "products_v8", "alias": "products" } }
] }
```

### Python example

```python
def switch_alias(client, alias: str, old_index: str, new_index: str) -> None:
    client.indices.update_aliases(body={"actions": [
        {"remove": {"index": old_index, "alias": alias}},
        {"add": {"index": new_index, "alias": alias}},
    ]})
```

### JavaScript example

```js
export async function switchAlias(client, alias, oldIndex, newIndex) {
  await client.indices.updateAliases({ body: { actions: [
    { remove: { index: oldIndex, alias } },
    { add: { index: newIndex, alias } },
  ] } });
}
```

## Sources

- [OpenSearch index aliases](https://docs.opensearch.org/latest/im-plugin/index-alias/)

## Related rules

- SRH-17 [Test search results with a fixed query set](https://agentwranglers.se/playbook/search/relevance/search-quality-tests.md) in Search

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/search/index-contents-and-sync/reindex-with-alias">Agent Wranglers search playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Remove erased records from every index](https://agentwranglers.se/playbook/search/index-contents-and-sync/erase-from-indexes.md)
- [Index contents and sync](https://agentwranglers.se/playbook/search/index-contents-and-sync.md)