Merge pull request #272366 from HeidiSteen/heidist-vectors

[azure search] deprecated REST API

Author: prmerger-automator[bot]

articles/search/search-api-migration.md

@@ -1,7 +1,7 @@
 ---
 title: Upgrade REST API versions
 titleSuffix: Azure AI Search
-description: Review differences in API versions and learn the steps for migrating code to the newest Azure AI Search service REST API version.
+description: Review differences in API versions and learn the steps for migrating code to the newer versions.
 
 manager: nitinme
 author: bevloh
@@ -10,43 +10,53 @@ ms.service: cognitive-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 11/27/2023
+ms.date: 04/17/2024
 ---
 
 # Upgrade to the latest REST API in Azure AI Search
 
-Use this article to migrate data plane calls to newer *stable* versions of the [**Search REST API**](/rest/api/searchservice/).
+Use this article to migrate data plane calls to newer versions of the [**Search REST API**](/rest/api/searchservice/).
 
-+ [**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.
++ [**2023-11-01**](/rest/api/searchservice/search-service-api-versions#2023-11-01) is the most recent stable version. Semantic ranking and support for indexing and querying vectors are generally available in this version.
 
-+ [**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](vector-search-integrated-vectorization.md) using the [Text Split](cognitive-search-skill-textsplit.md) skill and [Azure OpenAI Embedding](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](https://github.com/Azure/azure-search-vector-samples) and [walkthroughs](vector-search-how-to-configure-vectorizer.md) for help with new features.
++ [**2023-10-01-preview**](/rest/api/searchservice/search-service-api-versions#2023-10-01-preview) is the most recent preview version. Preview features include [built-in query vectorization](vector-search-how-to-configure-vectorizer.md), [built-in data chunking and vectorization during indexing](vector-search-integrated-vectorization.md) (uses the [Text Split](cognitive-search-skill-textsplit.md) skill and [Azure OpenAI Embedding](cognitive-search-skill-azure-openai-embedding.md) skill). Refer to [code samples](https://github.com/Azure/azure-search-vector-samples) and [walkthroughs](vector-search-how-to-configure-vectorizer.md) for help with new features.
+
++ **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]
-> API reference docs are now versioned. To get the right content, open a reference page and then apply the version-specific filter located above the table of contents.
+> 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.
 
 <a name="UpgradeSteps"></a>
 
 ## How to upgrade
 
-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:
+Azure AI Search breaks backward compatibility as a last resort. This section provides instructions to help you modify existing code that won't run in a newer version. 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](#upgrade-to-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](/rest/api/searchservice/Search-Documents)).
 
-+ 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. 
+## Upgrade to 2023-10-01-preview
+
+This version is identical to 2023-11-01 but has extra features in public preview: [built-in query vectorizer](vector-search-how-to-configure-vectorizer.md) and [vector prefilter mode](vector-search-filters.md). If you want to use those features, you should upgrade to the latest preview version.
 
-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.
+The vector search algorithm configuration inside a search index is identical to 2023-11-01. To fix breaking changes from 2023-07-01-preview, follow the instructions in the next section.
 
 ## Upgrade to 2023-11-01
 
 This version has breaking changes and behavioral differences for semantic ranking and vector search support. 
 
-+ [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-configure.md#migrate-from-preview-versions) for steps.
++ [Semantic ranking](semantic-search-overview.md) is generally available and no longer uses the `queryLanguage` property. It also requires a `semanticConfiguration` definition. 
+
+   To upgrade from 2020-06-30-preview, create a `semanticConfiguration` to replace `searchFields`. See [Migrate from preview version](semantic-how-to-configure.md#migrate-from-preview-versions) for steps.
+
++ [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).
 
-+ [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.
+   To upgrade from 2023-07-01-preview, rename and restructure the vector configuration in the index, and rewrite your vector query syntax using the instructions in this section.
 
-If you added vector support using 2023-10-01-preview, there are no breaking changes, but there's one behavior difference: the `vectorFilterMode` default changed from postfilter to prefilter for [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. 
+   To upgrade from 2023-10-01-preview, there are no breaking changes, but there's one behavior difference: the `vectorFilterMode` default changed from postfilter to prefilter for [filter expressions](vector-search-filters.md). If your 2023-10-01-preview code doesn't set `vectorFilterMode` explicitly, make sure you understand the new behavior, or set the mode to postfilter to retain the old behavior. 
 
 > [!TIP]
 > Azure portal supports a one-click upgrade path for 2023-07-01-preview indexes. The portal detects 2023-07-01-preview indexes and provides a **Migrate** button. Before selecting **Migrate**, select **Edit JSON** to review the updated schema first. You should find a schema that conforms to the changes described in this section. Portal migration only handles indexes with one vector search algorithm configuration, creating a default profile that maps to the algorithm. Indexes with multiple configurations require manual migration.
@@ -55,7 +65,7 @@ Here are the steps for migrating from 2023-07-01-preview:
 
 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.
 
-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`.
+1. Modify the vector search configuration. This API introduces the concept of *vector profiles that bundles together vector-related configurations under one name. It also renames `algorithmConfigurations` to `algorithms`.
 
    + 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.
 
@@ -210,48 +220,40 @@ These steps complete the migration to 2023-11-01 API version.
 
 In this version, there's one breaking change and several behavioral differences. Generally available features include:
 
-+ [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.
++ [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 is created through Azure AI Search REST APIs but it resides in Azure Storage. 
 
 ### Breaking change
 
-Existing code written against earlier API versions will break on api-version=2020-06-30 and later if code contains the following functionality:
+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 as `2020-12-12`) in filter expressions must follow the Edm.DateTimeOffset format: `2020-12-12T00:00:00Z`. This change was necessary to handle erroneous or unexpected query results due to timezone differences.
++ Any Edm.Date literals (a date composed of year-month-day, such as `2020-12-12`) in filter expressions must follow the Edm.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](index-ranking-similarity.md) 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.  
++ [BM25 ranking algorithm](index-ranking-similarity.md) 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 is `desc`. If you wrote code to handle how null values are sorted, be aware of this change.
++ 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.
 
 ## Upgrade to 2019-05-06
 
-Version 2019-05-06 is the previous generally available release of the REST API. Features that became generally available in this API version include:
+Features that became generally available in this API version include:
 
-* [Autocomplete](index-add-suggesters.md) is a typeahead feature that completes a partially specified term input.
-* [Complex types](search-howto-complex-data-types.md) provides native support for structured object data in search index.
-* [JsonLines parsing modes](search-howto-index-json-blobs.md), part of Azure Blob indexing, creates one search document per JSON entity that is separated by a newline.
-* [AI enrichment](cognitive-search-concept-intro.md) provides indexing that uses the AI enrichment engines of Azure AI services.
++ [Autocomplete](index-add-suggesters.md) is a typeahead feature that completes a partially specified term input.
++ [Complex types](search-howto-complex-data-types.md) provides native support for structured object data in search index.
++ [JsonLines parsing modes](search-howto-index-json-blobs.md), part of Azure Blob indexing, creates one search document per JSON entity that is separated by a newline.
++ [AI enrichment](cognitive-search-concept-intro.md) provides indexing that uses the AI enrichment engines of Azure AI services.
 
 ### Breaking changes
 
-Existing code written against earlier API versions will break on api-version=2019-05-06 and later if code contains the following functionality:
-
-#### Indexer for Azure Cosmos DB - datasource is now `"type": "cosmosdb"`
-
-If you're using an [Azure Cosmos DB indexer](search-howto-index-cosmosdb.md), you must change `"type": "documentdb"` to `"type": "cosmosdb"`.
-
-#### Indexer execution result errors no longer have status
-
-The error structure for indexer execution previously had a `status` element. This element was removed because it wasn't providing useful information.
+Code written against an earlier API version breaks on 2019-05-06 and later if it contains the following functionality:
 
-#### Indexer data source API no longer returns connection strings
+1. Type property for Azure Cosmos DB. For indexers targeting an [Azure Cosmos DB for NoSQL API](search-howto-index-cosmosdb.md) data source, change `"type": "documentdb"` to `"type": "cosmosdb"`.
 
-From API versions 2019-05-06 and 2019-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.
+1. 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.
 
-#### Named Entity Recognition cognitive skill is now discontinued
+1. Data source connection strings are no longer returned in the response. From API versions 2019-05-06 and 2019-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.
 
-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.
+1. Named Entity Recognition cognitive skill is retired. 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.
 
 ### Upgrading complex types
 
@@ -306,9 +308,9 @@ You can update "flat" indexes to the new format with the following steps using A
 
 1. Perform a GET request to retrieve your index. If it’s already in the new format, you’re done.
 
-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.
+1. 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.
 
-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.
+1. 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.

articles/search/search-api-versions.md

@@ -14,7 +14,7 @@ ms.custom:
   - devx-track-python
   - ignite-2023
 ms.topic: conceptual
-ms.date: 01/10/2024
+ms.date: 04/17/2024
 ---
 
 # API versions in Azure AI Search
@@ -25,6 +25,10 @@ As a rule, the REST APIs and libraries are versioned only when necessary, since
 
 See [Azure SDK lifecycle and support policy](https://azure.github.io/azure-sdk/policies_support.html) for more information about the deprecation path.
 
+## Deprecated versions
+
+**2023-07-01-preview** was deprecated on April 8, 2024 and will be retired on July 8, 2024. This was the first REST API that offered vector search support. Newer API versions have a different vector configuration. We recommend [migrating to a newer version](search-api-migration.md) as soon as possible.
+
 <a name="unsupported-versions"></a>
 
 ## Unsupported versions

articles/search/whats-new.md

@@ -7,7 +7,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
 ms.topic: overview
-ms.date: 04/03/2024
+ms.date: 04/17/2024
 ms.custom:
   - references_regions
   - ignite-2023
@@ -26,6 +26,7 @@ ms.custom:
 | [**Built-in vector quantization, narrow vector data types, and a new `stored` property (preview)**](vector-search-how-to-configure-compression-storage.md) | Feature | This preview adds support for larger vector workloads at a lower cost through three enhancements. First, *scalar quantization* reduces vector index size in memory and on disk. Second, [narrow data types](/rest/api/searchservice/supported-data-types) can be assigned to vector fields that can use them. Third, we added more flexible vector field storage options.|
 | [**2024-03-01-preview Search REST API**](/rest/api/searchservice/search-service-api-versions#2024-03-01-preview) | API | New preview version of the Search REST APIs for the new data types, vector compression properties, and storage options. |
 | [**2024-03-01-preview Management REST API**](/rest/api/searchmanagement/operation-groups?view=rest-searchmanagement-2024-03-01-preview&preserve-view=true) | API | New preview version of the Management REST APIs for control plane operations.  |
+| [**2023-07-01-preview deprecation announcement**](/rest/api/searchservice/search-service-api-versions#2023-07-01-preview) | API | Deprecation announced on April 8, 2024. Retirement on July 8, 2024. This was the first REST API that offered vector search support. Newer API versions have a different vector configuration. We recommend [migrating to a newer version](search-api-migration.md) as soon as possible. |
 
 ## February 2024