@@ -382,4 +382,4 @@
             "redirect_document_id": false
         }
     ]
-}
\ No newline at end of file
+  }
\ No newline at end of file

@@ -50,7 +50,7 @@ Using the Azure portal or newer preview REST APIs and beta SDK packages, you can
 
 1. On your Azure AI services multi-service resource, [assign the identity](/azure/role-based-access-control/role-assignments-portal) to the **Cognitive Services User** role.
 
-1. Using the Azure portal, or the [Skillset 2024-11-01-preview REST API](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2024-11-01-preview&preserve-view=true), or an Azure SDK beta package that provides the syntax, configure a skillset to use an identity:
+1. Using the Azure portal, or the [Skillset 2024-11-01-preview REST API](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2024-11-01-preview&preserve-view=true) or later, or an Azure SDK beta package that provides the syntax, configure a skillset to use an identity:
 
    + The managed identity used on the connection belongs to the search service. It can be system managed or user assigned.
 

@@ -11,7 +11,7 @@ ms.custom:
   - references_regions
   - ignite-2024
 ms.topic: reference
-ms.date: 02/13/2025
+ms.date: 04/07/2025
 ---
 
 # Document Layout skill
@@ -22,12 +22,13 @@ The **Document Layout** skill analyzes a document to extract regions of interest
 
 This article is the reference documentation for the Document Layout skill. For usage information, see [Structure-aware chunking and vectorization](search-how-to-semantic-chunking.md).
 
-The **Document Layout** skill calls the [Document Intelligence Public preview version 2024-07-31-preview](/rest/api/aiservices/operation-groups?view=rest-aiservices-v4.0%20(2024-07-31-preview)&preserve-view=true). It's currently only available in the following Azure regions:
+The **Document Layout** skill calls the [Document Intelligence Public preview version 2024-07-31-preview](/rest/api/aiservices/operation-groups?view=rest-aiservices-v4.0%20(2024-07-31-preview)&preserve-view=true). 
 
-+ East US
-+ West US2
-+ West Europe
-+ North Central US
+Supported regions varies by modality:
+
++ In code, your skillset can call Document Intelligence through an Azure AI multi-service resource in any region that provides both AI enrichment and Document Intelligence. See [Product availability by region](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/table) to find regions that provide both *AI enrichment* in Azure AI Search and *Document Intelligence* under Azure AI services.
+
++ In the [Import and vectorize data](search-import-data-portal.md) wizard in the Azure portal, you can enable document layout detection in the data source connection step. Document layout detection in the portal is available in the following Azure regions: **East US**, **West Europe**, **North Central US**. Create an Azure AI multi-service resource in one of these three regions to get the portal experience.
 
 Supported file formats include:
 
@@ -59,7 +60,7 @@ Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill
 
 ## Supported languages
 
-Refer to [Azure AI Document Intelligence layout model supported languages](/azure/ai-services/document-intelligence/language-support/ocr?view=doc-intel-3.1.0&tabs=read-print%2Clayout-print%2Cgeneral#layout) for printed text.
+Refer to [Azure AI Document Intelligence layout model supported languages](/azure/ai-services/document-intelligence/language-support/ocr?view=doc-intel-3.1.0&tabs=read-print%2Clayout-print%2Cgeneral#layout&preserve-view=true) for printed text.
 
 ## Limitations
 

@@ -1,5 +1,5 @@
 ---
-title: 'Tutorial: Skillsets using C#'
+title: 'Tutorial: Skillsets Using C#'
 titleSuffix: Azure AI Search
 description: Use C# and the Azure SDK for .NET to create skillsets. This skillset applies AI transformations and analyses to create searchable content from images and unstructured text.
 
@@ -9,7 +9,7 @@ manager: nitinme
 
 ms.service: azure-ai-search
 ms.topic: tutorial
-ms.date: 01/17/2025
+ms.date: 03/31/2025
 ms.custom:
   - devx-track-csharp
   - devx-track-dotnet
@@ -18,19 +18,17 @@ ms.custom:
 
 # C# Tutorial: Use skillsets to generate searchable content in Azure AI Search
 
-In this tutorial, learn how to use the [Azure SDK for .NET](https://www.nuget.org/packages/Azure.Search.Documents/) to create an [AI enrichment pipeline](cognitive-search-concept-intro.md) for content extraction and transformations during indexing.
+Learn how to use the [Azure SDK for .NET](https://www.nuget.org/packages/Azure.Search.Documents/) to create an [AI enrichment pipeline](cognitive-search-concept-intro.md) for content extraction and transformations during indexing.
 
-Skillsets add AI processing to raw content, making that content more uniform and searchable. Once you know how skillsets work, you can support a broad range of transformations: from image analysis, to natural language processing, to customized processing that you provide externally.
+Skillsets add AI processing to raw content, making it more uniform and searchable. Once you know how skillsets work, you can support a broad range of transformations, from image analysis to natural language processing to customized processing that you provide externally.
 
-This tutorial helps you learn how to:
+In this tutorial, you:
 
 > [!div class="checklist"]
 > + Define objects in an enrichment pipeline.
 > + Build a skillset. Invoke OCR, language detection, entity recognition, and key phrase extraction.
 > + Execute the pipeline. Create and load a search index.
-> + Check the results using full text search.
-
-If you don't have an Azure subscription, open a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
+> + Check the results using full-text search.
 
 ## Overview
 
@@ -42,16 +40,18 @@ Once content is extracted, the [skillset](cognitive-search-working-with-skillset
 
 ## Prerequisites
 
-+ [Visual Studio](https://visualstudio.microsoft.com/downloads/)
++ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+
++ [Azure Storage](/azure/storage/common/storage-account-create).
 
-+ [Azure.Search.Documents 11.x NuGet package](https://www.nuget.org/packages/Azure.Search.Documents) 
++ [Azure AI Search](search-create-app-portal.md).
 
-+ [Azure Storage](/azure/storage/common/storage-account-create)
++ [Azure.Search.Documents 11.x NuGet package](https://www.nuget.org/packages/Azure.Search.Documents).
 
-+ [Azure AI Search](search-create-app-portal.md)
++ [Visual Studio](https://visualstudio.microsoft.com/downloads/).
 
 > [!NOTE]
-> You can use a free search service for this tutorial. The free tier limits you to three indexes, three indexers, and three data sources. This tutorial creates one of each. Before starting, make sure you have room on your service to accept the new resources.
+> You can use a free search service for this tutorial. The Free tier limits you to three indexes, three indexers, and three data sources. This tutorial creates one of each. Before you start, make sure you have room on your service to accept the new resources.
 
 ### Download files
 

@@ -1,5 +1,5 @@
 ---
-title: 'Tutorial: Skillsets using REST'
+title: 'Tutorial: Skillsets Using REST'
 titleSuffix: Azure AI Search
 description: Use the Search REST APIs to create skillsets. This skillset applies AI transformations and analyses to create searchable content from images and unstructured text.
 
@@ -9,25 +9,23 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: tutorial
-ms.date: 01/17/2025
+ms.date: 03/31/2025
 ---
 
 # REST Tutorial: Use skillsets to generate searchable content in Azure AI Search
 
-In this tutorial, learn how to call REST APIs that create an [AI enrichment pipeline](cognitive-search-concept-intro.md) for content extraction and transformations during indexing.
+Learn how to call REST APIs that create an [AI enrichment pipeline](cognitive-search-concept-intro.md) for content extraction and transformations during indexing.
 
-Skillsets add AI processing to raw content, making that content more uniform and searchable. Once you know how skillsets work, you can support a broad range of transformations: from image analysis, to natural language processing, to customized processing that you provide externally.
+Skillsets add AI processing to raw content, making it more uniform and searchable. Once you know how skillsets work, you can support a broad range of transformations, from image analysis to natural language processing to customized processing that you provide externally.
 
-This tutorial helps you learn how to:
+In this tutorial, you:
 
 > [!div class="checklist"]
 > + Define objects in an enrichment pipeline.
 > + Build a skillset. Invoke OCR, language detection, entity recognition, and key phrase extraction.
 > + Execute the pipeline. Create and load a search index.
 > + Check the results using full text search.
 
-If you don't have an Azure subscription, open a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
-
 ## Overview
 
 This tutorial uses a REST client and the [Azure AI Search REST APIs](/rest/api/searchservice/) to create a data source, index, indexer, and skillset.
@@ -38,20 +36,22 @@ Once content is extracted, the [skillset](cognitive-search-working-with-skillset
 
 ## Prerequisites
 
-+ [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client)
++ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
 
 + [Azure Storage](/azure/storage/common/storage-account-create)
 
 + [Azure AI Search](search-create-app-portal.md)
 
++ [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client)
+
 > [!NOTE]
-> You can use a free search service for this tutorial. The free tier limits you to three indexes, three indexers, and three data sources. This tutorial creates one of each. Before starting, make sure you have room on your service to accept the new resources.
+> You can use a free search service for this tutorial. The Free tier limits you to three indexes, three indexers, and three data sources. This tutorial creates one of each. Before you start, make sure you have room on your service to accept the new resources.
 
 ### Download files
 
 Download a zip file of the sample data repository and extract the contents. [Learn how](https://docs.github.com/get-started/start-your-journey/downloading-files-from-github).
 
-+ [Sample data files (mixed media)](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/ai-enrichment-mixed-media). 
++ [Sample data files (mixed media)](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/ai-enrichment-mixed-media).
 
 + [Sample REST file](https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/skillset-tutorial)
 

@@ -1,5 +1,5 @@
 ---
-title: 'Tutorial: Debug skillsets'
+title: 'Tutorial: Debug Skillsets'
 titleSuffix: Azure AI Search
 description: Practice creating and completing a debug session on an Azure AI Search skillset. This tutorial provides a buggy sample skillset that you resolve in a debug session.
 
@@ -10,7 +10,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: tutorial
-ms.date: 12/03/2024
+ms.date: 03/31/2025
 ---
 
 # Tutorial: Fix a skillset using Debug Sessions
@@ -19,15 +19,15 @@ In Azure AI Search, a skillset coordinates the actions of skills that analyze, t
 
 **Debug Sessions** is an Azure portal tool that provides a holistic visualization of a skillset that executes on Azure AI Search. Using this tool, you can drill down to specific steps to easily see where an action might be falling down.
 
-In this article, use **Debug Sessions** to find and fix missing inputs and outputs. The tutorial is all-inclusive. It provides sample data, a REST file that creates objects, and instructions for debugging problems in the skillset.
-
-If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
+In this tutorial, you use **Debug Sessions** to find and fix missing inputs and outputs. The tutorial is all-inclusive. It provides sample data, a REST file that creates objects, and instructions for debugging problems in the skillset.
 
 ## Prerequisites
 
-+ Azure AI Search. [Create a service](search-create-service-portal.md) or [find an existing service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) under your current subscription. You can use a free service for this tutorial. The free tier doesn't provide managed identity support for an Azure AI Search service. You must use keys for connections to Azure Storage.
++ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+
++ Azure AI Search. [Create a service](search-create-service-portal.md) or [find an existing service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) in your current subscription. You can use a free service for this tutorial. The Free tier doesn't provide managed identity support for an Azure AI Search service. You must use keys for connections to Azure Storage.
 
-+ Azure Storage account with [Blob storage](/azure/storage/blobs/), used for hosting sample data, and for persisting cached data created during a debug session. If you're using a free search service, the storage account must have shared access keys enabled and it must allow public network access.
++ Azure Storage account with [Blob storage](/azure/storage/blobs/), used for hosting sample data and for persisting cached data created during a debug session. If you're using a free search service, the storage account must have shared access keys enabled and it must allow public network access.
 
 + [Visual Studio Code](https://code.visualstudio.com/download) with a [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client).
 
@@ -44,29 +44,29 @@ This section creates the sample data set in Azure Blob Storage so that the index
 
 1. [Download sample data (clinical-trials-pdf-19)](https://github.com/Azure-Samples/azure-search-sample-data/tree/main/_ARCHIVE/clinical-trials/clinical-trials-pdf-19), consisting of 19 files.
 
-1. [Create an Azure Storage account](/azure/storage/common/storage-account-create?tabs=azure-portal) or [find an existing account](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Storage%2storageAccounts/). 
+1. [Create an Azure Storage account](/azure/storage/common/storage-account-create?tabs=azure-portal) or [find an existing account](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Storage%2storageAccounts/).
 
    + Choose the same region as Azure AI Search to avoid bandwidth charges.
 
    + Choose the StorageV2 (general purpose V2) account type.
 
-1. Navigate to the Azure Storage services pages in the Azure portal and create a Blob container. Best practice is to specify the access level "private". Name your container `clinicaltrialdataset`.
+1. Go to the Azure Storage services pages in the Azure portal and create a Blob container. Best practice is to specify the access level "private". Name your container `clinicaltrialdataset`.
 
 1. In container, select **Upload** to upload the sample files you downloaded and unzipped in the first step.
 
-1. While in the Azure portal, copy the connection string for Azure Storage. You can get the connection string from **Settings** > **Access Keys** in the Azure portal.
+1. In the Azure portal, select **Settings** > **Access Keys** and copy the connection string for Azure Storage.
 
 ## Copy a key and URL
 
 This tutorial uses API keys for authentication and authorization. You need the search service endpoint and an API key, which you can get from the Azure portal.
 
-1. Sign in to the [Azure portal](https://portal.azure.com), navigate to the **Overview** page, and copy the URL. An example endpoint might look like `https://mydemo.search.windows.net`.
+1. Sign in to the [Azure portal](https://portal.azure.com), go to the **Overview** page, and copy the URL. An example endpoint might look like `https://mydemo.search.windows.net`.
 
 1. Under **Settings** > **Keys**, copy an admin key. Admin keys are used to add, modify, and delete objects. There are two interchangeable admin keys. Copy either one.
 
    :::image type="content" source="media/search-get-started-rest/get-url-key.png" alt-text="Screenshot of the URL and API keys in the Azure portal.":::
 
-A valid API key establishes trust, on a per request basis, between the application sending the request and the search service handling it.
+A valid API key establishes trust, on a per-request basis, between the application sending the request and the search service handling it.
 
 ## Create data source, skillset, index, and indexer
 
@@ -82,9 +82,9 @@ In this section, create a "buggy" workflow that you can fix in this tutorial.
 
 ## Check results in the Azure portal
 
-The sample code intentionally creates a buggy index as a consequence of problems that occurred during skillset execution. The problem is that the index is missing data. 
+The sample code intentionally creates a buggy index as a consequence of problems that occurred during skillset execution. The problem is that the index is missing data.
 
-1. In Azure portal, on the search service **Overview** page, select the **Indexes** tab. 
+1. In Azure portal, on the search service **Overview** page, select the **Indexes** tab.
 
 1. Select *clinical-trials*.
 
@@ -98,15 +98,15 @@ The sample code intentionally creates a buggy index as a consequence of problems
 
 1. Run the query. You should see empty values for `organizations` and `locations`.
 
-    These fields should have been populated through the skillset's [Entity Recognition skill](cognitive-search-skill-entity-recognition-v3.md), used to detect organizations and locations anywhere within the blob's content. In the next exercise, you'll debug the skillset to determine what went wrong.
+    These fields should have been populated through the skillset's [Entity Recognition skill](cognitive-search-skill-entity-recognition-v3.md), used to detect organizations and locations anywhere within the blob's content. In the next exercise, you debug the skillset to determine what went wrong.
 
 Another way to investigate errors and warnings is through the Azure portal.
 
-1. Open the **Indexers** tab and select *clinical-trials-idxr*.
+1. On the **Indexers** tab, select *clinical-trials-idxr*.
 
    Notice that while the indexer job succeeded overall, there were warnings.
 
-1. Select **Success** to view the warnings (if there were mostly errors, the detail link would be **Failed**). You'll see a long list of every warning emitted by the indexer.
+1. Select **Success** to view the warnings. If there are mostly errors, the detail link is **Failed**. You should see a long list of every warning emitted by the indexer.
 
    :::image type="content" source="media/cognitive-search-debug/portal-indexer-errors-warnings.png" alt-text="Screenshot of view warnings." :::
 
@@ -116,27 +116,27 @@ Another way to investigate errors and warnings is through the Azure portal.
 
 1. Select **+ Add Debug Session**.
 
-1. Give the session a name. 
+1. Give the session a name.
 
 1. In Indexer template, provide the indexer name. The indexer has references to the data source, the skillset, and index.
 
 1. Select the storage account.
 
-1. **Save** the session. 
+1. **Save** the session.
 
    :::image type="content" source="media/cognitive-search-debug/debug-tutorial-create-session.png" lightbox="media/cognitive-search-debug/debug-tutorial-create-session.png" alt-text="Screenshot of Debug session definition page." :::
   
 1. A debug session opens to the settings page. You can make modifications to the initial configuration and override any defaults. A debug session only works with a single document. The default is to accept the first document in the collection as the basis of your debug sessions. You can [choose a specific document to debug](cognitive-search-how-to-debug-skillset.md#create-a-debug-session) by providing its URI in Azure Storage.
 
-1. When the debug session has finished initializing, you should see a skills workflow with mappings and a search index. The enriched document data structure appears in a details pane on the side. We excluded it from the following screenshot so that you could see more of the workflow.
+1. When the debug session finishes initializing, you should see a skills workflow with mappings and a search index. The enriched document data structure appears in a details pane on the side. We excluded it from the following screenshot so that you could see more of the workflow.
 
    :::image type="content" source="media/cognitive-search-debug/debug-execution-complete1.png" lightbox="media/cognitive-search-debug/debug-execution-complete1.png" alt-text="Screenshot of Debug Session visual editor." :::
 
 ## Find issues with the skillset
 
 Any issues reported by the indexer are indicated as **Errors** and **Warnings**.
 
-Notice that the number of errors and warning is a much smaller list than the one displayed earlier because this list is only detailing the errors for a single document. Like the list displayed by the indexer, you can select on a warning message and see the details of this warning.
+Notice that the number of errors and warnings is a smaller list than the one displayed earlier because this list is only detailing the errors for a single document. Like the list displayed by the indexer, you can select on a warning message and see the details of this warning.
 
 Select **Warnings** to review the notifications. You should see four:
 
@@ -163,7 +163,7 @@ Because all four notifications are about this skill, your next step is to debug
 
    :::image type="content" source="media/cognitive-search-debug/debug-tutorial-skill-detail.png" alt-text="Screenshot of the skill details pane.":::
 
-1. Hover over each input (or select an input) to show the values in the **Expression evaluator**. Notice that the displayed result for this input doesn’t look like a text input. It looks like a series of new line characters `\n \n\n\n\n` instead of text. The lack of text means that no entities can be identified, so either this document fails to meet the prerequisites of the skill, or there's another input that should be used instead.
+1. Hover over each input (or select an input) to show the values in the **Expression evaluator**. Notice that the displayed result for this input doesn’t look like a text input. It looks like a series of new line characters `\n \n\n\n\n` instead of text. The lack of text means that no entities can be identified. Either this document doesn't meet the prerequisites of the skill, or there's another input that should be used instead.
 
    :::image type="content" source="media/cognitive-search-debug/debug-tutorial-skill-input-null.png" alt-text="Screenshot of skill input showing null values.":::
 
@@ -177,7 +177,7 @@ Because all four notifications are about this skill, your next step is to debug
 
    :::image type="content" source="media/cognitive-search-debug/debug-tutorial-edit-skill.png" alt-text="Screenshot of Expression Evaluator for fixed merged_content input." :::
 
-1. Select **Run** in the session's window menu. This kicks off another execution of the skillset using the document. 
+1. Select **Run** in the session's window menu. This kicks off another execution of the skillset using the document.
 
 1. Once the debug session execution completes, notice that the warnings count has reduced by one. Warnings show that the error for text input is gone, but the other warnings remain. The next step is to address the warning about the missing or empty value `/document/languageCode`.
 
@@ -221,11 +221,11 @@ The messages say to check the 'outputFieldMappings' property of your indexer, so
 
 1. Select **Run**.
 
-All of the errors have been resolved.
+All of the errors are resolved.
 
 ## Commit changes to the skillset
 
-When the debug session was initiated, the search service created a copy of the skillset. This was done to protect the original skillset on your search service. Now that you have finished debugging your skillset, the fixes can be committed (overwrite the original skillset). 
+When the debug session was initiated, the search service created a copy of the skillset. This was done to protect the original skillset on your search service. Now that you debugged your skillset, the fixes can be committed (overwrite the original skillset).
 
 Alternatively, if you aren't ready to commit changes, you can save the debug session and reopen it later.
 
@@ -243,7 +243,7 @@ Alternatively, if you aren't ready to commit changes, you can save the debug ses
 
 1. Select **Refresh** to show the status of the reset and run commands.
 
-When the indexer has finished running, there should be a green checkmark and the word Success next to the time stamp for the latest run in the **Execution history** tab. To ensure that the changes have been applied:
+When the indexer finishes running, there should be a green checkmark and the word Success next to the time stamp for the latest run in the **Execution history** tab. To ensure that the changes are applied:
 
 1. In the left pane, open **Indexes**.
 
@@ -263,7 +263,7 @@ The free service is limited to three indexes, indexers, and data sources. You ca
 
 ## Next steps
 
-This tutorial touched on various aspects of skillset definition and processing. To learn more about concepts and workflows, refer to the following articles:
+This tutorial touched on various aspects of skillset definition and processing. To learn more about concepts and workflows, see the following articles:
 
 + [How to map skillset output fields to fields in a search index](cognitive-search-output-field-mapping.md)
 

@@ -1,13 +1,13 @@
 ---
-title: include file
-description: include file
+title: Include file
+description: Include file
 author: eric-urban
 ms.author: eur
 ms.service: azure-ai-speech
 ms.topic: include
-ms.date: 9/20/2024
+ms.date: 03/19/2024
 ms.custom: include, ignite-2024
 ---
 
 > [!NOTE]
-> This feature is currently in public preview. This preview is provided without a service-level agreement, and is not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
+> This feature is currently in public preview. This preview is provided without a service-level agreement and isn't recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

@@ -8,7 +8,7 @@ author: haileytap
 ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: conceptual
-ms.date: 10/28/2024
+ms.date: 04/07/2025
 ---
 
 # Training - Azure AI Search
@@ -27,10 +27,9 @@ Learning paths are a collection of training modules that are organized around sp
 
 | Module | Learning path |
 |--------|---------------|
-[Fundamentals of Knowledge Mining and Azure AI Search](/training/modules/intro-to-azure-search/) | [Microsoft Azure AI Fundamentals:](/training/paths/document-intelligence-knowledge-mining/) |
+[Fundamentals of Knowledge Mining and Azure AI Search](/training/modules/intro-to-azure-search/) | [Microsoft Azure AI Fundamentals](/training/paths/document-intelligence-knowledge-mining/) |
 | [Create an Azure AI Search solution](/training/modules/create-azure-cognitive-search-solution/) | [Implement knowledge mining](/training/paths/implement-knowledge-mining-azure-cognitive-search/) |
 | [Create a custom skill for Azure AI Search](/training/modules/create-azure-ai-custom-skill/) | [Implement knowledge mining](/training/paths/implement-knowledge-mining-azure-cognitive-search/) |
-| [Build an Azure Machine Learning custom skill for Azure AI Search](/training/modules/build-azure-machine-learn-custom-skill-for-azure-cognitive-search/) | |
 | [Enrich your data with Azure AI Language](/training/modules/enrich-search-index-using-language-studio/) | |
 | [Create a knowledge store with Azure AI Search](/training/modules/create-knowledge-store-azure-cognitive-search/) | [Implement knowledge mining](/training/paths/implement-knowledge-mining-azure-cognitive-search/) |
 | [Implement advanced search features in Azure AI Search](/training/modules/implement-advanced-search-features-azure-cognitive-search/)| [Implement knowledge mining](/training/paths/implement-knowledge-mining-azure-cognitive-search/) |

@@ -12,7 +12,7 @@ ms.custom:
   - build-2024
   - ignite-2024
 ms.topic: conceptual
-ms.date: 02/14/2025
+ms.date: 03/10/2025
 ---
 
 # Upgrade to the latest REST API in Azure AI Search
@@ -24,7 +24,7 @@ Use this article to migrate to newer versions of the [**Search Service REST APIs
 | Data plane | [`2024-07-01`](/rest/api/searchservice/search-service-api-versions#2024-07-01) | Stable |
 | Data plane | [`2024-11-01-preview`](/rest/api/searchservice/search-service-api-versions#2024-11-01-preview) | Preview |
 | Control plane | [`2023-11-01`](/rest/api/searchmanagement/operation-groups?view=rest-searchmanagement-2023-11-0&preserve-view=true1) | Stable |
-| Control plane | [`2024-03-01-preview`](/rest/api/searchmanagement/operation-groups?view=rest-searchmanagement-2024-03-01-preview&preserve-view=true) | Preview |
+| Control plane | [`2025-02-01-preview`](/rest/api/searchmanagement/operation-groups?view=rest-searchmanagement-2025-02-01-preview&preserve-view=true) | Preview |
 
 Upgrade instructions focus on code changes that get you through breaking changes from previous versions so that existing code runs the same as before, but on the newer API version. Once your code is in working order, you can decide whether to adopt newer features. To learn more about new features, see [vector code samples](https://github.com/Azure/azure-search-vector-samples) and [What's New](whats-new.md).
 

@@ -11,7 +11,7 @@ ms.custom:
   - build-2024
   - ignite-2024
 ms.topic: conceptual
-ms.date: 11/05/2024
+ms.date: 03/31/2025
 ---
 
 # Preview features in Azure AI Search
@@ -26,6 +26,9 @@ Preview features are removed from this list if they're retired or transition to
 
 |Feature                          | Category | Description | Availability  |
 |---------|------------------|-------------|---------------|
+| [**flightingOptIn parameter in a semantic configuration**](semantic-how-to-configure.md#opt-in-for-prerelease-semantic-ranking-models) | Queries| You can opt in to use prerelease semantic ranking models if one is available in a search service region. | [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-03-01-preview&preserve-view=true). |
+| [**Rescore vector queries over binary embeddings using full precision vectors**](vector-search-how-to-quantization.md#recommended-rescoring-techniques) | Relevance (scoring) | For vector indexes that contain quantized binary embeddings, you can rescore query results using a full precision query vector. The query engine uses the dot product for rescoring, which improves the quality of search results. Set `enableRescoring` and `discardOriginals` to use this feature.| [Create or Update Index (preview)](/rest/api/searchservice/indexes/create-or-update?view=rest-searchservice-2025-03-01-preview&preserve-view=true). |
+| [**Facet hierarchies, aggregations, and facet filters**](search-faceted-navigation-examples.md) | Queries| New facet query parameters support nested facets. For numeric facetable fields, you can sum the values of each field. You can also specify filters on a facet to add inclusion or exclusion criteria. | [Search Documents (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2025-03-01-preview&preserve-view=true). |
 | [**Query rewrite in the semantic reranker**](semantic-how-to-query-rewrite.md) | Relevance (scoring) | You can set options on a semantic query to rewrite the query input into a revised or expanded query that generates more relevant results from the L2 ranker. | [Search Documents (preview)](/rest/api/searchservice/documents/search-post?view=rest-searchservice-2024-11-01-preview&preserve-view=true).|
 | [**Document Layout skill**](cognitive-search-skill-document-intelligence-layout.md) | Applied AI (skills) | A new skill used to analyze a document for structure and provide [structure-aware chunking](search-how-to-semantic-chunking.md). | [Create or Update Skillset (preview)](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2024-11-01-preview&preserve-view=true). |
 | [**Keyless billing for Azure AI skills processing**](cognitive-search-attach-cognitive-services.md). | Applied AI (skills) | You can now use a managed identity and roles for a keyless connection to Azure AI services for built-in skills processing. This capability removes restrictions for having both search and AI services in the same region.  | [Create or Update Skillset  (preview)](/rest/api/searchservice/skillsets/create-or-update?view=rest-searchservice-2024-11-01-preview&preserve-view=true).|
@@ -57,7 +60,9 @@ Preview features are removed from this list if they're retired or transition to
 
 |Feature                          | Category | Description | Availability  |
 |---------|------------------|-------------|---------------|
-| [**Network security perimeter**](search-security-network-security-perimeter.md) | Service | Join a search service to a [network security perimeter](/azure/private-link/network-security-perimeter-concepts) to control network access to your search service. | The Azure portal and the [Network Security Perimeter APIs 2024-06-01-preview](/rest/api/searchmanagement/network-security-perimeter-configurations?view=rest-searchmanagement-2024-06-01-preview&preserve-view=true). |
+| [**Service upgrade**](search-how-to-upgrade.md) | Feature | Upgrade your search service to higher storage limits in your region. With a one-time upgrade, you no longer need to recreate your service. | The Azure portal and [Upgrade Service (2025-02-01-preview)](/rest/api/searchmanagement/services/upgrade?view=rest-searchmanagement-2025-02-01-preview&preserve-view=true). |
+| [**Pricing tier change**](search-capacity-planning.md#change-your-pricing-tier) | Feature | Change the [pricing tier](search-sku-tier.md) of your search service. This provides flexibility to scale storage, increase request throughput, and decrease latency based on your needs. In this preview, you can only change between Basic and Standard (S1, S2, and S3) tiers. | The Azure portal and [Update Service (2025-02-01-preview)](/rest/api/searchmanagement/services/update?view=rest-searchmanagement-2025-02-01-preview&preserve-view=true#searchupdateservicewithsku). |
+| [**Network security perimeter**](search-security-network-security-perimeter.md) | Service | Join a search service to a [network security perimeter](/azure/private-link/network-security-perimeter-concepts) to control network access to your search service. | The Azure portal and the [Network Security Perimeter APIs 2024-06-01-preview](/rest/api/searchmanagement/network-security-perimeter-configurations?view=rest-searchmanagement-2024-06-01-preview&preserve-view=true) or the latest preview version. |
 | [**Search service under a user-assigned managed identity**](search-howto-managed-identities-data-sources.md) | Service | Configures a search service to use a previously created user-assigned managed identity. | [Services - Update](/rest/api/searchmanagement/services/update?view=rest-searchmanagement-2024-06-01-preview&preserve-view=true#identity), 2021-04-01-preview, or the latest preview version. We recommend using the latest preview version. |
 
 ## Preview features in Azure SDKs
@@ -91,10 +96,10 @@ For data plane operation on content, [**`2024-05-01-preview`**](/rest/api/search
 GET {endpoint}/indexes('{indexName}')?api-version=2024-05-01-Preview
 ```
 
-For management operations on the search service, [**`2024-06-01-preview`**](/rest/api/searchmanagement/services/update?view=rest-searchmanagement-2024-06-01-preview&preserve-view=true) is the most recent preview version. The following example shows the syntax for Update Service 2024-06-01-preview version.
+For management operations on the search service, [**`2025-05-01-preview`**](/rest/api/searchmanagement/services/update?view=rest-searchmanagement-2025-05-01-preview&preserve-view=true) is the most recent preview version. The following example shows the syntax for Update Service 2025-05-01-preview version.
 
 ```rest
-PATCH https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2024-06-01-preview
+PATCH https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01-preview
 
 {
   "tags": {

@@ -11,14 +11,14 @@ ms.custom:
   - ignite-2023
   - ignite-2024
 ms.topic: conceptual
-ms.date: 03/11/2025
+ms.date: 03/31/2025
 ---
 
 # Estimate and manage capacity of a search service
 
 In Azure AI Search, capacity is based on *replicas* and *partitions* that can be scaled to your workload. Replicas are copies of the search engine. Partitions are units of storage. Each new search service starts with one each, but you can add or remove replicas and partitions independently to accommodate fluctuating workloads. Adding capacity increases the [cost of running a search service](search-sku-manage-costs.md#billable-events).
 
-The physical characteristics of replicas and partitions, such as processing speed and disk IO, vary by [service tier](search-sku-tier.md). On a standard search service, the replicas and partitions are faster and larger than those of a basic service.
+The physical characteristics of replicas and partitions, such as processing speed and disk IO, vary by [pricing tier](search-sku-tier.md). On a standard search service, the replicas and partitions are faster and larger than those of a basic service.
 
 Changing capacity isn't instantaneous. It can take up to an hour to commission or decommission partitions, especially on services with large amounts of data.
 
@@ -30,73 +30,121 @@ When scaling a search service, you can choose from the following tools and appro
 + [Management REST API](/rest/api/searchmanagement/services/create-or-update)
 
 > [!NOTE]
-> Higher capacity partitions are available at the same billing rate on newer services created after April and May 2024. For more information, see [Service limits](search-limits-quotas-capacity.md#service-limits) for partition size upgrades.
+> If your service was created before April or May 2024, a one-time upgrade to higher storage limits might be available at no extra cost. For more information, see [Upgrade your search service](search-how-to-upgrade.md).
 
 ## Concepts: search units, replicas, partitions
 
 Capacity is expressed in *search units* that can be allocated in combinations of *partitions* and *replicas*.  
 
 | Concept  | Definition|
 |----------|-----------|
-|*Search unit* | A single increment of total available capacity (36 units). A minimum of one unit is required to run the service. The first replica and partition pair is the first search unit. However, each extra instance of a replica *or* a partition consumes an extra search unit. For example, you start with one replica and partition (one search unit), add a second replica, you are now consuming two search units. A search unit is also the billing unit for an Azure AI Search service. |
+|*Search unit* | A single increment of total available capacity (36 units). A minimum of one unit is required to run the service. The first replica and partition pair is the first search unit. However, each extra instance of a replica *or* a partition consumes an extra search unit. For example, you start with one replica and partition (one search unit), add a second replica, you're now consuming two search units. A search unit is also the billing unit for an Azure AI Search service. |
 |*Replica* | Instances of the search service, used primarily to load balance query operations. Each replica hosts one copy of an index. If you allocate three replicas, you have three copies of an index available for servicing query requests.|
 |*Partition* | Physical storage and I/O for read/write operations (for example, when rebuilding or refreshing an index). Each partition has a slice of the total index. If you allocate three partitions, your index is divided into thirds. |
 
-Review the [partitions and replicas table](#partition-and-replica-combinations) for possible combinations that stay under the 36 unit limit. 
+Review the [partitions and replicas table](#partition-and-replica-combinations) for possible combinations that stay under the 36 unit limit.
 
 ## When to add capacity
 
-Initially, a service is allocated a minimal level of resources consisting of one partition and one replica. The [tier you choose](search-sku-tier.md) determines partition size and speed, and each tier is optimized around a set of characteristics that fit various scenarios. If you choose a higher-end tier, you might [need fewer partitions](search-performance-tips.md#service-capacity) than if you go with S1. One of the questions you'll need to answer through self-directed testing is whether a larger and more expensive partition yields better performance than two cheaper partitions on a service provisioned at a lower tier.
+Initially, a service is allocated a minimal level of resources consisting of one partition and one replica. The [tier you choose](search-sku-tier.md) determines partition size and speed, and each tier is optimized around a set of characteristics that fit various scenarios. If you choose a higher-end tier, you might [need fewer partitions](search-performance-tips.md#service-capacity) than if you go with S1. One of the questions you need to answer through self-directed testing is whether a larger and more expensive partition yields better performance than two cheaper partitions on a service provisioned at a lower tier.
 
-A single service must have sufficient resources to handle all workloads (indexing and queries). Neither workload runs in the background. You can schedule indexing for times when query requests are naturally less frequent, but the service won't otherwise prioritize one task over another. Additionally, a certain amount of redundancy smooths out query performance when services or nodes are updated internally.
+A single service must have sufficient resources to handle all workloads (indexing and queries). Neither workload runs in the background. You can schedule indexing for times when query requests are naturally less frequent, but the service doesn't otherwise prioritize one task over another. Additionally, a certain amount of redundancy smooths out query performance when services or nodes are updated internally.
 
-Some guidelines for determining whether to add capacity include:
+Guidelines for determining whether to add capacity include:
 
-+ Meeting the high availability criteria for service level agreement
-+ The frequency of HTTP 503 errors is increasing
-+ Large query volumes are expected
++ Meeting the high availability criteria for service-level agreement.
++ The frequency of HTTP 503 errors is increasing.
++ Large query volumes are expected.
++ A [one-time upgrade](#how-to-upgrade-capacity) to newer infrastructure and larger partitions isn’t sufficient.
++ The current number of partitions isn’t adequate for indexing workloads.
 
-As a general rule, search applications tend to need more replicas than partitions, particularly when the service operations are biased toward query workloads. Each replica is a copy of your index, allowing the service to load balance requests against multiple copies. All load balancing and replication of an index is managed by Azure AI Search and you can alter the number of replicas allocated for your service at any time. You can allocate up to 12 replicas in a Standard search service and 3 replicas in a Basic search service. Replica allocation can be made either from the [Azure portal](search-create-service-portal.md) or one of the programmatic options.
+As a general rule, search applications tend to need more replicas than partitions, particularly when the service operations are biased toward query workloads. Each replica is a copy of your index, allowing the service to load balance requests against multiple copies. Azure AI Search manages all load balancing and replication of an index, and you can alter the number of replicas allocated for your service at any time. You can allocate up to 12 replicas in a Standard search service and 3 replicas in a Basic search service. Replica allocation can be made either from the [Azure portal](search-create-service-portal.md) or one of the programmatic options.
 
 Extra partitions are helpful for intensive indexing workloads. Extra partitions spread read/write operations across a larger number of compute resources.
 
-Finally, larger indexes take longer to query. As such, you might find that every incremental increase in partitions requires a smaller but proportional increase in replicas. The complexity of your queries and query volume will factor into how quickly query execution is turned around.
+Finally, larger indexes take longer to query. As such, you might find that every incremental increase in partitions requires a smaller but proportional increase in replicas. The complexity of your queries and query volume factors into how quickly query execution is turned around.
 
 > [!NOTE]
-> Adding more replicas or partitions increases the cost of running the service, and can introduce slight variations in how results are ordered. Be sure to check the [pricing calculator](https://azure.microsoft.com/pricing/calculator/) to understand the billing implications of adding more nodes. The [chart below](#chart) can help you cross-reference the number of search units required for a specific configuration. For more information on how additional replicas impact query processing, see [Ordering results](search-pagination-page-layout.md#ordering-results).
+> Adding more replicas or partitions increases the cost of running the service, and can introduce slight variations in how results are ordered. Be sure to check the [pricing calculator](https://azure.microsoft.com/pricing/calculator/) to understand the billing implications of adding more nodes. The [chart below](#chart) can help you cross-reference the number of search units required for a specific configuration. For more information on how extra replicas affect query processing, see [Ordering results](search-pagination-page-layout.md#ordering-results).
 
 <a name="adjust-capacity"></a>
 
+## How to upgrade capacity
+
+Some Azure AI Search capabilities are only available to new services. One such capability is higher storage capacity, which applies to [services created after April 2024](search-limits-quotas-capacity.md#service-limits). However, if you created your service before April 2024, you can get higher capacity without recreating your service by performing a one-time upgrade. For more information, see [Upgrade your search service](search-how-to-upgrade.md).
+
 ## How to change capacity
 
-To increase or decrease the capacity of your search service, add or remove partitions and replicas.
+To increase or decrease the capacity of your service, you have two options:
+
++ [Add or remove partitions and replicas](#add-or-remove-partitions-and-replicas)
++ [Change your pricing tier](#change-your-pricing-tier)
 
-1. Sign in to the [Azure portal](https://portal.azure.com/) and select the search service.
+### Add or remove partitions and replicas
 
-1. Under **Settings**, open the **Scale** page to modify replicas and partitions. 
+1. Sign in to the [Azure portal](https://portal.azure.com/) and select your search service.
+
+1. From the left pane, select **Settings** > **Scale**.
 
    The following screenshot shows a Standard service provisioned with one replica and partition. The formula at the bottom indicates how many search units are being used (1). If the unit price was $100 (not a real price), the monthly cost of running this service would be $100 on average.
 
-   :::image type="content" source="media/search-capacity-planning/1-initial-values.png" alt-text="Scale page showing current values" border="true":::
+   :::image type="content" source="media/search-capacity-planning/initial-values.png" alt-text="Screenshot of the Scale page showing the current replica and partition values." border="true":::
 
 1. Use the slider to increase or decrease the number of partitions. Select **Save**.
 
    This example adds a second replica and partition. Notice the search unit count; it's now four because the billing formula is replicas multiplied by partitions (2 x 2). Doubling capacity more than doubles the cost of running the service. If the search unit cost was $100, the new monthly bill would now be $400.
 
-   For the current per unit costs of each tier, visit the [Pricing page](https://azure.microsoft.com/pricing/details/search/).
+   For the current per unit costs of each tier, visit the [pricing page](https://azure.microsoft.com/pricing/details/search/).
+
+   :::image type="content" source="media/search-capacity-planning/add-two-each.png" alt-text="Screenshot of the Scale page with added replicas and partitions." border="true":::
 
-   :::image type="content" source="media/search-capacity-planning/2-add-2-each.png" alt-text="Add replicas and partitions" border="true":::
+1. Check your notifications to confirm that the operation started.
 
-1. After saving, you can check notifications to confirm the action succeeded.
+   :::image type="content" source="media/search-capacity-planning/portal-notifications.png" alt-text="Screenshot of the notification of the scaling operation in the Azure portal." border="true":::
 
-   :::image type="content" source="media/search-capacity-planning/3-save-confirm.png" alt-text="Save changes" border="true":::
+   This operation can take several hours to complete. You can’t cancel the process after it starts, and there’s no real-time monitoring of replica and partition adjustments. However, the following message displays while changes are underway.
 
-   Changes in capacity can take anywhere from 15 minutes up to several hours to complete. You can't cancel once the process has started and there's no real-time monitoring for replica and partition adjustments. However, the following message remains visible while changes are underway.
+   :::image type="content" source="media/search-capacity-planning/updating-message.png" alt-text="Screenshot of the Updating message in the Azure portal." border="true":::
 
-   :::image type="content" source="media/search-capacity-planning/4-updating.png" alt-text="Status message in the Azure portal" border="true":::
+### Change your pricing tier
 
 > [!NOTE]
-> After a service is provisioned, it cannot be upgraded to a higher tier. You must create a search service at the new tier and reload your indexes. See [Create an Azure AI Search service in the Azure portal](search-create-service-portal.md) for help with service provisioning.
+> The 2025-02-01-preview supports changes between Basic and Standard (S1, S2, and S3) tiers. Currently, you can only switch from a lower tier to a higher tier, such as going from Basic to S1. Your region also can't have [capacity constraints on the higher tier](search-region-support.md).
+
+Your [pricing tier](search-sku-tier.md) determines the maximum storage of your search service. If you need more <!-- or less capacity -->capacity, you can switch to a different pricing tier that accommodates your storage needs.
+
+In addition to capacity, changing your pricing tier affects the workload and maximum limits of your service. Before you proceed, compare the [service limits](search-limits-quotas-capacity.md) of your current tier and your desired tier. These include limits on:
+
++ Partition storage
++ Indexes
++ Vectors
++ Indexers
++ Shared private link resources
++ Synonyms
++ Index aliases
++ Semantic ranker throttling
+
+Generally, switching to a higher tier increases your [storage limit](search-limits-quotas-capacity.md#service-limits) and [vector limit](search-limits-quotas-capacity.md#vector-index-size-limits), increases request throughput, and decreases latency<!-- , while switching to a lower tier decreases your storage limit and vector limit, decreases request throughput, and increases latency -->.
+
+To change your pricing tier:
+
+1. Sign in to the [Azure portal](https://portal.azure.com/) and select your search service.
+
+1. From the left pane, select **Settings** > **Scale**.
+
+1. Under your current tier, select **Change Pricing Tier**.
+
+   :::image type="content" source="media/search-capacity-planning/change-pricing-tier.png" alt-text="Screenshot of the Change Pricing Tier button in the Azure portal." border="true":::
+
+1. On the **Select Pricing Tier** page, choose a higher tier from the list. Currently, you can only move up between Basic, S1, S2, and S3. Other pricing tiers are unavailable and appear dimmed.
+
+1. To switch to the higher tier, select **Select**.
+
+   :::image type="content" source="media/search-capacity-planning/pricing-tier-list.png" alt-text="Screenshot of the Select Pricing Tier page and the list of higher tiers in the Azure portal." border="true":::
+
+   This operation can take several hours to complete. You can’t cancel the process after it starts, and there’s no real-time monitoring of tier changes. However, on the **Overview** page, a **Provisioning** status indicates the operation is underway for your service.
+
+   :::image type="content" source="media/search-capacity-planning/provisioning-status.png" alt-text="Screenshot of the service Overview page with a Provisioning status." border="true":::
 
 ## How scale requests are handled
 
@@ -143,25 +191,25 @@ The following chart applies to Standard tier and higher. It shows all possible c
 
 Basic search services have lower search unit counts.
 
-+ On search services created before April 3, 2024, a basic search service can have exactly one partition and up to three replicas, for a maximum limit of three SUs. The only adjustable resource is replicas. 
++ On search services created before April 3, 2024, Basic services can have exactly one partition and up to three replicas for a maximum limit of three SUs. The only adjustable resource is replicas. However, you might be able to increase your partition count by [upgrading your service](search-how-to-upgrade.md).
 
-+ On search services created after April 3, 2024 in [supported regions](search-limits-quotas-capacity.md#service-limits), basic services can have up to three partitions and three replicas. The maximum SU limit is nine to support a full complement of partitions and replicas.
++ On search services created after April 3, 2024 in [supported regions](search-limits-quotas-capacity.md#service-limits), Basic services can have up to three partitions and three replicas. The maximum SU limit is nine to support a full complement of partitions and replicas.
 
 For search services on any billable tier, regardless of creation date, you need a minimum of two replicas for high availability on queries.
 
 For billing rates per tier and currency, see the [Azure AI Search pricing page](https://azure.microsoft.com/pricing/details/search/).
 
 ## Estimate capacity using a billable tier
 
-Storage needs are determined by the size of the indexes you expect to build. There are no solid heuristics or generalities that help with estimates. The only way to determine the size of an index is [build one](search-what-is-an-index.md). Its size is based on tokenization and embeddings, and whether you enable suggesters, filtering, and sorting, or can take advantage of [vector compression](vector-search-how-to-quantization.md).
+The size of the indexes you expect to build determines storage needs. There are no solid heuristics or generalities that help with estimates. The only way to determine the size of an index is [build one](search-what-is-an-index.md). Its size is based on tokenization and embeddings, and whether you enable suggesters, filtering, and sorting, or can take advantage of [vector compression](vector-search-how-to-quantization.md).
 
 We recommend estimating on a billable tier, Basic or above. The Free tier runs on physical resources shared by multiple customers and is subject to factors beyond your control. Only the dedicated resources of a billable search service can accommodate larger sampling and processing times for more realistic estimates of index quantity, size, and query volumes during development. 
 
 1. [Review service limits at each tier](search-limits-quotas-capacity.md#service-limits) to determine whether lower tiers can support the number of indexes you need. Consider whether you need multiple copies of an index for active development, testing, and production. 
 
    A search service is subject to object limits (maximum number of indexes, indexers, skillsets, etc.) and storage limits. Whichever limit is reached first is the effective limit. 
 
-1. [Create a service at a billable tier](search-create-service-portal.md). Tiers are optimized for certain workloads. For example, Storage Optimized tier has a limit of 10 indexes because it's designed to support a low number of very large indexes.
+1. [Create a service at a billable tier](search-create-service-portal.md). Tiers are optimized for certain workloads. For example, the Storage Optimized tier has a limit of 10 indexes because it's designed to support a low number of large indexes.
 
     + Start low, at Basic or S1, if you're not sure about the projected load.
 
@@ -187,11 +235,11 @@ Storage requirements can be inflated if you include data that will never be sear
 
 ## Service-level agreement considerations
 
-The Free tier and preview features aren't covered by [service-level agreements (SLAs)](https://azure.microsoft.com/support/legal/sla/search/v1_0/). For all billable tiers, SLAs take effect when you provision sufficient redundancy for your service. 
+The Free tier and preview features aren't covered by [service-level agreements (SLAs)](https://azure.microsoft.com/support/legal/sla/search/v1_0/). For all billable tiers, SLAs take effect when you provision sufficient redundancy for your service.
 
-+ Two or more replicas satisfy query (read) SLAs. 
++ Two or more replicas satisfy query (read) SLAs.
 
-+ Three or more replicas satisfy query and indexing (read-write) SLAs. 
++ Three or more replicas satisfy query and indexing (read-write) SLAs.
 
 The number of partitions doesn't affect SLAs.
 

@@ -11,7 +11,7 @@ ms.custom:
   - references_regions
   - build-2024
 ms.topic: how-to
-ms.date: 02/20/2025
+ms.date: 03/21/2025
 ---
 
 # Create an Azure AI Search service in the Azure portal
@@ -33,13 +33,13 @@ You can also use:
 
 ## Before you start
 
-Some properties are fixed for the lifetime of the search service. Before creating your service, decide on the following properties:
+Some properties are fixed for the lifetime of the search service. Before you create your service, decide on the following properties:
 
 | Property | Description |
 |--|--|
 | [Name](#name-your-service) | Becomes part of the URL endpoint. The name must be unique and follow naming rules. |
 | [Region](search-region-support.md) | Determines data residency and availability of certain features. For example, semantic ranker and Azure AI integration have region requirements. Choose a region that supports the features you need. |
-| [Tier](search-sku-tier.md) | Determines infrastructure, service limits, and billing. Some features aren't available on lower or specialized tiers. |
+| [Tier](search-sku-tier.md) | Determines infrastructure, service limits, and billing. Some features aren't available on lower or specialized tiers. In the 2025-02-01-preview, you can also [switch from a lower tier to a higher tier](search-capacity-planning.md#change-your-pricing-tier). |
 
 ## Subscribe to Azure
 
@@ -131,7 +131,7 @@ Currently, the following regions offer cross-regional availability for Azure AI
 + Americas: West US, East US
 + Europe: Switzerland North, Sweden Central
 
-This list isn't definitive, and depending on your tier, you might have more choices. Region status can also change quickly, so confirm your region choice before creating your search service.
+This list isn't definitive, and depending on your tier, you might have more choices. Region status can also change quickly, so confirm your region choice before you create your search service.
 
 ## Choose a tier
 
@@ -149,8 +149,8 @@ The Basic and Standard tiers are the most common for production workloads, but m
 :::image type="content" source="media/search-create-service-portal/select-pricing-tier.png" lightbox="media/search-create-service-portal/select-pricing-tier.png" alt-text="Screenshot of the Select Pricing Tier page in the Azure portal." border="true":::
 
 > [!NOTE]
-> + You can't change the tier after creating your search service, so choose carefully.
-> + Search services created after April 3, 2024 have larger partitions and higher vector quotas at every billable tier.
+> + After you create your service, you can move up between Basic and Standard (S1, S2, and S3) tiers. Switching to a lower tier isn't currently supported. For more information, see [Change your pricing tier](search-capacity-planning.md#change-your-pricing-tier).
+> + Services created after April 3, 2024 have larger partitions and higher vector quotas at every billable tier.
 
 ## Create your service
 

@@ -0,0 +1,721 @@
+---
+
+title: Faceted navigation examples
+titleSuffix: Azure AI Search
+description: Examples that demonstrate query syntax for facet hierarchies, distinct counts, facet aggregations, and facet filters.
+
+manager: nitinme
+author: HeidiSteen
+ms.author: heidist
+ms.service: azure-ai-search
+ms.topic: how-to
+ms.date: 04/04/2025
+---
+
+# Faceted navigation examples
+
+This section extends [faceted navigation configuration](search-faceted-navigation.md) with examples that demonstrate basic usage and other scenarios.
+
+Facetable fields are defined in an index, but facet parameters and expressions are defined in query requests. If you have an index with facetable fields, you can try new preview features like [facet hierarchies](#facet-hierarchy-example), [facet aggregations](#facet-aggregation-example), and [facet filters](#facet-filtering-example) on existing indexes.
+
+## Facet parameters and syntax
+
+Depending on the API, a facet query is usually an array of facet expressions that are applied to search results. Each facet expression contains a facetable field name, optionally followed by a comma-separated list of name-value pairs.
+
++ *facet query* is a query request that includes a facet property.
++ *facetable field* is a field definition in the search index attributed with the `facetable` property.
++ *count* is the number of matches for each facet found in the search results.
+
+The following table describes facet parameters used in the examples.
+
+| Facet parameter | Description | Usage | Example |
+|-----------------|-------------|-------|---------|
+| `count` | Maximum number of facet terms per structure.| Integer. Default is 10. There's no upper limit, but higher values degrade performance, especially if the faceted field contains a large number of unique terms. This is due to the way facet queries are distributed across shards. You can set `count` to zero or to a value that's greater than or equal to the number of unique values in the facetable field to get an accurate count across all shards. The tradeoff is increased latency. | `Tags,count:5` limits the faceted navigation response to 5 facet buckets that containing the most facet counts, but they can be in any order. |
+| `sort` | Determines order of facet buckets. | Valid values are `count`, `-count`, `value`, `-value`. Use `count` to list facets from greatest to smallest. Use `-count` to sort in ascending order (smallest to greatest). Use `value` to sort alphanumerically by facet value in ascending order. Use `-value` to sort descending by value. | `"facet=Category,count:3,sort:count"` gets the top three facet buckets in search results, listed in descending order by the number of matches in each Category. If the top three categories are Budget, Extended-Stay, and Luxury, and Budget has 5 hits, Extended-Stay has 6, and Luxury has 4, then the facet buckets are ordered as Extended-Stay, Budget, Luxury. Another example is`"facet=Rating,sort:-value"`. It produces facets for all possible ratings, in descending order by value. If ratings are from 1 to 5, the facets are ordered 5, 4, 3, 2, 1, irrespective of how many documents match each rating. |
+| `values` | Provides values for facet labels. | Set to pipe-delimited numeric or `Edm.DateTimeOffset` values specifying a dynamic set of facet entry values. The values must be listed in sequential, ascending order to get the expected results. | `"facet=baseRate,values:10 | 20"` produces three facet buckets: one for base rate 0 up to but not including 10, one for 10 up to but not including 20, and one for 20 and higher. A string `"facet=lastRenovationDate,values:2024-02-01T00:00:00Z"` produces two facet buckets: one for hotels renovated before February 2024, and one for hotels renovated February 1, 2024 or later. |
+| `interval` | Provides an interval sequence for facets that can be grouped into intervals. | An integer interval greater than zero for numbers, or minute, hour, day, week, month, quarter, year for date time values. | `"facet=baseRate,interval:100"` produces facet buckets based on base rate ranges of size 100. If base rates are all between $60 and $600, there are facet buckets for 0-100, 100-200, 200-300, 300-400, 400-500, and 500-600. The string `"facet=lastRenovationDate,interval:year"` produces one facet bucket for each year a hotel was renovated. |
+| `timeoffset` | Specifies the UTC time offset to account for in setting time boundaries. | Set to (`[+-]hh:mm, [+-]hhmm, or [+-]hh`). If used, the `timeoffset` parameter must be combined with the interval option, and only when applied to a field of type `Edm.DateTimeOffset`. | `"facet=lastRenovationDate,interval:day,timeoffset:-01:00"` uses the day boundary that starts at 01:00:00 UTC (midnight in the target time zone). |
+
+`count` and `sort` can be combined in the same facet specification, but they can't be combined with `interval` or `values`.
+
+`interval` and `values` can't be combined together.
+
+Interval facets on date time are computed based on the UTC time if `timeoffset` isn't specified. For example, for `"facet=lastRenovationDate,interval:day"`, the day boundary starts at 00:00:00 UTC.
+
+## Basic facet example
+
+The following facet queries work against the [hotels sample index](search-get-started-portal.md). You can use **JSON view** in Search Explorer to paste in the JSON query. For help with getting started, see [Add faceted navigation to search results](search-faceted-navigation.md).
+
+This first query retrieves facets for Categories, Ratings, Tags, and rooms with baseRate values in specific ranges. Notice the last facet is on a subfield of the Rooms collection. Facets count the parent document (Hotels) and not intermediate subdocuments (Rooms), so the response determines the number of *hotels* that have any rooms in each pricing category.
+
+```rest
+POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-01-Preview
+{  
+  "search": "ocean view",  
+  "facets": [ "Category", "Rating", "Tags", "Rooms/BaseRate,values:80|150|220" ],
+  "count": true 
+}  
+```
+
+This second example uses a filter to narrow down the previous faceted query result after the user selects Rating 3 and category "Motel".
+
+```rest
+POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-01-Preview
+{  
+  "search": "water view",  
+  "facets": [ "Tags", "Rooms/BaseRate,values:80|150|220" ],
+  "filter": "Rating eq 3 and Category eq 'Motel'",
+  "count": true  
+} 
+```
+
+The third example sets an upper limit on unique terms returned in a query. The default is 10, but you can increase or decrease this value using the count parameter on the facet attribute. This example returns facets for city, limited to 5.
+
+```rest
+POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-01-Preview
+{  
+  "search": "view",  
+  "facets": [ "Address/City,count:5" ],
+  "count": true
+} 
+```
+
+This example shows three facets for "Category", "Tags", and "Rating", with a count override on "Tags" and a range override for "Rating", which is otherwise stored as a double in the index.
+
+```http
+POST https://{{service_name}}.search.windows.net/indexes/hotels/docs/search?api-version={{api_version}}
+{
+    "search": "*",
+    "facets": [ 
+        "Category", 
+        "Tags,count:5", 
+        "Rating,values:1|2|3|4|5"
+    ],
+    "count": true
+}
+```
+
+For each faceted navigation tree, there's a default limit of the top 10 facet instances found by the query. This default makes sense for navigation structures because it keeps the values list to a manageable size. You can override the default by assigning a value to "count". For example, `"Tags,count:5"` reduces the number of tags under the Tags section to the top five.
+
+For Numeric and DateTime values only, you can explicitly set values on the facet field (for example, `facet=Rating,values:1|2|3|4|5`) to separate results into contiguous ranges (either ranges based on numeric values or time periods). Alternatively, you can add "interval", as in `facet=Rating,interval:1`. 
+
+Each range is built using 0 as a starting point, a value from the list as an endpoint, and then trimmed of the previous range to create discrete intervals.
+
+## Distinct values example
+
+You can formulate a query that returns a distinct value count for each facetable field. This example formulates an empty or unqualified query (`"search": "*"`) that matches on all documents, but by setting `top` to zero, you get just the counts, with no results.
+
+For brevity, this query includes just two fields marked as `facetable` in the hotels sample index.
+
+```http
+POST https://{{service_name}}.search.windows.net/indexes/hotels/docs/search?api-version={{api_version}}
+{
+    "search": "*",
+    "count": true,
+    "top": 0,
+    "facets": [ 
+        "Category", "Address/StateProvince""
+    ]
+}
+```
+
+Results from this query are as follows:
+
+```json
+{
+  "@odata.count": 50,
+  "@search.facets": {
+    "Address/StateProvince": [
+      {
+        "count": 9,
+        "value": "WA"
+      },
+      {
+        "count": 6,
+        "value": "CA "
+      },
+      {
+        "count": 4,
+        "value": "FL"
+      },
+      {
+        "count": 3,
+        "value": "NY"
+      },
+      {
+        "count": 3,
+        "value": "OR"
+      },
+      {
+        "count": 3,
+        "value": "TX"
+      },
+      {
+        "count": 2,
+        "value": "GA"
+      },
+      {
+        "count": 2,
+        "value": "MA"
+      },
+      {
+        "count": 2,
+        "value": "TN"
+      },
+      {
+        "count": 1,
+        "value": "AZ"
+      }
+    ],
+    "Category": [
+      {
+        "count": 13,
+        "value": "Budget"
+      },
+      {
+        "count": 12,
+        "value": "Suite"
+      },
+      {
+        "count": 7,
+        "value": "Boutique"
+      },
+      {
+        "count": 7,
+        "value": "Resort and Spa"
+      },
+      {
+        "count": 6,
+        "value": "Extended-Stay"
+      },
+      {
+        "count": 5,
+        "value": "Luxury"
+      }
+    ]
+  },
+  "value": []
+}
+```
+
+## Facet hierarchy example
+
+[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
+
+Starting in [2025-03-01-preview REST API](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-03-01-preview&preserve-view=true) and available in the Azure portal, you can configure a facet hierarchy using the `>` and `;` operators.
+
+The nesting (hierarchical) operator `>` denotes a parent–child relationship, and the semicolon operator `;` denotes multiple fields at the same nesting level, which are all children of the same parent. The parent must contain only one field. Both the parent and child fields must be `facetable`. 
+
+The order of operations in a facet expression that includes facet hierarchies are:
+
+* options operator (comma `,`) that separates facet parameters for the facet field, such as the comma in `Rooms/BaseRate,values`
+* parentheses, such as the ones enclosing `(Rooms/BaseRate,values:50 ; Rooms/Type)`.
+* nesting operator (angled bracket `>`)
+* append operator (semicolon `;`), demonstrated in a second example `"Tags>(Rooms/BaseRate,values:50 ; Rooms/Type)"` in this section, where two child facets are peers under the Tags parent.
+
+There are several examples for facet hierarchies. The first example is a query that returns just a few documents, which is helpful for viewing a full response. Facets count the parent document (Hotels) and not intermediate subdocuments (Rooms), so the response determines the number of *hotels* that have any rooms in each facet bucket.
+
+```rest
+POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-01-Preview
+{
+  "search": "ocean",  
+  "facets": ["Address/StateProvince>Address/City", "Tags>Rooms/BaseRate,values:50"],
+  "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
+  "count": true 
+}
+```
+
+Results from this query are as follows. Both hotels have pools. For other tags, only one hotel provides the amenity.
+
+```json
+{
+  "@odata.count": 2,
+  "@search.facets": {
+    "Tags": [
+      {
+        "value": "pool",
+        "count": 2,
+        "@search.facets": {
+          "Rooms/BaseRate": [
+            {
+              "to": 50,
+              "count": 0
+            },
+            {
+              "from": 50,
+              "count": 2
+            }
+          ]
+        }
+      },
+      {
+        "value": "air conditioning",
+        "count": 1,
+        "@search.facets": {
+          "Rooms/BaseRate": [
+            {
+              "to": 50,
+              "count": 0
+            },
+            {
+              "from": 50,
+              "count": 1
+            }
+          ]
+        }
+      },
+      {
+        "value": "bar",
+        "count": 1,
+        "@search.facets": {
+          "Rooms/BaseRate": [
+            {
+              "to": 50,
+              "count": 0
+            },
+            {
+              "from": 50,
+              "count": 1
+            }
+          ]
+        }
+      },
+      {
+        "value": "restaurant",
+        "count": 1,
+        "@search.facets": {
+          "Rooms/BaseRate": [
+            {
+              "to": 50,
+              "count": 0
+            },
+            {
+              "from": 50,
+              "count": 1
+            }
+          ]
+        }
+      },
+      {
+        "value": "view",
+        "count": 1,
+        "@search.facets": {
+          "Rooms/BaseRate": [
+            {
+              "to": 50,
+              "count": 0
+            },
+            {
+              "from": 50,
+              "count": 1
+            }
+          ]
+        }
+      }
+    ],
+    "Address/StateProvince": [
+      {
+        "value": "FL",
+        "count": 1,
+        "@search.facets": {
+          "Address/City": [
+            {
+              "value": "Tampa",
+              "count": 1
+            }
+          ]
+        }
+      },
+      {
+        "value": "HI",
+        "count": 1,
+        "@search.facets": {
+          "Address/City": [
+            {
+              "value": "Honolulu",
+              "count": 1
+            }
+          ]
+        }
+      }
+    ]
+  },
+  "value": [
+    {
+      "@search.score": 1.6076145,
+      "HotelName": "Ocean Water Resort & Spa",
+      "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
+      "Tags": [
+        "view",
+        "pool",
+        "restaurant"
+      ],
+      "Address": {
+        "City": "Tampa",
+        "StateProvince": "FL"
+      }
+    },
+    {
+      "@search.score": 1.0594962,
+      "HotelName": "Windy Ocean Motel",
+      "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
+      "Tags": [
+        "pool",
+        "air conditioning",
+        "bar"
+      ],
+      "Address": {
+        "City": "Honolulu",
+        "StateProvince": "HI"
+      }
+    }
+  ]
+}
+```
+
+This second example extends the previous one, demonstrating multiple top-level facets with multiple children. Notice the semicolon (`;`) operator separates each child.
+
+```rest
+POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-01-Preview
+{  
+  "search": "+ocean",  
+  "facets": ["Address/StateProvince > Address/City", "Tags > (Rooms/BaseRate,values:50 ; Rooms/Type)"],
+  "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
+  "count": true 
+}  
+```
+
+A partial response, trimmed for brevity, shows Tags with child facets for the rooms base rate and type. In the hotels sample index, both hotels that match to `+ocean` have rooms in each type and a pool.
+
+```json
+{
+  "@odata.count": 2,
+  "@search.facets": {
+    "Tags": [
+      {
+        "value": "pool",
+        "count": 2,
+        "@search.facets": {
+          "Rooms/BaseRate": [
+            {
+              "to": 50,
+              "count": 0
+            },
+            {
+              "from": 50,
+              "count": 2
+            }
+          ],
+          "Rooms/Type": [
+            {
+              "value": "Budget Room",
+              "count": 2
+            },
+            {
+              "value": "Deluxe Room",
+              "count": 2
+            },
+            {
+              "value": "Standard Room",
+              "count": 2
+            },
+            {
+              "value": "Suite",
+              "count": 2
+            }
+          ]
+        }}]},
+  ...
+}
+```
+
+This last example shows precedence rules for parentheses that affects nesting levels. Suppose you want to return a facet hierarchy in this order.
+
+```
+Address/StateProvince
+  Address/City
+    Category
+    Rating
+```
+
+To return this hierarchy, create a query where Category and Rating are siblings under Address/City.
+
+```json
+  { 
+    "search": "beach",  
+    "facets": [
+        "Address/StateProvince > (Address/City > (Category ; Rating))"
+        ],
+    "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
+    "count": true 
+  }
+```
+
+If you remove the innermost parentheses, Category and Rating are no longer siblings because the precedence rules mean that the `>` operator is evaluated before `;`.
+
+```json
+  { 
+    "search": "beach",  
+    "facets": [
+        "Address/StateProvince > (Address/City > Category ; Rating)"
+        ],
+    "select": "HotelName, Description, Tags, Address/StateProvince, Address/City",
+    "count": true 
+  }
+```
+
+The top-level parent is still Address/StateProvince, but now Address/City and Rating are on same level.
+
+```
+Address/StateProvince
+  Rating
+  Address/City
+    Category
+```
+
+## Facet filtering example
+
+[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
+
+Starting in [2025-03-01-preview REST API](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-03-01-preview&preserve-view=true) and available in the Azure portal, you can configure facet filters.
+
+Facet filtering enables you to constrain the facet values returned to those matching a specified regular expression. Two new parameters accept a regular expression that is applied to the facet field:
+
+* `includeTermFilter` filters the facet values to those that match the regular expression
+* `excludeTermFilter` filters the facet values to those that don't match the regular expression 
+
+If a facet string satisfies both conditions, the `excludeTermFilter` takes precedence because the set of bucket strings is first evaluated with `includeTermFilter` and then excluded with `excludeTermFilter`.
+
+Only those facet values that match the regular expression are returned. You can combine these parameters with other facet options (for example, `count`, `sort`, and [hierarchical faceting](#facet-hierarchy-example)) on string fields.
+
+Because the regular expression is nested within a JSON string value, you must escape both the double quote (`"`) and the backslash (`\`) characters. The regular expression itself is delimited by the forward slash (`/`). For more information about escape patterns, see [Regular expression search](query-lucene-syntax.md#bkmk_regex).
+
+The following example shows how to escape special characters in your regular expression such as backslash, double quotes, or regular expression syntax characters. 
+
+```json
+{
+    "search": "*", 
+    "facets": ["name,includeTermFilter:/EscapeBackslash\\\OrDoubleQuote\\"OrRegexCharacter\\(/"] 
+}
+```
+
+Here's an example of a facet filter that matches on Budget and Extended-Stay hotels, with Rating as a child of each hotel category.
+
+```http
+POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-01-Preview
+{ 
+    "search": "*", 
+    "facets": ["(Category,includeTermFilter:/(Budget|Extended-Stay)/)>Rating,values:1|2|3|4|5"],
+    "select": "HotelName, Category, Rating",
+    "count": true 
+} 
+```
+
+The following example is an abbreviated response (hotel documents are omitted for brevity).
+
+```json
+{
+  "@odata.count": 50,
+  "@search.facets": {
+    "Category": [
+      {
+        "value": "Budget",
+        "count": 13,
+        "@search.facets": {
+          "Rating": [
+            {
+              "to": 1,
+              "count": 0
+            },
+            {
+              "from": 1,
+              "to": 2,
+              "count": 0
+            },
+            {
+              "from": 2,
+              "to": 3,
+              "count": 4
+            },
+            {
+              "from": 3,
+              "to": 4,
+              "count": 5
+            },
+            {
+              "from": 4,
+              "to": 5,
+              "count": 4
+            },
+            {
+              "from": 5,
+              "count": 0
+            }
+          ]
+        }
+      },
+      {
+        "value": "Extended-Stay",
+        "count": 6,
+        "@search.facets": {
+          "Rating": [
+            {
+              "to": 1,
+              "count": 0
+            },
+            {
+              "from": 1,
+              "to": 2,
+              "count": 0
+            },
+            {
+              "from": 2,
+              "to": 3,
+              "count": 4
+            },
+            {
+              "from": 3,
+              "to": 4,
+              "count": 1
+            },
+            {
+              "from": 4,
+              "to": 5,
+              "count": 1
+            },
+            {
+              "from": 5,
+              "count": 0
+            }
+          ]
+        }
+      }
+    ]
+  }, 
+  "value": [  ALL 50 HOTELS APPEAR HERE ]
+}
+```
+
+## Facet aggregation example
+
+[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
+
+Starting in [2025-03-01-preview REST API](/rest/api/searchservice/operation-groups?view=rest-searchservice-2025-03-01-preview&preserve-view=true) and available in the Azure portal, you can aggregate facets.
+
+Facet aggregations allow you to compute metrics from facet values. The aggregation capability works alongside the existing faceting options. The only supported metric is `sum`. Adding `metric: sum` to a numeric facet aggregates all the values of each bucket. 
+
+You can add a default value to use if a document contains a null for that field: `"facets": [ "Rooms/SleepsCount, metric: sum, default:2"]`. If a room has a null value for the Rooms/SleepsCount field, the default substitutes for the missing value.
+
+You can sum any facetable field of a numeric data type (except vectors and geographic coordinates). 
+
+Here's an example using the hotels-sample-index. The Rooms/SleepsCount field is facetable and numeric, so we choose this field to demonstrate sum. If we sum that field, we get the sleep count for the entire hotel. Recall that facets count the parent document (Hotels) and not intermediate subdocuments (Rooms), so the response sums the SleepsCount of all rooms for the entire hotel. In this query, we add a filter to sum the SleepsCount for just one hotel.
+
+```rest
+POST /indexes/hotels-sample-index/docs/search?api-version=2025-03-01-Preview
+
+{ 
+      "search": "*",
+      "filter": "HotelId eq '41'",
+      "facets": [ "Rooms/SleepsCount, metric: sum"],
+      "select": "HotelId, HotelName, Rooms/Type, Rooms/SleepsCount",
+      "count": true
+}
+```
+
+A response for the query might look like the following example. Windy Ocean Model can accommodate a total of 40 guests.
+
+```json
+{
+  "@odata.count": 1,
+  "@search.facets": {
+    "Rooms/SleepsCount": [
+      {
+        "sum": 40.0
+      }
+    ]
+  },
+  "value": [
+    {
+      "@search.score": 1.0,
+      "HotelId": "41",
+      "HotelName": "Windy Ocean Motel",
+      "Rooms": [
+        {
+          "Type": "Suite",
+          "SleepsCount": 4
+        },
+        {
+          "Type": "Deluxe Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Budget Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Budget Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Suite",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Standard Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Deluxe Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Suite",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Suite",
+          "SleepsCount": 4
+        },
+        {
+          "Type": "Standard Room",
+          "SleepsCount": 4
+        },
+        {
+          "Type": "Standard Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Deluxe Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Suite",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Standard Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Deluxe Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Deluxe Room",
+          "SleepsCount": 2
+        },
+        {
+          "Type": "Standard Room",
+          "SleepsCount": 2
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Next steps
+
+Revisit [facet navigation configuration](search-faceted-navigation.md) for tools and APIs, and review [best practices](search-faceted-navigation.md#best-practices-for-working-with-facets) for working with facets in code.
+
+We recommend the [C#: Add search to web apps](tutorial-csharp-overview.md) for an example of faceted navigation that includes code for the presentation layer. The sample also includes filters, suggestions, and autocomplete. It uses JavaScript and React for the presentation layer.

@@ -1,37 +1,45 @@
 ---
-title: Add a faceted navigation category hierarchy
+title: Add facets to a query
 titleSuffix: Azure AI Search
-description: Add faceted navigation for self-directed filtering in applications that integrate with Azure AI Search.
+description: Add faceted navigation for self-directed navigation in applications that integrate with Azure AI Search.
 
 manager: nitinme
 author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
-ms.topic: concept-article
-ms.date: 02/26/2025
+ms.topic: how-to
+ms.date: 04/04/2025
 ---
 
-# Add faceted navigation to a search app
+# Add faceted navigation to search results
 
-Faceted navigation is used for self-directed drill-down filtering on query results in a search app, where your application offers form controls for scoping search to groups of documents (for example, categories or brands), and Azure AI Search provides the data structures and filters to back the experience.
+Faceted navigation is used for self-directed filtering on query results in a search app, where your application offers form controls for scoping search to groups of documents (for example, categories or brands), and Azure AI Search provides the data structures and filters to back the experience.
 
-In this article, learn how to return a faceted navigation structure in Azure AI Search.
+In this article, learn the steps for returning a faceted navigation structure in Azure AI Search. Once you're familiar with basic concepts and clients, continue to [Facet examples](search-faceted-navigation-examples.md) for syntax about various use cases, including basic faceting and distinct counts. 
+
+More facet capabilities are available through preview APIs:
+
++ hierarchical facet structures
++ facet filtering
++ facet aggregations
+
+[Facet navigation examples](search-faceted-navigation-examples.md) provide the syntax and usage for the preview features.
 
 ## Faceted navigation in a search page
 
-Facets are dynamic and returned on a query. A search response brings with it all of the facet categories used to navigate the documents in the result. The query executes first, and then facets are pulled from the current results and assembled into a faceted navigation structure.
+Facets are dynamic because they're based on each specific query result set. A search response brings with it all of the facet buckets used to navigate the documents in the result. The query executes first, and then facets are pulled from the current results and assembled into a faceted navigation structure.
 
-In Azure AI Search, facets are one layer deep and can't be hierarchical. If you aren't familiar with faceted navigation structures, the following example shows one on the left. Counts indicate the number of matches for each facet. The same document can be represented in multiple facets.
+In Azure AI Search, facets are one layer deep and can't be hierarchical unless you use the preview API. If you aren't familiar with faceted navigation structures, the following example shows one on the left. Counts indicate the number of matches for each facet. The same document can be represented in multiple facets.
 
 :::image source="media/search-faceted-navigation/azure-search-facet-nav.png" alt-text="Screenshot of faceted search results.":::
 
 Facets can help you find what you're looking for, while ensuring that you don't get zero results. As a developer, facets let you expose the most useful search criteria for navigating your search index.
 
 ## Faceted navigation in code
 
-Facets are enabled on supported fields in an index, and then specified on a query. At query time, a faceted navigation structure is returned at the top of the response.
+Facets are enabled on supported fields in an index, and then specified on a query. The faceted navigation structure is returned at the beginning of the response, followed by the results.
 
-The following REST example is an unqualified query (`"search": "*"`) that is scoped to the entire index (see the [built-in hotels sample](search-get-started-portal.md)). It returns a faceted navigation structure for the "Category" field.
+The following REST example is an empty query (`"search": "*"`) that is scoped to the entire index (see the [built-in hotels sample](search-get-started-portal.md)). The `facets` parameter specifies the "Category" field.
 
 ```http
 POST https://{{service_name}}.search.windows.net/indexes/hotels/docs/search?api-version={{api_version}}
@@ -47,7 +55,7 @@ POST https://{{service_name}}.search.windows.net/indexes/hotels/docs/search?api-
 }
 ```
 
-The response for the example includes the faceted navigation structure at the top. The structure consists of "Category" values and a count of the hotels for each one. It's followed by the rest of the search results, trimmed here to just one document for brevity. This example works well for several reasons. The number of facets for this field fall under the limit (default is 10) so all of them appear, and every hotel in the index of 50 hotels is represented in exactly one of these categories.
+The response for the example starts with the faceted navigation structure. The structure consists of "Category" values and a count of the hotels for each one. It's followed by the rest of the search results, trimmed here to just one document for brevity. This example works well for several reasons. The number of facets for this field fall under the limit (default is 10) so all of them appear, and every hotel in the index of 50 hotels is represented in exactly one of these categories.
 
 ```json
 {
@@ -94,214 +102,142 @@ The response for the example includes the faceted navigation structure at the to
                 "concierge"
             ],
             "ParkingIncluded": false,
-        }
+        },
+        . . . 
     ]
 }
 ```
 
 ## Enable facets on fields
 
-During [index creation or update](search-how-to-create-search-index.md), facets are enabled when you set `"facetable": true` on new fields that you add to an index. Although it's not strictly required, it's a best practice to also set the "filterable" attribute so that you can build the necessary filters that back the faceted navigation experience in your search application.
+You can add facets to new fields that contain plain text or numeric content. Supported data types include strings, dates, boolean fields, and numeric fields (but not vectors).
 
-Here's a JSON example of the hotels sample index, showing "facetable" and "filterable" on low cardinality fields that contain single values or short phrases: "Category", "Tags", "Rating".
+You can use the Azure portal, REST APIs, Azure SDKs or any method that supports the creation or update of index schemas in Azure AI Search. As a first step, identify which fields to use for faceting.
 
-```json
-{
-  "name": "hotels",  
-  "fields": [
-    { "name": "hotelId", "type": "Edm.String", "key": true, "searchable": false, "sortable": false, "facetable": false },
-    { "name": "Description", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
-    { "name": "HotelName", "type": "Edm.String", "facetable": false },
-    { "name": "Category", "type": "Edm.String", "filterable": true, "facetable": true },
-    { "name": "Tags", "type": "Collection(Edm.String)", "filterable": true, "facetable": true },
-    { "name": "Rating", "type": "Edm.Int32", "filterable": true, "facetable": true },
-    { "name": "Location", "type": "Edm.GeographyPoint" }
-  ]
-}
-```
+### Choose which fields to attribute
 
-### Prerequisites
+Facets can be calculated over single-value fields and collections. Fields that work best in faceted navigation have these characteristics:
 
-Add faceting to new fields that contain plain text or numeric content. Supported data types include strings, dates, boolean fields, and numeric fields (but not vectors).
+* Human readable (nonvector) content.
+* Low cardinality (a few distinct values that repeat throughout documents in your search corpus).
+* Short descriptive values (one or two words) that render nicely in a navigation tree.
+
+The values within a field, and not the field name itself, produce the facets in a faceted navigation structure. If the facet is a string field named *Color*, facets are blue, green, and any other value for that field. Review field values to ensure there are no typos, nulls, or casing differences. Consider [assigning a normalizer](search-normalizers.md) to a filterable and facetable field to smooth out minor variations in the text. For example, "Canada", "CANADA", and "canada" would all be normalized to one bucket.
+
+### Avoid unsupported fields
 
 You can't set facets on existing fields, on vector fields, or fields of type `Edm.GeographyPoint` or `Collection(Edm.GeographyPoint)`.
 
-On complex fields, "facetable" must be null.
+On complex field collections, "facetable" must be null. 
 
 ### Start with new field definitions
 
-Because attribution determines how a field is indexed, many attributes can only be set when fields are created. This restriction applies to facets and filters. If your index already exists and you add a new field definition, existing documents in the index get a null value for the new field. This null value is replaced the next time you [refresh the index](search-howto-reindex.md).
+Attributes that affect how a field is indexed can only be set when fields are created. This restriction applies to facets and filters. 
 
-### Choosing which fields to attribute
+If your index already exists, you can add a new field definition that provides facets. Existing documents in the index get a null value for the new field. This null value is replaced the next time you [refresh the index](search-howto-reindex.md).
 
-Facets can be calculated over single-value fields and collections. Fields that work best in faceted navigation have these characteristics:
+#### [**Azure portal**](#tab/portal-facet)
 
-* Human readable (nonvector) content.
+1. In the search services page of the [Azure portal](https://portal.azure.com), go to the **Fields** tab of the index and select **Add field**.
 
-* Low cardinality (a few distinct values that repeat throughout documents in your search corpus).
+1. Provide a name, data type, and attributes. We recommend adding filterable because it's common to set filters based on a facet bucket in the response. We recommend sortable because filters produce unordered results, and you might want to sort them in your application.
 
-* Short descriptive values (one or two words) that render nicely in a navigation tree.
+   You can also set searchable if you also want to support full text search on the field, and retrievable if you want to include the field in the search response.
 
-The values within a field, and not the field name itself, produce the facets in a faceted navigation structure. If the facet is a string field named *Color*, facets are blue, green, and any other value for that field.
+   :::image type="content" source="media/search-faceted-navigation/portal-add-facetable-field.png" alt-text="Screenshot of the Add fields page in the Azure portal." border="true" lightbox="media/search-faceted-navigation/portal-add-facetable-field.png":::
 
-### Defaults in REST and Azure SDKs
+1. Save the field definition.
 
-If you're using one of the Azure SDKs, your code must explicitly set the "facetable" attribute on a field.
+#### [**REST**](#tab/rest-facet)
 
-The REST API has defaults for field attributes based on the [data type](/rest/api/searchservice/supported-data-types). The following data types are "filterable" and "facetable" by default:
+When you define an index schema, facets are enabled when you set `"facetable": true` on new fields that you add to an index. Although it's not strictly required, it's a best practice to also set the "filterable" attribute so that you can build the necessary filters that back the faceted navigation experience in your search application.
+
+Start with [Create or Update Index](search-how-to-create-search-index.md) request and specify the fields collection.
+
+  Here's a JSON example of the hotels sample index, showing "facetable" and "filterable" on low cardinality fields that contain single values or short phrases: "Category", "Tags", "Rating".
+
+  ```json
+  {
+    "name": "hotels",  
+    "fields": [
+      { "name": "hotelId", "type": "Edm.String", "key": true, "searchable": false, "sortable": false, "facetable": false },
+      { "name": "Description", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
+      { "name": "HotelName", "type": "Edm.String", "facetable": false },
+      { "name": "Category", "type": "Edm.String", "filterable": true, "facetable": true },
+      { "name": "Tags", "type": "Collection(Edm.String)", "filterable": true, "facetable": true },
+      { "name": "Rating", "type": "Edm.Int32", "filterable": true, "facetable": true },
+      { "name": "Location", "type": "Edm.GeographyPoint" }
+    ]
+  }
+  ```
+
+#### Defaults in REST
+
+Both the Azure portal and the REST API have defaults for field attributes based on the [data type](/rest/api/searchservice/supported-data-types). The following data types are "filterable" and "facetable" by default:
 
 * `Edm.String` and `Collection(Edm.String)`
 * `Edm.DateTimeOffset` and `Collection(Edm.DateTimeOffset)`
 * `Edm.Boolean` and`Collection(Edm.Boolean)`
 * `Edm.Int32`, `Edm.Int64`, `Edm.Double`, and their collection equivalents
 
-## Return facets in a query
+#### [**Azure SDKs**](#tab/sdk-facet)
 
-Recall that facets are calculated from results in a query response. You only get facets for documents found by the current query. 
+If you're using one of the Azure SDKs, your code must explicitly set facetable on a field.
 
-1. Facets are configured at query-time. Use the [Search POST](/rest/api/searchservice/documents/search-post) or [Search GET](/rest/api/searchservice/documents/search-get) request, or an equivalent Azure SDK API, to specify facets. 
+Assign the facet property to fields using APIs that create or update an index.
 
-1. Set facet query parameters in the request. In Search POST, `facets` are an array of facet expressions to apply to the search query. Each facet expression contains a field name, optionally followed by a comma-separated list of name-value pairs. Valid facet parameters are `count`, `sort`, `values`, `interval`, and `timeoffset`.
+* [Azure SDK for .NET: SearchIndex.Fields Property](/dotnet/api/azure.search.documents.indexes.models.searchindex.fields)
+* [Azure SDK for Python: SearchField Class](/python/api/azure-search-documents/azure.search.documents.indexes.models.searchfield)
+* [Azure SDK for Java: SearchField Class](/java/api/com.azure.search.documents.indexes.models.searchfield)
+* [Azure SDK for JavaScript: Simple Field interface](/javascript/api/@azure/search-documents/simplefield)
 
-    | Facet parameter | Description and usage |
-    |-----------------|-----------------------|
-    | `count` | Maximum number of facet terms; default is 10. An example is `Tags,count:5`. There's no upper limit on the number of terms, but higher values degrade performance, especially if the faceted field contains a large number of unique terms. This is due to the way faceting queries are distributed across shards. You can set count to zero or to a value that's greater than or equal to the number of unique values in the "facetable" field to get an accurate count across all shards. The tradeoff is increased latency.
-    | `sort` | Set to "count", "-count", "value", "-value". Use `count` to sort descending by count. Use `-count` to sort ascending by count. Use `value` to sort ascending by value. Use `-value` to sort descending by value (for example, `"facet=category,count:3,sort:count"` gets the top three categories in facet results in descending order by the number of documents with each city name). If the top three categories are Budget, Motel, and Luxury, and Budget has five hits, Motel has 6, and Luxury has 4, then the buckets are in the order Motel, Budget, Luxury. For `-value`, `"facet=rating,sort:-value"` produces buckets for all possible ratings, in descending order by value (for example, if the ratings are from 1 to 5, the buckets are ordered 5, 4, 3, 2, 1, irrespective of how many documents match each rating). |
-    | `values` | Set to pipe-delimited numeric or `Edm.DateTimeOffset` values specifying a dynamic set of facet entry values. For example, `"facet=baseRate,values:10 | 20"` produces three buckets: one for base rate 0 up to but not including 10, one for 10 up to but not including 20, and one for 20 and higher. A string `"facet=lastRenovationDate,values:2010-02-01T00:00:00Z"` produces two buckets: one for hotels renovated before February 2010, and one for hotels renovated February 1, 2010 or later. The values must be listed in sequential, ascending order to get the expected results. |
-    | `interval` | An integer interval greater than zero for numbers, or minute, hour, day, week, month, quarter, year for date time values. For example, `"facet=baseRate,interval:100"` produces buckets based on base rate ranges of size 100. If base rates are all between $60 and $600, there are buckets for 0-100, 100-200, 200-300, 300-400, 400-500, and 500-600. The string `"facet=lastRenovationDate,interval:year"` produces one bucket for each year when hotels were renovated. |
-    | `timeoffset` | Can be set to (`[+-]hh:mm, [+-]hhmm, or [+-]hh`). If used, the timeoffset parameter must be combined with the interval option, and only when applied to a field of type `Edm.DateTimeOffset`. The value specifies the UTC time offset to account for in setting time boundaries. For example: `"facet=lastRenovationDate,interval:day,timeoffset:-01:00"` uses the day boundary that starts at 01:00:00 UTC (midnight in the target time zone). |
+---
 
-`count` and `sort` can be combined in the same facet specification, but they can't be combined with interval or values, and interval and values can't be combined together.
+## Return facets in a query
 
-Interval facets on date time are computed based on the UTC time if `timeoffset` isn't specified. For example, for `"facet=lastRenovationDate,interval:day"`, the day boundary starts at 00:00:00 UTC.
+Recall that facets are dynamically calculated from results in a query response. You only get facets for documents found by the current query.
 
-### Basic facet example
+#### [**Azure portal**](#tab/portal-facet-response)
 
-The following example works against the [hotels sample index](search-get-started-portal.md). You can use **JSON view** in Search Explorer to paste in the JSON query. This example shows three facets for "Category", "Tags", and "Rating", with a count override on "Tags" and a range override for "Rating", which is otherwise stored as a double in the index.
+Use JSON view in Search Explorer to set facet parameters in the [Azure portal](https://portal.azure.com).
 
-```http
-POST https://{{service_name}}.search.windows.net/indexes/hotels/docs/search?api-version={{api_version}}
-{
-    "search": "*",
-    "facets": [ 
-        "Category", 
-        "Tags,count:5", 
-        "Rating,values:1|2|3|4|5"
-    ],
-    "count": true
-}
-```
+1. Select an index and open Search Explorer in JSON View.
+1. Provide a query in JSON. You can type it out, copy the JSON from a REST example, or use intellisense to help with syntax. Refer to the REST example in the next tab for reference on facet expressions.
+1. Select **Search** to return faceted results, articulated in JSON.
 
-For each faceted navigation tree, there's a default limit of the top 10 facet instances found by the query. This default makes sense for navigation structures because it keeps the values list to a manageable size. You can override the default by assigning a value to "count". For example, `"Tags,count:5"` reduces the number of tags under the Tags section to the top five.
+Here's a screenshot of the [basic facet query example](search-faceted-navigation-examples.md#basic-facet-example) on the [hotels sample index](search-get-started-portal.md). You can paste in other examples in this article to return the results in Search Explorer.
 
-For Numeric and DateTime values only, you can explicitly set values on the facet field (for example, `facet=Rating,values:1|2|3|4|5`) to separate results into contiguous ranges (either ranges based on numeric values or time periods). Alternatively, you can add "interval", as in `facet=Rating,interval:1`. 
+:::image type="content" source="media/search-faceted-navigation/portal-facet-query.png" alt-text="Screenshot of the Search Explorer page in the Azure portal." border="true" lightbox="media/search-faceted-navigation/portal-facet-query.png":::
 
-Each range is built using 0 as a starting point, a value from the list as an endpoint, and then trimmed of the previous range to create discrete intervals.
+#### [**REST**](#tab/rest-facet-response)
 
-### Distinct values example
+1. Facets are configured at query-time. Use the [Search POST](/rest/api/searchservice/documents/search-post) or [Search GET](/rest/api/searchservice/documents/search-get) request, or an equivalent Azure SDK API, to specify facets. 
 
-You can formulate a query that returns a distinct value count for each "facetable" field. This example formulates an empty or unqualified query (`"search": "*"`) that matches on all documents, but by setting `top` to zero, you get just the counts, with no results.
+1. Set facet query parameters in the request. In Search POST, `facets` are an array of facet expressions to apply to the search query. Each facet expression contains a field name, optionally followed by a comma-separated list of name-value pairs. Valid facet parameters are `count`, `sort`, `values`, `interval`, and `timeoffset`.
 
-For brevity, this query includes just two fields marked as "facetable" in the hotels sample index.
+    | Facet parameter | Description and usage |
+    |-----------------|-----------------------|
+    | `count` | Maximum number of facet terms per structure; default is 10. An example is `Tags,count:5`. There's no upper limit on the number of terms, but higher values degrade performance, especially if the faceted field contains a large number of unique terms. This is due to the way faceting queries are distributed across shards. You can set count to zero or to a value that's greater than or equal to the number of unique values in the "facetable" field to get an accurate count across all shards. The tradeoff is increased latency.
+    | `sort` | Set to `count`, `-count`, `value`, `-value`. Use `count` to sort descending by count. Use `-count` to sort ascending by count. Use `value` to sort ascending by value. Use `-value` to sort descending by value (for example, `"facet=category,count:3,sort:count"` gets the top three categories in facet results in descending order by the number of documents with each Category name). If the top three categories are Budget, Motel, and Luxury, and Budget has five hits, Motel has 6, and Luxury has 4, then the buckets are in the order Motel, Budget, Luxury. For `-value`, `"facet=rating,sort:-value"` produces buckets for all possible ratings, in descending order by value (for example, if the ratings are from 1 to 5, the buckets are ordered 5, 4, 3, 2, 1, irrespective of how many documents match each rating). |
+    | `values` | Set to pipe-delimited numeric or `Edm.DateTimeOffset` values specifying a dynamic set of facet entry values. For example, `"facet=baseRate,values:10 | 20"` produces three buckets: one for base rate 0 up to but not including 10, one for 10 up to but not including 20, and one for 20 and higher. A string `"facet=lastRenovationDate,values:2010-02-01T00:00:00Z"` produces two buckets: one for hotels renovated before February 2010, and one for hotels renovated February 1, 2010 or later. The values must be listed in sequential, ascending order to get the expected results. |
+    | `interval` | An integer interval greater than zero for numbers, or minute, hour, day, week, month, quarter, year for date time values. For example, `"facet=baseRate,interval:100"` produces buckets based on base rate ranges of size 100. If base rates are all between $60 and $600, there are buckets for 0-100, 100-200, 200-300, 300-400, 400-500, and 500-600. The string `"facet=lastRenovationDate,interval:year"` produces one bucket for each year when hotels were renovated. |
+    | `timeoffset` | Can be set to (`[+-]hh:mm, [+-]hhmm, or [+-]hh`). If used, the `timeoffset` parameter must be combined with the interval option, and only when applied to a field of type `Edm.DateTimeOffset`. The value specifies the UTC time offset to account for in setting time boundaries. For example: `"facet=lastRenovationDate,interval:day,timeoffset:-01:00"` uses the day boundary that starts at 01:00:00 UTC (midnight in the target time zone). |
 
-```http
-POST https://{{service_name}}.search.windows.net/indexes/hotels/docs/search?api-version={{api_version}}
-{
-    "search": "*",
-    "count": true,
-    "top": 0,
-    "facets": [ 
-        "Category", "Address/StateProvince""
-    ]
-}
-```
+`count` and `sort` can be combined in the same facet specification, but they can't be combined with `interval` or `values`, and `interval` and `values` can't be combined together.
 
-Results from this query are as follows:
+Interval facets on date time are computed based on the UTC time if `timeoffset` isn't specified. For example, for `"facet=lastRenovationDate,interval:day"`, the day boundary starts at 00:00:00 UTC.
 
-```json
-{
-  "@odata.count": 50,
-  "@search.facets": {
-    "Address/StateProvince": [
-      {
-        "count": 9,
-        "value": "WA"
-      },
-      {
-        "count": 6,
-        "value": "CA "
-      },
-      {
-        "count": 4,
-        "value": "FL"
-      },
-      {
-        "count": 3,
-        "value": "NY"
-      },
-      {
-        "count": 3,
-        "value": "OR"
-      },
-      {
-        "count": 3,
-        "value": "TX"
-      },
-      {
-        "count": 2,
-        "value": "GA"
-      },
-      {
-        "count": 2,
-        "value": "MA"
-      },
-      {
-        "count": 2,
-        "value": "TN"
-      },
-      {
-        "count": 1,
-        "value": "AZ"
-      }
-    ],
-    "Category": [
-      {
-        "count": 13,
-        "value": "Budget"
-      },
-      {
-        "count": 12,
-        "value": "Suite"
-      },
-      {
-        "count": 7,
-        "value": "Boutique"
-      },
-      {
-        "count": 7,
-        "value": "Resort and Spa"
-      },
-      {
-        "count": 6,
-        "value": "Extended-Stay"
-      },
-      {
-        "count": 5,
-        "value": "Luxury"
-      }
-    ]
-  },
-  "value": []
-}
-```
+---
 
 ## Best practices for working with facets
 
 This section is a collection of tips and workarounds that are helpful for application development.
 
-### Initialize a faceted navigation structure
+We recommend the [C#: Add search to web apps](tutorial-csharp-overview.md) for an example of faceted navigation that includes code for the presentation layer. The sample also includes filters, suggestions, and autocomplete. It uses JavaScript and React for the presentation layer.
+
+### Initialize a faceted navigation structure with an unqualified or empty search string
 
-It's useful to initialize a search page with an open query (`"search": "*"`) to completely fill in the faceted navigation structure. As soon as you pass query terms in the request, the faceted navigation structure is scoped to just the matches in the results, rather than the entire index.
+It's useful to initialize a search page with an open query (`"search": "*"`) to completely fill in the faceted navigation structure. As soon as you pass query terms in the request, the faceted navigation structure is scoped to just the matches in the results, rather than the entire index. This practice is helpful for verifying facet and filter behaviors during testing. If you include match criteria in the query, the response excludes documents that don't match, which has the potential downstream effect of excluding facets.
 
 ### Clear facets
 
@@ -315,7 +251,15 @@ Remember that you can't use `Edm.GeographyPoint` or `Collection(Edm.GeographyPoi
 
 ### Check for bad data
 
-As you prepare data for indexing, check fields for null values, misspellings or case discrepancies, and single and plural versions of the same word. By default, filters and facets don't undergo lexical analysis or [spell check](speller-how-to-add.md), which means that all values of a "facetable" field are potential facets, even if the words differ by one character. Optionally, you can [assign a normalizer](search-normalizers.md) to a "filterable" and "facetable" field to smooth out variations in casing and characters.
+As you prepare data for indexing, check fields for null values, misspellings or case discrepancies, and single and plural versions of the same word. By default, filters and facets don't undergo lexical analysis or [spell check](speller-how-to-add.md), which means that all values of a "facetable" field are potential facets, even if the words differ by one character. 
+
+[Normalizers](search-normalizers.md) can mitigate data discrepancies, correcting for casing and character differences. Otherwise, to inspect your data, you can check fields at their source, or run queries that return values from the index.
+
+An index isn't the best place to fix nulls or invalid values. You should fix data problems in your source, assuming it's a database or persistent storage, or in a data cleansing step that you perform prior to indexing. 
+
+### Ordering facet buckets
+
+Although you can sort within a bucket, there's no parameters for controlling the order of facet buckets in the navigation structure as a whole. If you want facet buckets in a specific order, you must provide it in application code.
 
 ### Discrepancies in facet counts
 
@@ -346,4 +290,5 @@ Content type
 
 ## Next steps
 
-We recommend the [C#: Add search to web apps](tutorial-csharp-overview.md) for an example of faceted navigation that includes code for the presentation layer. The sample also includes filters, suggestions, and autocomplete. It uses JavaScript and React for the presentation layer.
+> [!div class="nextstepaction"]
+> [Facet navigation examples](search-faceted-navigation-examples.md)
\ No newline at end of file

@@ -9,7 +9,7 @@ metadata:
   ms.author: haileytapia
   ms.service: azure-ai-search
   ms.topic: faq
-  ms.date: 01/16/2025
+  ms.date: 03/21/2025
 title: Azure AI Search Frequently Asked Questions
 summary:  Find answers to commonly asked questions about Azure AI Search.
 
@@ -36,7 +36,7 @@ sections:
         answer: |
           For vectors, the embedding models you use determines the linguistic experience. 
           
-          For nonvector strings and numbers, the default analyzer used for tokenization is standard Lucene and it's language agnostic. Otherwise, language support is expressed through [language analyzers](index-add-language-analyzers.md#supported-language-analyzers) that apply linguistic rules to inbound (indexing) and outbound (queries) content. Some features, such as [speller](speller-how-to-add.md#supported-languages) and [query rewrite](semantic-how-to-query-rewrite.md), are limited to a subset of languages.
+          For nonvector strings and numbers, the default analyzer used for tokenization is standard Lucene, which is language agnostic. Otherwise, language support is expressed through [language analyzers](index-add-language-analyzers.md#supported-language-analyzers) that apply linguistic rules to inbound (indexing) and outbound (queries) content. Some features, such as [speller](speller-how-to-add.md#supported-languages) and [query rewrite](semantic-how-to-query-rewrite.md), are limited to a subset of languages.
 
       - question: |
           How do I integrate search into my solution?
@@ -56,15 +56,27 @@ sections:
           You can't pause a search service. In Azure AI Search, computing resources are allocated when the service is created. It's not possible to release and reclaim those resources on-demand.
 
       - question: |
-          Can I upgrade, downgrade, rename or move the service?
+          Can I upgrade or downgrade the service?
         answer: |
-          Service tier, name, and region are fixed for the lifetime of the service.
+          Services created before April 2024 in select regions can be [upgraded to higher capacity clusters](search-how-to-upgrade.md). Downgrading your service isn't supported. 
+          
+          To get more capacity, you can also [switch to a higher pricing tier](search-capacity-planning.md#change-your-pricing-tier). Your region can't have [capacity constraints on the higher tier](search-region-support.md), and you can only move up between Basic and Standard (S1, S2, and S3) tiers, such as going from Basic to S1. Currently, you can't switch to a lower tier.
+          
+      - question: |
+          Can I rename or move the service?
+        answer: |
+          Service name and region are fixed for the lifetime of the service.
           
       - question: |
           If I migrate my search service to another subscription or resource group, should I expect any downtime?
         answer: |
           As long as you follow the [checklist before moving resources](/azure/azure-resource-manager/management/move-resource-group-and-subscription) and make sure each step is completed, there shouldn't be any downtime.
 
+      - question: |
+          Why do I see different storage limits for same-tier search services?
+        answer: |
+          Storage limits can vary by service creation date. In most supported regions, [newer services have higher storage limits than older services](search-limits-quotas-capacity.md#partition-storage-gb), even if they're on the same tier. However, you might be able to [upgrade your old service](search-how-to-upgrade.md) to access the new limits.
+
   - name: Indexing 
     questions:
       - question: |
@@ -130,7 +142,12 @@ sections:
       - question: |
           Why do I see different vector index size limits between my new search services and existing search services?
         answer: |
-          Azure AI Search rolled out improved vector index size limits worldwide for new search services, but [some regions experience capacity constraints](search-region-support.md), and some regions don't have the required infrastructure. New search services created in supported regions should see increased vector index size limits. Unfortunately, we can't migrate existing services to the new limits. Also, only vector indexes that use the Hierarchical Navigable Small World (HNSW) algorithm report on vector index size in the Azure portal. If your index uses exhaustive KNN, vector index size is reported as zero, even though the index contains vectors. 
+          Azure AI Search rolled out improved vector index size limits worldwide for new search services, but [some regions experience capacity constraints](search-region-support.md), and some regions don't have the required infrastructure. New search services created after May 2024 in supported regions should see increased vector index size limits. Alternatively, if you have an existing service in a supported region, you can [upgrade your service](search-how-to-upgrade.md) to access the new limits.
+          
+      - question: |
+          Why does my vector index show zero storage?
+        answer: |    
+          Only vector indexes that use the Hierarchical Navigable Small World (HNSW) algorithm report on vector index size in the Azure portal. If your index uses exhaustive KNN, vector index size is reported as zero, even though the index contains vectors. 
 
       - question: |
           How do I enable vector search on a search index?
@@ -141,7 +158,7 @@ sections:
           
           * Add a "vectorSearch" section to the index schema specifying the configuration used by vector search fields, including the parameters of the Approximate Nearest Neighbor algorithm used, like HNSW.
           
-          * Use the latest stable version[**2024-07-01**](/rest/api/searchservice), or an Azure SDK to create or update the index, load documents, and issue queries. For more information, see [Create a vector index](vector-search-how-to-create-index.md).
+          * Use the latest stable version, [**2024-07-01**](/rest/api/searchservice), or an Azure SDK to create or update the index, load documents, and issue queries. For more information, see [Create a vector index](vector-search-how-to-create-index.md).
 
   - name: Queries
     questions:
@@ -189,7 +206,7 @@ sections:
       - question: |
           Does Azure AI Search process customer data in other regions?
         answer: |
-          Processing (vectorization or applied AI transformations) is performed in the Geo that hosts the Azure AI services used by skills, or the Azure apps or functions hosting custom skills, or the Azure OpenAI or Azure AI Foundry region that hosts your deployed models. These resources are specified by you, so you can choose whether to provision them in the same Geo as your search service or not
+          Processing (vectorization or applied AI transformations) is performed in the Geo that hosts the Azure AI services used by skills, or the Azure apps or functions hosting custom skills, or the Azure OpenAI or Azure AI Foundry region that hosts your deployed models. These resources are specified by you, so you can choose whether to deploy them in the same Geo as your search service or not.
           
           If you send data to external (non-Azure) models or services, the processing location is determined by the external service. 
 

@@ -10,7 +10,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 11/20/2024
+ms.date: 03/18/2025
 ---
 
 # Index data from Azure SQL Database
@@ -30,13 +30,17 @@ This article also provides:
 
 ## Prerequisites
 
-+ An [Azure SQL database](/azure/azure-sql/database/sql-database-paas-overview) with data in a single table or view, or a [SQL Managed Instance with a public endpoint](search-how-to-index-sql-managed-instance.md).
++ An [Azure SQL database](/azure/azure-sql/database/sql-database-paas-overview) or a [SQL Managed Instance with a public endpoint](search-how-to-index-sql-managed-instance.md).
 
-  Use a table if your data is large or if you need [incremental indexing](#CaptureChangedRows) using SQL's native change detection capabilities.
++ A single table or view.
 
-  Use a view if you need to consolidate data from multiple tables. Large views aren't ideal for SQL indexer. A workaround is to create a new table just for ingestion into your Azure AI Search index. You can use SQL integrated change tracking to track new and changed rows, which is easier to implement than High Water Mark.
+  Use a table if your data is large or if you need incremental indexing using SQL's native change detection capabilities ([SQL integrated change tracking](#indexing-new-changed-and-deleted-rows)) to reflect new, changed, and deleted rows in the search index.
 
-+ Read permissions. Azure AI Search supports SQL Server authentication, where the user name and password are provided on the connection string. Alternatively, you can [set up a managed identity and use Azure roles](search-howto-managed-identities-sql.md).
+  Use a view if you need to consolidate data from multiple tables. Large views aren't ideal for SQL indexer. A workaround is to create a new table just for ingestion into your Azure AI Search index. If you choose to go with a view, you can use [High Water Mark](#indexing-new-changed-and-deleted-rows) for change detection, but must use a workaround for deletion detection.
+
++ Primary key must be single-valued. On a table, it must also be non-clustered for full SQL integrated change tracking.
+
++ Read permissions. Azure AI Search supports SQL Server authentication, where the user name and password are provided on the connection string. Alternatively, you can [set up a managed identity and use Azure roles](search-howto-managed-identities-sql.md) with membership in **SQL Server Contributor** or **SQL DB Contributor** roles.
 
 To work through the examples in this article, you need the Azure portal or a [REST client](search-get-started-rest.md). If you're using Azure portal, make sure that access to all public networks is enabled in the Azure SQL firewall and that the client has access via an inbound rule. For a REST client that runs locally, configure the SQL Server firewall to allow inbound access from your device IP address. Other approaches for creating an Azure SQL indexer include Azure SDKs.
 
@@ -52,12 +56,12 @@ Use these instructions to create and load a table in Azure SQL Database for test
 
 1. On your Azure SQL database, select **Query editor (preview)** and then select **New Query**.
 
-1. Paste in and then run the T-SQL script that creates the hotels table.
+1. Paste in and then run the T-SQL script that creates the hotels table. A non-clustered primary key is a requirement for SQL integrated change tracking.
 
    ```tsql
    CREATE TABLE tbl_hotels
     (
-        Id TINYINT PRIMARY KEY,
+        Id TINYINT PRIMARY KEY NONCLUSTERED,
         Modified DateTime NULL DEFAULT '0000-00-00 00:00:00',
         IsDeleted TINYINT,
         HotelName VARCHAR(40),
@@ -93,9 +97,9 @@ Use these instructions to create and load a table in Azure SQL Database for test
    SELECT Description FROM tbl_hotels;
     ```
 
-You should see results similar to the following screenshot.
+   You should see results similar to the following screenshot.
 
-:::image type="content" source="media/search-how-to-index-sql-database/tsql-query-results.png" alt-text="Screenshot of query results showing the description field.":::
+   :::image type="content" source="media/search-how-to-index-sql-database/tsql-query-results.png" alt-text="Screenshot of query results showing the description field.":::
 
 The Description field provides the most verbose content. You should target this field for full text search and optional vectorization.
 
@@ -104,39 +108,42 @@ Now that you have a database table, you can use the Azure portal, REST client, o
 > [!TIP]
 > Another resource that provides sample content and code can be found on [Azure-Samples/SQL-AI-samples](https://github.com/Azure-Samples/SQL-AI-samples/tree/main/AzureSQLACSSamples/src).
 
-## Use the Azure portal
-
-You can use either the **Import data** wizard or **Import and vectorize data** wizard to automate indexing from an SQL database table or view. The data source configuration is similar for both wizards.
-
-1. [Start the wizard](search-import-data-portal.md#starting-the-wizards).
-
-1. On **Connect to your data**, select or verify that the data source type is either *Azure SQL Database* or *SQL database*.
+## Set up the indexer pipeline
 
-   The data source name refers to the data source connection object in Azure AI Search. If you use the vector wizard, your data source name is autogenerated using a custom prefix specified at the end of the wizard workflow.
+In this step, specify the data source, index, and indexer.
 
-1. Specify the server name, database name, and table or view name.
+### [**Azure portal**](#tab/portal-sql)
 
-   the Azure portal validates the connection. If the database is paused due to inactivity, navigate to the database server page and make sure database status is *online*. You can run a query on any table to activate the database.
+1. Make sure your SQL database is active and not paused due to inactivity. In the Azure portal, navigate to the database server page and verify the database status is *online*. You can run a query on any table to activate the database.
 
    :::image type="content" source="media/search-how-to-index-sql-database/database-online.png" alt-text="Screenshot of the database status page in the Azure portal.":::
 
-1. Specify an authentication method, either a SQL Server login defined during server setup, or a managed identity.
+1. Make sure you have a table or view that meets the requirements for indexers and change detection.
 
-   If you [configure Azure AI Search to use a managed identity](search-howto-managed-identities-data-sources.md), and you create a role assignment on the database server that grants **SQL Server Contributor** or **SQL DB Contributor** permissions to the identity, your indexer can connect to Azure SQL using Microsoft Entra ID and roles.
+   First, you can only pull from a single table or view. We recommend tables because they support SQL integrated change tracking policy, which detects new, updated, and deleted rows. A high water mark policy doesn't support row deletion and is harder to implement.
 
-1. For the **Import and vectorize data** wizard, you can specify options for change and deletion tracking.
+   Second, the primary key must be a single value (compound keys aren't supported) and non-clustered.
 
-   + Deletion tracking is based on [soft delete using custom metadata](#soft-delete-column-deletion-detection-policy).
+1. Switch to your search service and create a data source. Under **Search management** > **Data sources**, select **Add data source**:
 
-   + Change tracking is based on [SQL Server integrated change tracking](#sql-integrated-change-tracking-policy) or [high water mark change tracking](#high-water-mark-change-detection-policy).
+   1. For data source type, choose *Azure SQL Database*.
+   1. Provide a name for the data source object on Azure AI Search.
+   1. Use the dropdowns to select the subscription, account type, server, database, table or view, schema, and table name.
+   1. For change tracking we recommend **SQL Integrated Change Tracking Policy**.
+   1. For authentication, we recommend connecting with a [managed identity](search-howto-managed-identities-data-sources.md). Your search service must have **SQL Server Contributor** or **SQL DB Contributor** role membership on the database.
+   1. Select **Create** to create the data source.
 
-1. Continue with the remaining steps to complete the wizard:
+   :::image type="content" source="media/search-how-to-index-sql-database/search-data-source.png" alt-text="Screenshot of the data source creation page in the Azure portal.":::
 
-   + [Quickstart: Import data wizard](search-get-started-portal.md)
+1. Start the **Import data** wizard to create the index and indexer.
 
-   + [Quickstart: Import and vectorize data wizard](search-get-started-portal-import-vectors.md)
+   1. On the Overview page, select **Import data**.
+   1. Select the data source you just created, and select **Next**.
+   1. Skip the **Add cognitive skills (Optional)** page.
+   1. On **Customize target index**, name the index, set the key to your primary key in the table, and then group select *Retrievable* and *Searchable* for all fields, and optionally add *Filterable* and *Sortable* for short strings or numeric values.
+   1. On **Create an indexer**, name the indexer and select **Submit**.
 
-## Use the REST APIs
+### [**REST**](#tab/test-sql)
 
 This section demonstrates the REST API calls that create a data source, index, and indexer.
 
@@ -178,6 +185,7 @@ The data source definition specifies the data to index, credentials, and policie
    + Alternatively, you can specify a managed identity connection string that doesn't include database secrets with the following format: `Initial Catalog|Database=<your database name>;ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Sql/servers/<your SQL Server name>/;Connection Timeout=connection timeout length;`.
 
     For more information, see [Connect to Azure SQL Database indexer using a managed identity](search-howto-managed-identities-sql.md).
+
 > [!NOTE]
 > For the container name property, the value is restricted to only allow letters, numbers, underscores (_), dots (.), single dashes (-), and square brackets ([])
 
@@ -280,6 +288,8 @@ Once the index and data source have been created, you're ready to create the ind
 
 An indexer runs automatically when it's created. You can prevent this by setting "disabled" to true. To control indexer execution, [run an indexer on demand](search-howto-run-reset-indexers.md) or [put it on a schedule](search-howto-schedule-indexers.md).
 
+---
+
 ## Check indexer status
 
 To monitor the indexer status and execution history, check the indexer execution history in the Azure portal, or send a [Get Indexer Status](/rest/api/searchservice/indexers/get-status) REST API request
@@ -350,22 +360,23 @@ For Azure SQL indexers, there are two change detection policies:
 
 + "SqlIntegratedChangeTrackingPolicy" (applies to tables only)
 
-+ "HighWaterMarkChangeDetectionPolicy" (works for tables and views)
++ "HighWaterMarkChangeDetectionPolicy" (works for views)
 
 ### SQL Integrated Change Tracking Policy
 
 We recommend using "SqlIntegratedChangeTrackingPolicy" for its efficiency and its ability to identify deleted rows.
 
 Database requirements:
 
-+ SQL Server 2012 SP3 and later, if you're using SQL Server on Azure VMs
-+ Azure SQL Database or SQL Managed Instance
-+ Tables only (no views)
-+ On the database, [enable change tracking](/sql/relational-databases/track-changes/enable-and-disable-change-tracking-sql-server) for the table
-+ No composite primary key (a primary key containing more than one column) on the table
-+ No clustered indexes on the table. As a workaround, any clustered index would have to be dropped and re-created as nonclustered index, however, performance might be affected in the source compared to having a clustered index
++ Azure SQL Database or SQL Managed Instance. SQL Server 2016 or later if you're using an Azure VM.
++ Database must have [change tracking enabled](/sql/relational-databases/track-changes/enable-and-disable-change-tracking-sql-server)
++ Tables only (no views).
++ Tables can't be clustered. To meet this requirement, drop the clustered index and recreate it as non-clustered index. This workaround often degrades performance. Duplicating content in a second table that's dedicated to indexer processing can be a helpful mitigation. 
++ Tables can't be empty. If you use TRUNCATE TABLE to clear rows, a reset and rerun of the indexer won't remove the corresponding search documents. To remove orphaned search documents, you must [index them with a delete action](search-howto-reindex.md#delete-orphan-documents).
++ Primary key can't be a compound key (containing more than one column).
++ Primary key must be non-clustered if you want deletion detection.
 
-Change detection policies are added to data source definitions. To use this policy, create or update your data source like this:
+Change detection policies are added to data source definitions. To use this policy, edit the data source definition in the Azure portal, or use REST to update your data source like this:
 
 ```http
 POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
@@ -382,10 +393,10 @@ api-key: admin-key
     }
 ```
 
-When using SQL integrated change tracking policy, don't specify a separate data deletion detection policy. The SQL integrated change tracking policy has built-in support for identifying deleted rows. However, for the deleted rows to be detected automatically, the document key in your search index must be the same as the primary key in the SQL table. 
+When using SQL integrated change tracking policy, don't specify a separate data deletion detection policy. The SQL integrated change tracking policy has built-in support for identifying deleted rows. However, for the deleted rows to be detected automatically, the document key in your search index must be the same as the primary key in the SQL table, and the primary key must be non-clustered.
 
-> [!NOTE]  
-> When using [TRUNCATE TABLE](/sql/t-sql/statements/truncate-table-transact-sql) to remove a large number of rows from a SQL table, the indexer needs to be [reset](/rest/api/searchservice/indexers/reset) to reset the change tracking state to pick up row deletions.
+<!-- > [!NOTE]  
+> When using [TRUNCATE TABLE](/sql/t-sql/statements/truncate-table-transact-sql) to remove a large number of rows from a SQL table, the indexer needs to be [reset](/rest/api/searchservice/indexers/reset) to reset the change tracking state to pick up row deletions. -->
 
 <a name="HighWaterMarkPolicy"></a>
 

@@ -10,7 +10,7 @@ ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: conceptual
-ms.date: 02/25/2025
+ms.date: 03/21/2025
 ---
 
 # Index large data sets in Azure AI Search
@@ -21,7 +21,7 @@ These strategies assume familiarity with the [two basic approaches for importing
 
 This article complements [Tips for better performance](search-performance-tips.md), which offers best practices on index and query design. A well-designed index that includes only the fields and attributes you need is an important prerequisite for large-scale indexing.
 
-We recommend using a newer search service, created after April 3, 2024, for [higher storage per partition](search-limits-quotas-capacity.md#service-limits).
+We recommend using a search service created after April 3, 2024 for [higher storage per partition](search-limits-quotas-capacity.md#service-limits). Older services can also be [upgraded to benefit from higher partition storage](search-how-to-upgrade.md).
 
 > [!NOTE]
 > The strategies described in this article assume a single large data source. If your solution requires indexing from multiple data sources, see [Index multiple data sources in Azure AI Search](/samples/azure-samples/azure-search-dotnet-scale/multiple-data-sources/) for a recommended approach.
@@ -46,7 +46,7 @@ Because the optimal batch size depends on your index and your data, the best app
 
 ### Manage threads and a retry strategy
 
-Indexers have built-in thread management, but when you're using the push APIs, your application code needs to manage threads. Make sure there are sufficient threads to make full use of the available capacity, especially if you've recently increased partitions or upgraded to a higher tier search service. 
+Indexers have built-in thread management, but when you're using the push APIs, your application code needs to manage threads. Make sure there are sufficient threads to make full use of the available capacity, especially if you recently [upgraded your service](search-how-to-upgrade.md), [switched to a higher tier](search-capacity-planning.md#change-your-pricing-tier), or [increased partitions](search-capacity-planning.md#add-or-remove-partitions-and-replicas).
 
 1. [Increase the number of concurrent threads](tutorial-optimize-indexing-push-api.md#use-multiple-threadsworkers) in your client code.
 
@@ -97,7 +97,7 @@ When there are no longer any new or updated documents in the data source, indexe
 For more information about setting schedules, see [Create Indexer REST API](/rest/api/searchservice/indexers/create) or see [Schedule indexers for Azure AI Search](search-howto-schedule-indexers.md).
 
 > [!NOTE]
-> Some indexers that run on an older runtime architecture have a 24-hour rather than 2-hour maximum processing window. The two-hour limit is for newer content processors that run in an [internally managed multitenant environment](search-howto-run-reset-indexers.md#indexer-execution-environment). Whenever possible, Azure AI Search tries to offload indexer and skillset processing to the multi-tenant environment. If the indexer can't be migrated, it runs in the private environment and it can run for as long as 24 hours. If you're scheduling an indexer that exhibits these characteristics, assume a 24-hour processing window.
+> Some indexers that run on an older runtime architecture have a 24-hour rather than 2-hour maximum processing window. The two-hour limit is for newer content processors that run in an [internally managed multitenant environment](search-howto-run-reset-indexers.md#indexer-execution-environment). Whenever possible, Azure AI Search tries to offload indexer and skillset processing to the multitenant environment. If the indexer can't be migrated, it runs in the private environment and it can run for as long as 24 hours. If you're scheduling an indexer that exhibits these characteristics, assume a 24-hour processing window.
 
 <a name="parallel-indexing"></a>
 

@@ -9,7 +9,7 @@ ms.author: heidist
 
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 10/31/2024
+ms.date: 03/21/2025
 ---
 
 # Load data into a search index in Azure AI Search
@@ -28,7 +28,7 @@ You can prepare these documents yourself, but if content resides in a [supported
 
 Once data is indexed, the physical data structures of the index are locked in. For guidance on what can and can't be changed, see [Update and rebuild an index](search-howto-reindex.md).
 
-Indexing isn't a background process. A search service will balance indexing and query workloads, but if [query latency is too high](search-performance-analysis.md#impact-of-indexing-on-queries), you can either [add capacity](search-capacity-planning.md#adjust-capacity) or identify periods of low query activity for loading an index.
+Indexing isn't a background process. A search service will balance indexing and query workloads, but if [query latency is too high](search-performance-analysis.md#impact-of-indexing-on-queries), you can either [add capacity](search-capacity-planning.md#add-or-remove-partitions-and-replicas) or identify periods of low query activity for loading an index.
 
 For more information, see [Data import strategies](search-what-is-data-import.md).
 

@@ -6,7 +6,7 @@ author: rawan
 ms.author: rawan
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 11/22/2024
+ms.date: 04/07/2025
 ms.custom:
   - references_regions
   - ignite-2024
@@ -36,13 +36,15 @@ For illustration purposes, this article uses the [sample health plan PDFs](https
 
 + [An indexer-based indexing pipeline](search-indexer-overview.md) with an index that accepts the output. The index must have fields for receiving headings and content.
 
++ [An index projection](search-how-to-define-index-projections.md) for one-to-many indexing.
+
 + [A supported data source](search-indexer-overview.md#supported-data-sources) having text content that you want to chunk.
 
-+ [A skillset with Document Layout skill](cognitive-search-skill-document-intelligence-layout.md) that splits documents based on paragraph boundaries.
++ A skillset with these two skills:
 
-+ [An Azure OpenAI Embedding skill](cognitive-search-skill-azure-openai-embedding.md) that generates vector embeddings.
+  + [Document Layout skill](cognitive-search-skill-document-intelligence-layout.md) that splits documents based on paragraph boundaries. This skill has region requirements. An Azure AI multi-service resource must be in the same region as Azure AI Search with AI Enrichment.
 
-+ [An index projection](search-how-to-define-index-projections.md) for one-to-many indexing.
+  + [Azure OpenAI Embedding skill](cognitive-search-skill-azure-openai-embedding.md) that generates vector embeddings. This skill also has region requirements. The model must be in the same region as Azure AI Search.
 
 ## Prepare data files
 
@@ -52,7 +54,7 @@ The raw inputs must be in a [supported data source](search-indexer-overview.md#s
 
 + Supported indexers can be any indexer that can handle the supported file formats. These indexers include [Blob indexers](search-howto-indexing-azure-blob-storage.md), [OneLake indexers](search-how-to-index-onelake-files.md), [File indexers](search-file-storage-integration.md).
 
-+ Supported regions for this feature include: East US, West US2, West Europe, North Central US. Be sure to [check this list](search-region-support.md#azure-public-regions) for updates on regional availability.
++ Supported regions for the portal experience of this feature include: East US, West Europe, North Central US. If your setting up your skillset programmatically, you can use any Document Intelligence region that also provides the AI enrichment feature of Azure AI Search. For more information, see [Product availability by region](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/table).
 
 You can use the Azure portal, REST APIs, or an Azure SDK package to [create a data source](search-howto-indexing-azure-blob-storage.md).
 

@@ -0,0 +1,115 @@
+---
+title: Service Upgrade in the Azure Portal
+titleSuffix: Azure AI Search
+description: Learn how to upgrade your existing Azure AI Search service to high-capacity storage and processors in your region.
+manager: nitinme
+author: haileytap
+ms.author: haileytapia
+ms.service: azure-ai-search
+ms.topic: how-to
+ms.custom: references_regions
+ms.date: 04/04/2025
+---
+
+# Upgrade your Azure AI Search service in the Azure portal
+
+[!INCLUDE [Feature preview](./includes/previews/preview-generic.md)]
+
+An upgrade brings older search services to the capabilities of new services created in the same region. Specifically, it upgrades the computing power of the underlying service. This one-time operation doesn't introduce breaking changes to your application, and you shouldn't need to change any code.
+
+For [eligible services](#upgrade-eligibility), an upgrade increases the [partition storage](#higher-storage-limits) and [vector index size](#higher-vector-limits) on the same tier at no extra cost.
+
+> [!TIP]
+> Looking to [change your pricing tier](search-capacity-planning.md#change-your-pricing-tier)? You can now move up between Basic and Standard (S1, S2, and S3) tiers.
+
+This article describes how to upgrade your service in the [Azure portal](https://portal.azure.com/). Alternatively, you can use the [Search Management REST APIs](/rest/api/searchmanagement/) to upgrade your service programmatically. For more information, see [Manage your search service using REST](search-manage-rest.md#upgrade-a-service).
+
+## About service upgrades
+
+In April 2024, Azure AI Search increased the [storage capacity](search-limits-quotas-capacity.md#service-limits) of newly created search services. Services created before April 2024 saw no capacity changes, so if you wanted larger and faster partitions, you had to create a new service. However, some older services can now be upgraded to benefit from the higher capacity partitions.
+
+In this preview, an upgrade only increases the [storage limit](#higher-storage-limits) and [vector index size](#higher-vector-limits) of [eligible services](#upgrade-eligibility).
+
+### Upgrade eligibility
+
+To qualify for an upgrade, your service:
+
+> [!div class="checklist"]
+> + Must have been created before April 2024. Services created after April 2024 should already have higher capacity. To see when you created your service, [check your service creation date](#check-your-service-creation-or-upgrade-date).
+> + Must be in a region where higher capacity is enabled.
+> + Must be in one of the following regions:
+>   + East US
+>   + North Central US
+>   + West Central US
+>   + UK South
+
+<!-- Check the footnotes in the [list of supported regions](search-region-support.md). -->
+
+### Higher storage limits
+
+For [eligible services](#upgrade-eligibility), the following table compares the storage limit (per partition) before and after an upgrade.
+
+| | Basic <sup>1</sup> | S1 | S2 | S3/HD | L1 | L2 |
+|-|-|-|-|-|-|-|
+| **Limit before upgrade** | 2 GB | 25 GB | 100 GB | 200 GB | 1 TB | 2 TB |
+| **Limit after upgrade** | 15 GB | 160 GB | 512 GB | 1 TB | 2 TB | 4 TB |
+
+<sup>1</sup> Basic services created before April 3, 2024 were originally limited to one partition, which increases to three partitions after an upgrade. [Partition counts for all other pricing tiers](search-limits-quotas-capacity.md#service-limits) stay the same.
+
+### Higher vector limits
+
+For [eligible services](#upgrade-eligibility), the following table compares the vector index size (per partition) before and after an upgrade.
+
+| | Basic | S1 | S2 | S3/HD | L1 | L2 |
+|-|-|-|-|-|-|-|
+| **Limit before upgrade** | 0.5 GB <sup>1</sup> or 1 GB <sup>2</sup> | 1 GB <sup>1</sup> or 3 GB <sup>2</sup> | 6 GB <sup>1</sup> or 12 GB <sup>2</sup> | 12 GB <sup>1</sup> or 36 GB <sup>2</sup> | 12 GB | 36 GB |
+| **Limit after upgrade** | 5 GB | 35 GB | 150 GB | 300 GB | 150 GB | 300 GB |
+
+<sup>1</sup> Applies to services created before July 1, 2023.
+
+<sup>2</sup> Applies to services created between July 1, 2023 and April 3, 2024 in all regions except Germany West Central, Qatar Central, and West India, to which the <sup>1</sup> limits apply.
+
+## Check your service creation or upgrade date
+
+On the **Overview** page, you can view various metadata about your search service, including the **Create date (UTC)** and **Upgrade date (UTC)**.
+
+:::image type="content" source="media/search-how-to-upgrade/service-creation-upgrade-metadata.png" alt-text="Screenshot of the service creation and service upgrade dates in the Azure portal." border="true":::
+
+The date you created your service partially determines its [upgrade eligibility](#upgrade-eligibility). If your service has never been upgraded, the **Upgrade date (UTC)** doesn't appear.
+
+## Upgrade your service
+
+You can’t undo a service upgrade. Before you proceed, make sure that you want to permanently increase the [storage limit](#higher-storage-limits) and [vector index size](#higher-vector-limits) of your search service. We recommend that you test this operation in a nonproduction environment.
+
+To upgrade your service:
+
+1. Sign in to the [Azure portal](https://portal.azure.com/) and select your search service.
+
+1. On the **Overview** page, select **Upgrade** from the command bar.
+
+   :::image type="content" source="media/search-how-to-upgrade/upgrade-button.png" alt-text="Screenshot of the Upgrade button on the command bar in the Azure portal." border="true":::
+
+   If this button appears dimmed, an upgrade isn’t available for your service. Your service either has the [latest upgrade](#check-your-service-creation-or-upgrade-date) or is in an [unsupported region](#upgrade-eligibility).
+
+1. Review the upgrade details for your service, and then select **Upgrade**.
+
+   :::image type="content" source="media/search-how-to-upgrade/upgrade-panel.png" alt-text="Screenshot of your service upgrade details in the Azure portal." border="true":::
+
+   A confirmation appears reminding you that the upgrade can't be undone.
+
+1. To permanently upgrade your service, select **Upgrade**.
+
+   :::image type="content" source="media/search-how-to-upgrade/upgrade-confirmation.png" alt-text="Screenshot of the upgrade confirmation in the Azure portal." border="true":::
+
+1. Check your notifications to confirm that the operation started.
+
+   The upgrade is an asynchronous operation, so you can continue using your service. Depending on the size of your service, the upgrade can take several hours to complete.
+
+   If the upgrade fails, your service returns to its original state.
+
+## Next step
+
+After you upgrade your search service, you might want to reconsider your scale configuration:
+
+> [!div class="nextstepaction"]
+> [Estimate and manage capacity of an Azure AI Search service](search-capacity-planning.md)