|
| 1 | +--- |
| 2 | +title: Create an index alias |
| 3 | +titleSuffix: Azure Cognitive Search |
| 4 | +description: Create an alias to define a secondary name that can be used to refer to an index for querying, indexing, and other operations. |
| 5 | + |
| 6 | +author: dereklegenzoff |
| 7 | +ms.author: delegenz |
| 8 | +ms.service: cognitive-search |
| 9 | +ms.topic: how-to |
| 10 | +ms.date: 03/01/2022 |
| 11 | +--- |
| 12 | + |
| 13 | +# Create an index alias in Azure Cognitive Search |
| 14 | + |
| 15 | +> [!IMPORTANT] |
| 16 | +> Index aliases are currently in public preview and available under [supplemental terms of use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). |
| 17 | +
|
| 18 | +In Azure Cognitive Search, an 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. This gives you added flexibility if you ever need to change which index your application is pointing to. Instead of updating the references to the index name in your application, you can just update the mapping for your alias. |
| 19 | + |
| 20 | +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](search-howto-reindex.md) or create a new index and then migrate your application over to that index. |
| 21 | + |
| 22 | +Instead of dropping and rebuilding your index, you can use index aliases. A typical workflow would be to: |
| 23 | + |
| 24 | +1. Create your search index |
| 25 | +1. Create an alias that maps to your search index |
| 26 | +1. Have your application send querying/indexing requests to the alias rather than the index name |
| 27 | +1. When you need to make a change to your index that requires a rebuild, create a new search index |
| 28 | +1. 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 |
| 29 | + |
| 30 | +## Create an alias |
| 31 | + |
| 32 | +You can create an alias using the preview REST API, the preview SDKs, or through [Visual Studio Code](search-get-started-vs-code.md). 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. |
| 33 | + |
| 34 | +### [**REST API**](#tab/rest) |
| 35 | + |
| 36 | +You can use the [Create or Update Alias (REST preview)](/rest/api/searchservice/preview-api/create-or-update-alias) to create an index alias. |
| 37 | + |
| 38 | +```http |
| 39 | +POST /aliases?api-version=2021-04-30-preview |
| 40 | +{ |
| 41 | + "name": "my-alias", |
| 42 | + "indexes": ["hotel-samples-index"] |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +### [**Visual Studio Code**](#tab/vscode) |
| 47 | + |
| 48 | +To create an alias in Visual Studio Code: |
| 49 | +1. Follow the steps in the [Visual Studio Code Quickstart](search-get-started-vs-code.md) to install the [Azure Cognitive Search extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurecognitivesearch) and connect to your Azure Subscription. |
| 50 | +1. Navigate to your search service. |
| 51 | +1. Under your search service, right-click on **Aliases** and select **Create new alias**. |
| 52 | +1. Provide the name of your alias and the name of the search index you'd like to map it to and then save the file to create the alias. |
| 53 | + |
| 54 | +  |
| 55 | + |
| 56 | +--- |
| 57 | + |
| 58 | + |
| 59 | +## Send requests |
| 60 | + |
| 61 | +Once you've created your alias, you're ready to start using it. Aliases can be used for all [document operations](/rest/api/searchservice/document-operations) including querying, indexing, suggestions, and autocomplete. |
| 62 | + |
| 63 | +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. |
| 64 | + |
| 65 | +```http |
| 66 | +POST /indexes/my-alias/docs/search?api-version=2021-04-30-preview |
| 67 | +{ |
| 68 | + "search": "pool spa +airport", |
| 69 | + "searchMode": any, |
| 70 | + "queryType": "simple", |
| 71 | + "select": "HotelId, HotelName, Category, Description", |
| 72 | + "count": true |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +If you expect that you may need to make updates to your index definition for your production indexes, you should use an alias rather than the index name for requests in your client-side application. Scenarios that require you to create a new index are outlined under these [rebuild conditions](search-howto-reindex.md#rebuild-conditions). |
| 77 | + |
| 78 | +> [!NOTE] |
| 79 | +> You can only use an alias with [document operations](/rest/api/searchservice/document-operations). Aliases can't be used to get or update an index definition, can't be used with the Analyze Text API, and can't be used as the `targetIndexName` on an indexer. |
| 80 | +
|
| 81 | +## Swap indexes |
| 82 | + |
| 83 | +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)](/rest/api/searchservice/preview-api/create-or-update-alias). |
| 84 | + |
| 85 | +```http |
| 86 | +PUT /aliases/my-alias?api-version=2021-04-30-preview |
| 87 | +{ |
| 88 | + "name": "my-alias", |
| 89 | + "indexes": ["hotel-samples-index2"] |
| 90 | +} |
| 91 | +``` |
| 92 | +After you make the update to the alias, requests will automatically start to be routed to the new index. |
| 93 | + |
| 94 | +> [!NOTE] |
| 95 | +> An update to an alias may take up to 10 seconds to propogate through the system so you should wait at least 10 seconds before deleting the index that the alias was previously mapped to. |
| 96 | +
|
| 97 | +## See also |
| 98 | + |
| 99 | ++ [Drop and rebuild an index in Azure Cognitive Search](search-howto-reindex.md) |
0 commit comments