Skip to content

Commit f1dbd0a

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #259561 from HeidiSteen/heidist-fix
REST API migration from 2023-07-01-preview
2 parents 7970431 + 0ad3cee commit f1dbd0a

File tree

3 files changed

+200
-32
lines changed

3 files changed

+200
-32
lines changed

‎articles/search/search-api-migration.md

Lines changed: 189 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Upgrade REST API versions
33
titleSuffix: Azure AI Search
4-
description: Review differences in API versions and learn which actions are required to migrate existing code to the newest Azure AI Search service REST API version.
4+
description: Review differences in API versions and learn the steps for migrating code to the newest Azure AI Search service REST API version.
55

66
manager: nitinme
77
author: bevloh
@@ -10,39 +10,205 @@ ms.service: cognitive-search
1010
ms.custom:
1111
- ignite-2023
1212
ms.topic: conceptual
13-
ms.date: 10/03/2022
13+
ms.date: 11/27/2023
1414
---
1515

1616
# Upgrade to the latest REST API in Azure AI Search
1717

18-
If you're using an earlier version of the [**Search REST API**](/rest/api/searchservice/), this article will help you upgrade your application to the newest generally available API version, **2020-06-30**.
18+
Use this article to migrate data plane REST API calls to newer *stable* versions of the [**Search REST API**](/rest/api/searchservice/).
1919

20-
Version 2020-06-30 includes an important new feature ([knowledge store](knowledge-store-concept-intro.md)), and introduces several minor behavior changes. As such, this version is mostly backward compatible so code changes should be minimal if you're upgrading from the previous version (2019-05-06).
20+
+ [**2023-11-01**](/rest/api/searchservice/search-service-api-versions#2023-11-01) is the most recent stable version. Semantic ranking and vector search support are generally available in this version.
21+
22+
+ [**2023-10-01-preview**](/rest/api/searchservice/search-service-api-versions#2023-10-01-preview) is the most recent preview version. Integrated data chunking and vectorization using the [Text Split](cognitive-search-skill-textsplit.md) skill and [AzureOpenAiEmbedding](cognitive-search-skill-azure-openai-embedding.md) skill are introduced in this version. There's no migration guidance for preview API versions, but you can review code samples and walkthroughs for guidance. See [Integrated vectorization (preview)](vector-search-integrated-vectorization.md) for your first step.
2123

2224
> [!NOTE]
23-
> A search service supports a range of REST API versions, including earlier ones. You can continue to use those API versions, but we recommend migrating your code to the newest version so that you can access new capabilities. Over time, the most outdated versions of the REST API will be deprecated and [no longer supported](search-api-versions.md#unsupported-versions).
25+
> New filter controls on the table of contents provide version-specific API reference pages. To get the right information, open a reference page and then apply the filter.
2426
2527
<a name="UpgradeSteps"></a>
2628

2729
## How to upgrade
2830

29-
When upgrading to a new version, you probably won't have to make many changes to your code, other than to change the version number. The only situations in which you may need to change code are when:
30-
31-
* Your code fails when unrecognized properties are returned in an API response. By default your application should ignore properties that it doesn't understand.
32-
33-
* 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](/rest/api/searchservice/Search-Documents)).
31+
Azure AI Search strives for backward compatibility. To upgrade and continue with existing functionality, you can usually just change the API version number. Conversely, situations calling for change codes include:
3432

35-
* Your code references an API version that predates 2019-05-06 and is subject to one or more of the breaking changes in that release. The section [Upgrade to 2019-05-06](#upgrade-to-2019-05-06) provides more detail.
36-
37-
If any of these situations apply to you, then you may need to change your code accordingly. Otherwise, no changes should be necessary, although you might want to start using features added in the new version.
33+
+ 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.
34+
35+
+ 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](/rest/api/searchservice/Search-Documents)).
36+
37+
+ Your code references an API version that predates 2019-05-06 and is subject to one or more of the breaking changes in that release. The section [Upgrade to 2019-05-06](#upgrade-to-2019-05-06) provides more detail.
38+
39+
If any of these situations apply to you, change your code to maintain existing functionality. Otherwise, no changes should be necessary, although you might want to start using features added in the new version.
40+
41+
## Upgrade to 2023-11-01
42+
43+
This version has breaking changes and behavioral differences for semantic ranking and vector search support.
44+
45+
[Semantic ranking](semantic-search-overview.md) no longer uses `queryLanguage`. It also requires a `semanticConfiguration` definition. If you're migrating from 2020-06-30-preview, a semantic configuration replaces `searchFields`. See [Migrate from preview version](semantic-how-to-query-request.md#migrate-from-preview-versions) for steps.
46+
47+
[Vector search](vector-search-overview.md) support was introduced in [Create or Update Index (2023-07-01-preview)](/rest/api/searchservice/preview-api/create-or-update-index). If you're migrating from that version, there are new options and several breaking changes. New options include vector filter mode, vector profiles, and an exhaustive K-nearest neighbors algorithm and query-time exhaustive k-NN flag. Breaking changes include renaming and restructuring the vector configuration in the index, and vector query syntax.
48+
49+
If you added vector support using 2023-10-01-preview, there are no breaking changes. There's one behavior difference: the `vectorFilterMode` default changed from postfilter to prefilter. Change the API version and test your code to confirm the migration from the previous preview version (2023-07-01-preview).
50+
51+
> [!TIP]
52+
> You can upgrade a 2023-07-01-preview index in the Azure portal. The portal detects the previous version and provides a **Migrate** button. Select **Edit JSON** to review the updated schema before selecting **Migrate**. The new and changed schema conforms to the steps described in this section. Portal migration only handles indexes with one vector field. Indexes with more than one vector field require manual migration.
53+
54+
Here are the steps for migrating from 2023-07-01-preview:
55+
56+
1. Call [Get Index](/rest/api/searchservice/indexes/get?view=rest-searchservice-2023-11-01&tabs=HTTP&preserve-view=true) to retrieve the existing definition.
57+
58+
1. Modify the vector search configuration. This API introduces the concept of "vector profiles" which bundles together vector-related configurations under one name. It also renames `algorithmConfigurations` to `algorithms`.
59+
60+
+ Rename `algorithmConfigurations` to `algorithms`. This is only a renaming of the array. The contents are backwards compatible. This means your existing HNSW configuration parameters can be used.
61+
62+
+ Add `profiles`, giving a name and an algorithm configuration for each one.
63+
64+
**Before migration (2023-07-01-preview)**:
65+
66+
```http
67+
"vectorSearch": {
68+
"algorithmConfigurations": [
69+
{
70+
"name": "myHnswConfig",
71+
"kind": "hnsw",
72+
"hnswParameters": {
73+
"m": 4,
74+
"efConstruction": 400,
75+
"efSearch": 500,
76+
"metric": "cosine"
77+
}
78+
}
79+
]}
80+
```
81+
82+
**After migration (2023-11-01)**:
83+
84+
```http
85+
"vectorSearch": {
86+
"profiles": [
87+
{
88+
"name": "myHnswProfile",
89+
"algorithm": "myHnswConfig"
90+
}
91+
],
92+
"algorithms": [
93+
{
94+
"name": "myHnswConfig",
95+
"kind": "hnsw",
96+
"hnswParameters": {
97+
"m": 4,
98+
"efConstruction": 400,
99+
"efSearch": 500,
100+
"metric": "cosine"
101+
}
102+
}
103+
]
104+
}
105+
```
106+
107+
1. Modify vector field definitions, replacing `vectorSearchConfiguration` with `vectorSearchProfile`. Other vector field properties remain unchanged. For example, they can't be filterable, sortable, or facetable, nor use analyzers or normalizers or synonym maps.
108+
109+
**Before (2023-07-01-preview)**:
110+
111+
```http
112+
{
113+
"name": "contentVector",
114+
"type": "Collection(Edm.Single)",
115+
"key": false,
116+
"searchable": true,
117+
"retrievable": true,
118+
"filterable": false,
119+
"sortable": false,
120+
"facetable": false,
121+
"analyzer": "",
122+
"searchAnalyzer": "",
123+
"indexAnalyzer": "",
124+
"normalizer": "",
125+
"synonymMaps": "",
126+
"dimensions": 1536,
127+
"vectorSearchConfiguration": "myHnswConfig"
128+
}
129+
```
130+
131+
**After (2023-11-01)**:
132+
133+
```http
134+
{
135+
"name": "contentVector",
136+
"type": "Collection(Edm.Single)",
137+
"searchable": true,
138+
"retrievable": true,
139+
"filterable": false,
140+
"sortable": false,
141+
"facetable": false,
142+
"analyzer": "",
143+
"searchAnalyzer": "",
144+
"indexAnalyzer": "",
145+
"normalizer": "",
146+
"synonymMaps": "",
147+
"dimensions": 1536,
148+
"vectorSearchProfile": "myHnswProfile"
149+
}
150+
```
151+
152+
1. Call [Create or Update Index](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2023-11-01&tabs=HTTP&preserve-view=true) to post the changes.
153+
154+
1. Modify [Search POST](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2023-11-01&tabs=HTTP&preserve-view=true) to change the query syntax. This API change enables support for polymorphic vector query types.
155+
156+
+ Rename `vectors` to `vectorQueries`.
157+
+ For each vector query, add `kind`, setting it to "vector".
158+
+ For each vector query, rename `value` to `vector`.
159+
+ Optionally, add `vectorFilterMode` if you're using [filter expressions](vector-search-filters.md). 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.
160+
161+
**Before (2023-07-01-preview)**:
162+
163+
```http
164+
{
165+
"search": (this parameter is ignored in vector search),
166+
"vectors": [{
167+
"value": [
168+
0.103,
169+
0.0712,
170+
0.0852,
171+
0.1547,
172+
0.1183
173+
],
174+
"fields": "contentVector",
175+
"k": 5
176+
}],
177+
"select": "title, content, category"
178+
}
179+
```
180+
181+
**After (2023-11-01)**:
182+
183+
```http
184+
{
185+
"search": "(this parameter is ignored in vector search)",
186+
"vectorQueries": [
187+
{
188+
"kind": "vector",
189+
"vector": [
190+
0.103,
191+
0.0712,
192+
0.0852,
193+
0.1547,
194+
0.1183
195+
],
196+
"fields": "contentVector",
197+
"k": 5
198+
}
199+
],
200+
"vectorFilterMode": "preFilter",
201+
"select": "title, content, category"
202+
}
203+
```
204+
205+
These steps complete the migration to 2023-11-01 API version.
38206
39207
## Upgrade to 2020-06-30
40208
41-
Version 2020-06-30 is the new generally available release of the REST API. There's one breaking change and several behavioral differences.
42-
43-
Features are now generally available in this API version include:
209+
In this version, there's one breaking change and several behavioral differences. Generally available features include:
44210
45-
* [Knowledge store](knowledge-store-concept-intro.md), persistent storage of enriched content created through skillsets, created for downstream analysis and processing through other applications. With this capability, an indexer-driven AI enrichment pipeline can populate a knowledge store in addition to a search index. If you used the preview version of this feature, it's equivalent to the generally available version. The only code change required is modifying the api-version.
211+
+ [Knowledge store](knowledge-store-concept-intro.md), persistent storage of enriched content created through skillsets, created for downstream analysis and processing through other applications. A knowledge store exists in Azure Storage, which you provision and then provide connection details to a skillset. With this capability, an indexer-driven AI enrichment pipeline can populate a knowledge store in addition to a search index. If you used the preview version of this feature, it's equivalent to the generally available version. The only code change required is modifying the api-version.
46212
47213
### Breaking change
48214
@@ -52,7 +218,7 @@ Existing code written against earlier API versions will break on api-version=202
52218
53219
### Behavior changes
54220
55-
* [BM25 ranking algorithm](index-ranking-similarity.md) replaces the previous ranking algorithm with newer technology. New services will use this algorithm automatically. For existing services, you must set parameters to use the new algorithm.
221+
* [BM25 ranking algorithm](index-ranking-similarity.md) replaces the previous ranking algorithm with newer technology. New services use this algorithm automatically. For existing services, you must set parameters to use the new algorithm.
56222
57223
* 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 is `desc`. If you wrote code to handle how null values are sorted, be aware of this change.
58224
@@ -83,21 +249,21 @@ From API versions 2019-05-06 and 2019-05-06-Preview onwards, the data source API
83249
84250
#### Named Entity Recognition cognitive skill is now discontinued
85251
86-
If you called the [Name Entity Recognition](cognitive-search-skill-named-entity-recognition.md) skill in your code, the call will fail. Replacement functionality is [Entity Recognition Skill (V3)](cognitive-search-skill-entity-recognition-v3.md). Follow the recommendations in [Deprecated skills](cognitive-search-skill-deprecated.md) to migrate to a supported skill.
252+
If you called the [Name Entity Recognition](cognitive-search-skill-named-entity-recognition.md) skill in your code, the call fails. Replacement functionality is [Entity Recognition Skill (V3)](cognitive-search-skill-entity-recognition-v3.md). Follow the recommendations in [Deprecated skills](cognitive-search-skill-deprecated.md) to migrate to a supported skill.
87253
88254
### Upgrading complex types
89255
90256
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:
91257
92-
+ 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'll need to redesign your schema to fit within the new limits and then rebuild your index.
258+
+ 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.
93259
94-
+ 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-version 2019-05-06 will fail. If you find yourself in this situation, you'll need to reduce the number of complex collection elements per document before reindexing your data.
260+
+ 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-version 2019-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.
95261
96262
For more information, see [Service limits for Azure AI Search](search-limits-quotas-capacity.md).
97263
98264
#### How to upgrade an old complex type structure
99265
100-
If your code is using complex types with one of the older preview API versions, you may be using an index definition format that looks like this:
266+
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:
101267
102268
```json
103269
{
@@ -138,7 +304,7 @@ You can update "flat" indexes to the new format with the following steps using A
138304

139305
1. Perform a GET request to retrieve your index. If it’s already in the new format, you’re done.
140306

141-
2. Translate the index from the “flat” format to the new format. You’ll have to write code for this task since there's no sample code available at the time of this writing.
307+
2. 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.
142308

143309
3. 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.
144310

0 commit comments

Comments
 (0)