Share via

Update Index (Azure AI Search REST API)

  • Article

Important

This API reference is for a legacy version. See Data plane REST operations for updated reference documentation. Use the filter on the top left to select a version.

Modifying an existing index typically requires an index drop and rebuild, except for the following schema changes:

  • Add new fields to a fields collection

  • Add newly created fields to a suggester

  • Add or change scoring profiles

  • Add or change encryption keys

  • Add new custom analyzers

  • Change CORS options

  • Change existing fields with any of these three modifications:

    • Change retrievable (values are true or false)
    • Change searchAnalyzer (used at query time)
    • Add or change synonymMaps (used at query time)

To add these updates, put the index name on the request URI. In the request body, include a fully specified index definition with your modifications.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]

Existing fields and most field attributes can't be deleted or changed, nor can fields be added to suggesters. Only newly created fields can be added to a suggester.

When a new field is added, all existing documents automatically get a null value for that field. No other storage space is consumed until one of two things occurs: a value is provided for the new field (using merge), or new documents are added.

Existing analyzers, tokenizers, token filters, and char filters are unable to be altered. Adding new ones to an already existing index is only possible when the allowIndexDowntime flag is turned on in the index update request. The same rule applies when adding an initial vector field to a pre-existing index that was established using an API which didn't support vector search, specifically before the REST API version 2023-07-01 Preview.

PUT https://[search service name].search.windows.net/indexes/[index name]?api-version=[api-version]&allowIndexDowntime=true

This operation takes your index offline for a few seconds. Indexing and query requests fail while the index is offline. Performance and write operations can be temporarily impaired for several minutes after the index is back online.

URI Parameters

Parameter Description
service name Required. Set this to the unique, user-defined name of your search service.
index name Required. The request URI specifies the name of the index to update.
api-version Required. See API versions for a list of supported versions.
allowIndexDowntime Optional. False by default. Set to true for certain updates, such as adding or modifying an analyzer, tokenizer, token filter, char filter, or similarity property. The index is taken offline during the update, usually no more than several seconds.

Request Headers

The following table describes the required and optional request headers.

Fields Description
Content-Type Required. Set this to application/json
api-key Optional if you're using Azure roles and a bearer token is provided on the request, otherwise a key is required. Update requests must include an api-key header set to your admin key (as opposed to a query key). See Connect to Azure AI Search using key authentication for details.

Request Body

The request body syntax is the same as for Create Index.

When you update an existing index, the body must include the full schema definition, including any original definitions that you want to preserve. In general, the best pattern for updates is to retrieve the index definition with a GET, modify it, and then update it with PUT.

Response

For a successful request, you should see "204 No Content".

By default the response body is empty. However, if the Prefer request header is set to return=representation, the response body contains the JSON of the updated index. In this case, the success status code is "200 OK".

See also