Редактиране

Споделяне чрез

Create an index alias in Azure AI Search

  • Статия

Important

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

In Azure AI Search, an index alias is a secondary name that can be used to refer to an index for querying, indexing, and other operations. You can create an alias that maps to a search index and substitute the alias name in places where you would otherwise reference an index name. An alias adds flexibility if you need to change which index your application is pointing to. Instead of updating the references in your application, you can just update the mapping for your alias.

The main goal of index aliases is to make it easier to manage your production indexes. For example, if you need to make a change to your index definition, such as editing a field or adding a new analyzer, you'll have to create a new search index because all search indexes are immutable. This means you either need to drop and rebuild your index or create a new index and then migrate your application over to that index.

Instead of dropping and rebuilding your index, you can use index aliases. A typical workflow would be to:

  1. Create your search index
  2. Create an alias that maps to your search index
  3. Have your application send querying/indexing requests to the alias rather than the index name
  4. When you need to make a change to your index that requires a rebuild, create a new search index
  5. When your new index is ready to go, update the alias to map to the new index and requests will automatically be routed to the new index

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.

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

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

Send requests to an index alias

Once you've created your alias, you're ready to start using it. Aliases can be used for all document operations including querying, indexing, suggestions, and autocomplete.

In the query below, instead of sending the request to hotel-samples-index, you can instead send the request to my-alias and it will be routed accordingly.

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

If you expect to make updates to a production index, specify an alias rather than the index name in your client-side application. Scenarios that require an index rebuild are outlined in Drop and rebuild an index.

Note

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, can't be used with the Analyze Text API, and can't be used as the targetIndexName on an indexer.

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 performing any operation in the index that has been mapped or recently was mapped to the alias.

Swap indexes

Now, whenever you need to update your application to point to a new index, all you need to do is update the mapping in your alias. PUT is required for updates as described in Create or Update Alias (REST preview).

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

After you make the update to the alias, requests will automatically start to be routed to the new index.

Note

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