Skip to main content
Creating and managing aliases requires API version 2026-07 or later and is available through the REST API. Reading through an alias works on any API version, including the current SDKs.
The primary use case for a namespace alias is swapping the data an application reads without a redeploy: re-ingest into a new namespace, validate it, then flip live reads to it in one call. This guide refreshes the data behind an alias named example-alias, moving it from example-namespace-v1 to example-namespace-v2 with no downtime. The examples use the vector API; the same alias substitution works on any read endpoint.

​
Before you begin

Ensure you have the following:
  • An existing index containing the namespace serving live traffic.
  • A project role that can manage namespaces, such as DataPlaneEditor, ProjectOwner, or ProjectManager. Managing aliases needs the same access as managing namespaces directly.

​
Swap the namespace

1

Create an alias

Create an alias pointing at the namespace serving live traffic. Specify a name for the alias and the target_namespace it points at.
curl
The response returns the alias:
curl
2

Read through the alias

Point your application’s reads at the alias name. Pass it wherever you’d pass a namespace name; here, that’s the namespace field in a query request.
curl
The response’s namespace field reports the namespace that served the read. You sent example-alias, and the read came back from example-namespace-v1, so you can verify what the alias points at from the read itself.
3

Ingest the new data

Ingest the refreshed data into a new namespace. Writes never use the alias, so live read traffic keeps landing on example-namespace-v1 while you build example-namespace-v2.
curl
Validate example-namespace-v2 by reading it directly by its own name.
4

Cut over in one call

Repoint the alias to the new namespace. The repoint is atomic (all or nothing, no partial state), and when the call returns success, all reads resolve to the new target.
A paginated read (a list, or a filtered fetch) that’s already in progress when you repoint finishes its remaining pages against the new target.
curl
5

Verify the cutover

Describe the alias to confirm the current target and the last repoint time:
curl
The target_namespace now reads example-namespace-v2, and updated_at has advanced to the repoint time:
curl
6

Retire the old namespace

When you’re ready, delete the old example-namespace-v1 namespace. The delete succeeds now that no alias targets it. Before the repoint, the delete would have been rejected because the alias still pointed at it.

​
See also