Create an index alias in Azure AI Search

Important

Index aliases are currently in public preview and available under supplemental terms of use.

An index alias in Azure AI Search is an alternate name for an index. You can use the alias instead of the index name in your application, which minimizes future updates to production code. If you need to switch to a newer index, you can update the alias mapping.

Before using an alias, your application sends requests directly to hotel-samples-index.

POST /indexes/hotel-samples-index/docs/search?api-version=2025-05-01-preview
{
    "search": "pool spa +airport",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

After using an alias, your application sends requests to my-alias, which maps to hotel-samples-index.

POST /indexes/my-alias/docs/search?api-version=2025-05-01-preview
{
    "search": "pool spa +airport",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Supported scenarios

You can only use an alias with document operations or to get and update an index definition.

Aliases can't be used to delete an index, or test text tokenization, or referenced as the targetIndexName on an indexer.

Create an index alias

You can create an alias using the preview REST API, the preview SDKs, or through the Azure portal. An alias consists of the name of the alias and the name of the search index that the alias is mapped to. Only one index name can be specified in the indexes array.

REST API

You can use the Create or Update Alias (REST preview) to create an index alias.

POST /aliases?api-version=2025-05-01-preview
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index"]
}

Azure portal

Follow the steps below to create an index alias in the Azure portal.

1. Navigate to your search service in the Azure portal.
2. Find and select Aliases.
3. Select + Add Alias.
4. Give your index alias a name and select the search index you want to map the alias to. Then, select Save.

.NET SDK

Using one of the beta packages from the Azure SDK for .NET, you can use the following syntax to create an index alias.

// Create a SearchIndexClient
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, credential);

// Create an index alias
SearchAlias myAlias = new SearchAlias("my-alias", "hotel-quickstart-index");
adminClient.CreateAlias(myAlias);

Index aliases are also supported in the latest preview SDKs for Java, Python, and JavaScript.

Send requests to an index alias

Aliases can be used for all document operations including querying, indexing, suggestions, and autocomplete.

This query sends the request to my-alias, which is mapped to an actual index on your search service.

POST /indexes/my-alias/docs/search?api-version=2025-05-01-preview
{
    "search": "pool spa +airport",
    "searchMode": any,
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Update an alias

PUT is required for alias updates as described in Create or Update Alias (REST preview).

PUT /aliases/my-alias?api-version=2025-05-01-preview
{
    "name": "my-alias",
    "indexes": ["hotel-samples-index2"]
}

An update to an alias may take up to 10 seconds to propagate through the system so you should wait at least 10 seconds before deleting the index that the alias was previously mapped to.

See also

• Drop and rebuild an index in Azure AI Search