Upgrade to the latest REST API in Azure AI Search
Use this article to migrate data plane calls to newer versions of the Search REST API.
2023-11-01 is the most recent stable version. Semantic ranking and support for vector indexing and queries are generally available in this version.
2023-10-01-preview is the most recent preview version. Preview features include built-in query vectorization, built-in data chunking and vectorization during indexing (uses the Text Split skill and Azure OpenAI Embedding skill).
2023-07-01-preview was the first REST API for vector support. It's now deprecated and you should migrate to either 2023-11-01 or 2023-10-01-preview immediately.
Note
REST API reference docs are now versioned. To get the right content, open a reference page and then filter by version, using the selector located above the table of contents.
When to upgrade
Azure AI Search breaks backward compatibility as a last resort. Upgrade is necessary when:
Your code references a retired or deprecated API version and is subject to one or more of the breaking changes. API versions that fall into this category include 2023-07-10-preview for vectors and 2019-05-06.
Your code fails when unrecognized properties are returned in an API response. As a best practice, your application should ignore properties that it doesn't understand.
Your code persists API requests and tries to resend them to the new API version. For example, this might happen if your application persists continuation tokens returned from the Search API (for more information, look for
@search.nextPageParameters
in the Search API Reference).
Breaking change for client code that reads connection information
Effective March 29, 2024 and applies to all supported REST APIs:
GET Skillset, GET Index, and GET Indexer no longer return keys or connection properties in a response. This is a breaking change if you have downstream code that reads keys or connections (sensitive data) from a GET response.
If you need to retrieve admin or query API keys for your search service, use the Management REST APIs.
If you need to retrieve connection strings of another Azure resource such as Azure Storage or Azure Cosmos DB, use the APIs of that resource and published guidance to obtain the information.
Upgrade to 2023-10-01-preview
This section explains the migration path from 2023-07-01-preview to 2023-10-01-preview. You should migrate to 2023-10-01-preview if you want to use vector features that are still in public preview. If you don't need the preview features, we recommend upgrading to the stable release, 2023-11-01.
Preview features include:
Because these features didn't exist in previous API versions, there's no migration path. To learn how to add these features to your code, see code samples and walkthroughs.
In contrast, the vector field definitions, vector search algorithm configuration, and vector query syntax that were first introduced in 2023-07-01-preview have changed. The 2023-10-01-preview syntax for vector fields, algorithms, and vector queries is identical to the 2023-11-01 syntax. Migration steps for these vector constructs are explained in upgrade to 2023-11-01.
Portal upgrade for vector indexes
Azure portal supports a one-click upgrade path for 2023-07-01-preview indexes. The portal detects 2023-07-01-preview vector fields and provides a Migrate button.
- Migration path is from 2023-07-01-preview to 2023-10-01-preview.
- Updates are limited to vector field definitions and vector search algorithm configurations.
- Updates are one-way. You can't reverse the upgrade. Once the index is upgraded, you must use 2023-10-01-preview or later to query the index.
There's no portal migration for upgrading vector query syntax. See upgrade to 2023-11-01 for query syntax changes.
Before selecting Migrate, select Edit JSON to review the updated schema first. You should find a schema that conforms to the changes described in upgrade to 2023-11-01. Portal migration only handles indexes with one vector search algorithm configuration. It creates a default profile that maps to the 2023-07-01-preview vector search algorithm. Indexes with multiple vector search configurations require manual migration.
Upgrade to 2023-11-01
This version has breaking changes and behavioral differences for semantic ranking and vector search support.
Semantic ranking is generally available in 2023-11-01. It no longer uses the
queryLanguage
property. It also requires asemanticConfiguration
definition. AsemanticConfiguration
replacessearchFields
in previous versions. See Migrate from preview version for steps.Vector search support was introduced in Create or Update Index (2023-07-01-preview). Upgrading from 2023-07-01-preview requires renaming and restructuring the vector configuration in the index. It also requires rewriting your vector queries. Use the instructions in this section to migrate vector fields, configuration, and queries.
If you're upgrading from 2023-10-01-preview to 2023-11-01, there are no breaking changes, but there's one behavior difference: the
vectorFilterMode
default changed from postfilter to prefilter for filter expressions. If your 2023-10-01-preview code doesn't setvectorFilterMode
explicitly, make sure you understand the new default behavior, or explicity setvectorFilterMode
to postfilter to retain the old behavior.
Here are the steps for migrating from 2023-07-01-preview to 2023-11-01:
Call Get Index to retrieve the existing definition.
Modify the vector search configuration. 2023-11-01 introduces the concept of vector profiles that bundle vector-related configurations under one name. It also renames
algorithmConfigurations
toalgorithms
.Rename
algorithmConfigurations
toalgorithms
. This is only a renaming of the array. The contents are backwards compatible. This means your existing HNSW configuration parameters can be used.Add
profiles
, giving a name and an algorithm configuration for each one.
Before migration (2023-07-01-preview):
"vectorSearch": { "algorithmConfigurations": [ { "name": "myHnswConfig", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 500, "metric": "cosine" } } ]}
After migration (2023-11-01):
"vectorSearch": { "algorithms": [ { "name": "myHnswConfig", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 500, "metric": "cosine" } } ], "profiles": [ { "name": "myHnswProfile", "algorithm": "myHnswConfig" } ] }
Modify vector field definitions, replacing
vectorSearchConfiguration
withvectorSearchProfile
. Make sure the profile name resolves to a new vector profile definition, and not the algorithm configuration name. Other vector field properties remain unchanged. For example, they can't be filterable, sortable, or facetable, nor use analyzers or normalizers or synonym maps.Before (2023-07-01-preview):
{ "name": "contentVector", "type": "Collection(Edm.Single)", "key": false, "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "", "searchAnalyzer": "", "indexAnalyzer": "", "normalizer": "", "synonymMaps": "", "dimensions": 1536, "vectorSearchConfiguration": "myHnswConfig" }
After (2023-11-01):
{ "name": "contentVector", "type": "Collection(Edm.Single)", "searchable": true, "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "", "searchAnalyzer": "", "indexAnalyzer": "", "normalizer": "", "synonymMaps": "", "dimensions": 1536, "vectorSearchProfile": "myHnswProfile" }
Call Create or Update Index to post the changes.
Modify Search POST to change the query syntax. This API change enables support for polymorphic vector query types.
- Rename
vectors
tovectorQueries
. - For each vector query, add
kind
, setting it tovector
. - For each vector query, rename
value
tovector
. - Optionally, add
vectorFilterMode
if you're using filter expressions. The default is prefilter for indexes created after 2023-10-01. Indexes created before that date only support postfilter, regardless of how you set the filter mode.
Before (2023-07-01-preview):
{ "search": (this parameter is ignored in vector search), "vectors": [ { "value": [ 0.103, 0.0712, 0.0852, 0.1547, 0.1183 ], "fields": "contentVector", "k": 5 } ], "select": "title, content, category" }
After (2023-11-01):
{ "search": "(this parameter is ignored in vector search)", "vectorQueries": [ { "kind": "vector", "vector": [ 0.103, 0.0712, 0.0852, 0.1547, 0.1183 ], "fields": "contentVector", "k": 5 } ], "vectorFilterMode": "preFilter", "select": "title, content, category" }
- Rename
These steps complete the migration to 2023-11-01 API version.
Upgrade to 2020-06-30
In this version, there's one breaking change and several behavioral differences. Generally available features include:
- Knowledge store, persistent storage of enriched content created through skillsets, created for downstream analysis and processing through other applications. A knowledge store is created through Azure AI Search REST APIs but it resides in Azure Storage.
Breaking change
Code written against earlier API versions breaks on 2020-06-30
and later if code contains the following functionality:
- Any
Edm.Date
literals (a date composed of year-month-day, such as2020-12-12
) in filter expressions must follow theEdm.DateTimeOffset
format:2020-12-12T00:00:00Z
. This change was necessary to handle erroneous or unexpected query results due to timezone differences.
Behavior changes
BM25 ranking algorithm replaces the previous ranking algorithm with newer technology. Services created after 2019 use this algorithm automatically. For older services, you must set parameters to use the new algorithm.
Ordered results for null values have changed in this version, with null values appearing first if the sort is
asc
and last if the sort isdesc
. If you wrote code to handle how null values are sorted, be aware of this change.
Upgrade to 2019-05-06
Features that became generally available in this API version include:
- Autocomplete is a typeahead feature that completes a partially specified term input.
- Complex types provides native support for structured object data in search index.
- JsonLines parsing modes, part of Azure Blob indexing, creates one search document per JSON entity that is separated by a newline.
- AI enrichment provides indexing that uses the AI enrichment engines of Azure AI services.
Breaking changes
Code written against an earlier API version breaks on 2019-05-06
and later if it contains the following functionality:
Type property for Azure Cosmos DB. For indexers targeting an Azure Cosmos DB for NoSQL API data source, change
"type": "documentdb"
to"type": "cosmosdb"
.If your indexer error handling includes references to the
status
property, you should remove it. We removed status from the error response because it wasn't providing useful information.Data source connection strings are no longer returned in the response. From API versions
2019-05-06
and2019-05-06-Preview
onwards, the data source API no longer returns connection strings in the response of any REST operation. In previous API versions, for data sources created using POST, Azure AI Search returned 201 followed by the OData response, which contained the connection string in plain text.Named Entity Recognition cognitive skill is retired. If you called the Name Entity Recognition skill in your code, the call fails. Replacement functionality is Entity Recognition Skill (V3). Follow the recommendations in Deprecated skills to migrate to a supported skill.
Upgrading complex types
API version 2019-05-06
added formal support for complex types. If your code implemented previous recommendations for complex type equivalency in 2017-11-11-Preview or 2016-09-01-Preview, there are some new and changed limits starting in version 2019-05-06
of which you need to be aware:
The limits on the depth of subfields and the number of complex collections per index have been lowered. If you created indexes that exceed these limits using the preview api-versions, any attempt to update or recreate them using API version
2019-05-06
will fail. If you find yourself in this situation, you need to redesign your schema to fit within the new limits and then rebuild your index.There's a new limit starting in api-version
2019-05-06
on the number of elements of complex collections per document. If you created indexes with documents that exceed these limits using the preview api-versions, any attempt to reindex that data using api-version2019-05-06
will fail. If you find yourself in this situation, you need to reduce the number of complex collection elements per document before reindexing your data.
For more information, see Service limits for Azure AI Search.
How to upgrade an old complex type structure
If your code is using complex types with one of the older preview API versions, you might be using an index definition format that looks like this:
{
"name": "hotels",
"fields": [
{ "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
{ "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
{ "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
{ "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
{ "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
{ "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
{ "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
{ "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address", "type": "Edm.ComplexType" },
{ "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
{ "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
{ "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
{ "name": "Rooms", "type": "Collection(Edm.ComplexType)" },
{ "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
{ "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
{ "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
{ "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
{ "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
{ "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
{ "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
{ "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
]
}
A newer tree-like format for defining index fields was introduced in API version 2017-11-11-Preview
. In the new format, each complex field has a fields collection where its subfields are defined. In API version 2019-05-06, this new format is used exclusively and attempting to create or update an index using the old format will fail. If you have indexes created using the old format, you'll need to use API version 2017-11-11-Preview
to update them to the new format before they can be managed using API version 2019-05-06.
You can update flat indexes to the new format with the following steps using API version 2017-11-11-Preview
:
Perform a GET request to retrieve your index. If it’s already in the new format, you’re done.
Translate the index from the flat format to the new format. You have to write code for this task since there's no sample code available at the time of this writing.
Perform a PUT request to update the index to the new format. Avoid changing any other details of the index, such as the searchability/filterability of fields, because changes that affect the physical expression of existing index isn't allowed by the Update Index API.
Note
It is not possible to manage indexes created with the old "flat" format from the Azure portal. Please upgrade your indexes from the “flat” representation to the “tree” representation at your earliest convenience.
Next steps
Review the Search REST API reference documentation. If you encounter problems, ask us for help on Stack Overflow or contact support.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for