@@ -8,7 +8,7 @@ ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
 ms.date: 11/19/2025
-zone_pivot_groups: agentic-retrieval-pivots
+zone_pivot_groups: search-csharp-python-rest
 ---
 
 # Create a blob knowledge source from Azure Blob Storage and ADLS Gen2

@@ -10,7 +10,7 @@ ms.custom:
   - ignite-2025
 ms.topic: how-to
 ms.date: 11/20/2025
-zone_pivot_groups: agentic-retrieval-pivots
+zone_pivot_groups: search-csharp-python-rest
 ---
 
 # Create an indexed OneLake knowledge source

@@ -8,7 +8,7 @@ ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
 ms.date: 11/19/2025
-zone_pivot_groups: agentic-retrieval-pivots
+zone_pivot_groups: search-csharp-python-rest
 ---
 
 # Create a search index knowledge source

@@ -8,7 +8,7 @@ ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
 ms.date: 11/20/2025
-zone_pivot_groups: agentic-retrieval-pivots
+zone_pivot_groups: search-csharp-python-rest
 ---
 
 # Create an indexed SharePoint knowledge source

@@ -8,7 +8,7 @@ ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
 ms.date: 11/19/2025
-zone_pivot_groups: agentic-retrieval-pivots
+zone_pivot_groups: search-csharp-python-rest
 ---
 
 # Create a remote SharePoint knowledge source

@@ -10,7 +10,7 @@ ms.custom:
   - ignite-2025
 ms.topic: how-to
 ms.date: 11/19/2025
-zone_pivot_groups: agentic-retrieval-pivots
+zone_pivot_groups: search-csharp-python-rest
 ---
 
 # Create a Web Knowledge Source resource

@@ -7,7 +7,7 @@ ms.author: haileytapia
 ms.service: azure-ai-search
 ms.topic: how-to
 ms.date: 01/15/2026
-zone_pivot_groups: agentic-retrieval-pivots
+zone_pivot_groups: search-csharp-python-rest
 ---
 
 # Create a knowledge base in Azure AI Search

@@ -33,7 +33,7 @@ Afterwards, you test the knowledge base by submitting a complex query that requi
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-+ An [Azure AI Search service](search-create-service-portal.md) in any [region that provides agentic retrieval](search-region-support.md).
++ An [Azure AI Search service](search-create-service-portal.md) in any [region that provides agentic retrieval](search-region-support.md). This quickstart requires the Basic tier or higher for managed identity support.
 
 + An [Azure Blob Storage account](/azure/storage/common/storage-account-create).
 

@@ -214,7 +214,7 @@ from azure.search.documents.models import VectorizedQuery
 
 # Set up the client
 endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
-index_name = "hotels-sample-index"
+index_name = "hotels-sample"
 credential = DefaultAzureCredential()
 
 client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
@@ -256,7 +256,7 @@ using Azure.Search.Documents.Models;
 
 // Set up the client
 string endpoint = Environment.GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
-string indexName = "hotels-sample-index";
+string indexName = "hotels-sample";
 
 SearchClient client = new SearchClient(
     new Uri(endpoint),

@@ -45,7 +45,7 @@ After you create a knowledge base, you can update its properties at any time. If
 
 ### Supported models
 
-Use one of the following LLMs from Azure OpenAI in Foundry Models or an equivalent open-source model. For deployment instructions, see [Deploy Microsoft Foundry Models in the Foundry portal](/azure/ai-foundry/how-to/deploy-models-openai).
+Use one of the following LLMs from Azure OpenAI in Foundry Models. For deployment instructions, see [Deploy Microsoft Foundry Models in the Foundry portal](/azure/ai-foundry/how-to/deploy-models-openai).
 
 + `gpt-4o`
 + `gpt-4o-mini`
@@ -234,7 +234,7 @@ Pass the following properties to create a knowledge base.
 | `RetrievalInstructions` | A prompt for the LLM to determine whether a knowledge source should be in scope for a query. Include this prompt when you have multiple knowledge sources. This field influences both knowledge source selection and query formulation. For example, instructions could append information or prioritize a knowledge source. Instructions are passed directly to the LLM, which means it's possible to provide instructions that break query planning, such as instructions that result in bypassing an essential knowledge source. | String | Yes |
 | `AnswerInstructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](../../agentic-retrieval-how-to-answer-synthesis.md). | String | Yes |
 | `OutputMode` | Valid values are `AnswerSynthesis` for an LLM-formulated answer or `ExtractedData` for full search results that you can pass to an LLM as a downstream step. | String | Yes |
-| `Models` | A connection to a [supported LLM](#supported-models) used for answer formulation or query planning. In this preview, `Models` can contain just one model, and the model provider must be Azure OpenAI. Obtain model information from the Foundry portal or a command-line request. Provide the parameters by using the [KnowledgeBaseAzureOpenAIModel class](/dotnet/api/azure.search.documents.indexes.models.knowledgebaseazureopenaimodel?view=azure-dotnet-preview&preserve-view=true). You can use role-based access control instead of API keys for the Azure AI Search connection to the model. For more information, see [How to deploy Azure OpenAI models with Foundry](/azure/ai-foundry/how-to/deploy-models-openai). | Object | No |
+| `Models` | A connection to a [supported LLM](#supported-models) used for answer formulation or query planning. In this preview, `Models` can contain just one model, and the model provider must be Azure OpenAI. Obtain model information from the Foundry portal or a command-line request. Provide the parameters by using the [KnowledgeBaseAzureOpenAIModel class](/dotnet/api/azure.search.documents.indexes.models.knowledgebaseazureopenaimodel?view=azure-dotnet-preview&preserve-view=true). You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Object | No |
 | `RetrievalReasoningEffort` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](../../agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
 
 ## Query a knowledge base

@@ -45,7 +45,7 @@ After you create a knowledge base, you can update its properties at any time. If
 
 ### Supported models
 
-Use one of the following LLMs from Azure OpenAI in Foundry Models or an equivalent open-source model. For deployment instructions, see [Deploy Microsoft Foundry Models in the Foundry portal](/azure/ai-foundry/how-to/deploy-models-openai).
+Use one of the following LLMs from Azure OpenAI in Foundry Models. For deployment instructions, see [Deploy Microsoft Foundry Models in the Foundry portal](/azure/ai-foundry/how-to/deploy-models-openai).
 
 + `gpt-4o`
 + `gpt-4o-mini`
@@ -201,7 +201,7 @@ Pass the following properties to create a knowledge base.
 | `answer_instructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](../../agentic-retrieval-how-to-answer-synthesis.md). | String | Yes |
 | `output_mode` | Valid values are `answer_synthesis` for an LLM-formulated answer or `extracted_data` for full search results that you can pass to an LLM as a downstream step. | String | Yes |
 | `knowledge_sources` | One or more [supported knowledge sources](../../agentic-knowledge-source-overview.md#supported-knowledge-sources). | Array | Yes |
-| `models` | A connection to a [supported LLM](#supported-models) used for answer formulation or query planning. In this preview, `models` can contain just one model, and the model provider must be Azure OpenAI. Obtain model information from the Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. For more information, see [How to deploy Azure OpenAI models with Foundry](/azure/ai-foundry/how-to/deploy-models-openai). | Object | No |
+| `models` | A connection to a [supported LLM](#supported-models) used for answer formulation or query planning. In this preview, `models` can contain just one model, and the model provider must be Azure OpenAI. Obtain model information from the Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Object | No |
 | `encryption_key` | A [customer-managed key](../../search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
 | `retrieval_reasoning_effort` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](../../agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
 

@@ -45,7 +45,7 @@ After you create a knowledge base, you can update its properties at any time. If
 
 ### Supported models
 
-Use one of the following LLMs from Azure OpenAI in Foundry Models or an equivalent open-source model. For deployment instructions, see [Deploy Microsoft Foundry Models in the Foundry portal](/azure/ai-foundry/how-to/deploy-models-openai).
+Use one of the following LLMs from Azure OpenAI in Foundry Models. For deployment instructions, see [Deploy Microsoft Foundry Models in the Foundry portal](/azure/ai-foundry/how-to/deploy-models-openai).
 
 + `gpt-4o`
 + `gpt-4o-mini`
@@ -195,7 +195,7 @@ Pass the following properties to create a knowledge base.
 | `answerInstructions` | Custom instructions to shape synthesized answers. The default is null. For more information, see [Use answer synthesis for citation-backed responses](../../agentic-retrieval-how-to-answer-synthesis.md). | String | Yes |
 | `outputMode` | Valid values are `answerSynthesis` for an LLM-formulated answer or `extractedData` for full search results that you can pass to an LLM as a downstream step. | String | Yes |
 | `knowledgeSources` | One or more [supported knowledge sources](../../agentic-knowledge-source-overview.md#supported-knowledge-sources). | Array | Yes |
-| `models` | A connection to a [supported LLM](#supported-models) used for answer formulation or query planning. In this preview, `models` can contain just one model, and the model provider must be Azure OpenAI. Obtain model information from the Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. For more information, see [How to deploy Azure OpenAI models with Foundry](/azure/ai-foundry/how-to/deploy-models-openai). | Object | No |
+| `models` | A connection to a [supported LLM](#supported-models) used for answer formulation or query planning. In this preview, `models` can contain just one model, and the model provider must be Azure OpenAI. Obtain model information from the Foundry portal or a command-line request. You can use role-based access control instead of API keys for the Azure AI Search connection to the model. | Object | No |
 | `encryptionKey` | A [customer-managed key](../../search-security-manage-encryption-keys.md) to encrypt sensitive information in both the knowledge base and the generated objects. | Object | No |
 | `retrievalReasoningEffort.kind` | Determines the level of LLM-related query processing. Valid values are `minimal`, `low` (default), and `medium`. For more information, see [Set the retrieval reasoning effort](../../agentic-retrieval-how-to-set-retrieval-reasoning-effort.md). | Object | No |
 

@@ -24,7 +24,7 @@ Although you can use your own data, this quickstart uses [sample JSON documents]
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-+ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md).
++ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md). This quickstart requires the Basic tier or higher for managed identity support.
 
 + A [Microsoft Foundry project](/azure/ai-foundry/how-to/create-projects) and resource. When you create a project, the resource is automatically created.
 

@@ -24,7 +24,7 @@ Although you can use your own data, this quickstart uses [sample JSON documents]
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-+ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md).
++ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md). This quickstart requires the Basic tier or higher for managed identity support.
 
 + A [Microsoft Foundry project](/azure/ai-foundry/how-to/create-projects) and resource. When you create a project, the resource is automatically created.
 

@@ -24,7 +24,7 @@ Although you can use your own data, this quickstart uses [sample JSON documents]
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-+ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md).
++ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md). This quickstart requires the Basic tier or higher for managed identity support.
 
 + A [Microsoft Foundry project](/azure/ai-foundry/how-to/create-projects) and resource. When you create a project, the resource is automatically created.
 

@@ -24,7 +24,7 @@ Although you can use your own data, this quickstart uses [sample JSON documents]
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-+ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md).
++ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md). This quickstart requires the Basic tier or higher for managed identity support.
 
 + A [Microsoft Foundry project](/azure/ai-foundry/how-to/create-projects) and resource. When you create a project, the resource is automatically created.
 

@@ -24,7 +24,7 @@ Although you can use your own data, this quickstart uses [sample JSON documents]
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-+ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md).
++ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md). This quickstart requires the Basic tier or higher for managed identity support.
 
 + A [Microsoft Foundry project](/azure/ai-foundry/how-to/create-projects) and resource. When you create a project, the resource is automatically created.
 
@@ -69,7 +69,7 @@ Although you can use your own data, this quickstart uses [sample JSON documents]
    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
    ```
 
-1. Replace the placeholder value for `@token` with the access token from the previous step.
+1. Replace the placeholder value for `@token` with the token from the previous step.
 
 ## Run the code
 

@@ -24,7 +24,7 @@ Although you can use your own data, this quickstart uses [sample JSON documents]
 
 + An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-+ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md).
++ An [Azure AI Search service](../../search-create-service-portal.md) in any [region that provides agentic retrieval](../../search-region-support.md). This quickstart requires the Basic tier or higher for managed identity support.
 
 + A [Microsoft Foundry project](/azure/ai-foundry/how-to/create-projects) and resource. When you create a project, the resource is automatically created.
 

@@ -63,7 +63,7 @@ Full-text search uses Apache Lucene for indexing and queries and the BM25 rankin
     az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv
     ```
 
-1. Replace the placeholder value for `@token` with the access token from the previous step.
+1. Replace the placeholder value for `@token` with the token from the previous step.
 
 ## Run the code
 

@@ -1,159 +0,0 @@
----
-manager: nitinme
-author: haileytap
-ms.author: haileytapia
-ms.service: azure-ai-search
-ms.topic: include
-ms.date: 01/15/2026
----
-
-> [!IMPORTANT]
-> The **Import data (new)** wizard now supports keyword search, which was previously only available in the **Import data** wizard. We recommend the new wizard for an improved search experience. For more information about how we're consolidating the wizards, see [Import data wizards in the Azure portal](../../search-import-data-portal.md).
-
-In this quickstart, you use the **Import data (new)** wizard and sample data about fictitious hotels to get started with [full-text search](../../search-lucene-query-architecture.md), also known as keyword search. The wizard requires no code to create an index, helping you write interesting queries within minutes.
-
-The wizard creates multiple objects on your search service, including a searchable index, an indexer, and a data source connection for automated data retrieval. At the end of this quickstart, you review each object.
-
-## Prerequisites
-
-+ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
-
-+ An [Azure AI Search service](../../search-create-service-portal.md). You can use a free service for this quickstart.
-
-+ An [Azure Storage account](/azure/storage/common/storage-account-create). Use Azure Blob Storage or Azure Data Lake Storage Gen2 (storage account with a hierarchical namespace) on a standard performance (general-purpose v2) account. To avoid bandwidth charges, use the same region as Azure AI Search.
-
-+ Familiarity with the wizard. See [Import data wizards in the Azure portal](../../search-import-data-portal.md).
-
-### Check for network access
-
-For this quickstart, all of the preceding resources must have public access enabled so that the Azure portal nodes can access them. Otherwise, the wizard fails. After the wizard runs, you can enable firewalls and private endpoints on the integration components for security. For more information, see [Secure connections in the import wizards](../../search-import-data-portal.md#secure-connections).
-
-### Check for space
-
-Many customers start with a free search service, which is limited to three indexes, three indexers, and three data sources. This quickstart creates one of each, so before you begin, make sure you have room for extra objects.
-
-On the **Overview** page, select **Usage** to see how many indexes, indexers, and data sources you currently have.
-
-   :::image type="content" source="../../media/search-get-started-portal/overview-quota-usage.png" alt-text="Screenshot of the Overview page for an Azure AI Search service instance in the Azure portal, showing the number of indexes, indexers, and data sources." lightbox="../../media/search-get-started-portal/overview-quota-usage.png":::
-
-## Prepare sample data
-
-This quickstart uses a JSON document that contains metadata for 50 fictitious hotels, but you can also use your own files.
-
-To prepare the sample data for this quickstart:
-
-1. Download the `HotelsData_toAzureBlobs.json` file from the [azure-search-sample-data](https://github.com/Azure-Samples/azure-search-sample-data/blob/main/hotels/HotelsData_toAzureBlobs.json) repo.
-
-1. Sign in to the [Azure portal](https://portal.azure.com/) and select your Azure Storage account.
-
-1. From the left pane, select **Data storage** > **Containers**.
-
-1. Create a container named **hotels-sample**.
-
-1. Upload the `HotelsData_toAzureBlobs.json` file to the container.
-
-## Run the wizard
-
-The wizard walks you through several configuration steps. This section covers each step in sequence.
-
-### Start the wizard
-
-To start the wizard for this quickstart:
-
-1. Sign in to the [Azure portal](https://portal.azure.com/) and select your search service.
-
-1. On the **Overview** page, select **Import data (new)**.
-
-   :::image type="content" source="../../media/search-import-data-portal/import-data-new-button.png" alt-text="Screenshot that shows how to open the new import wizard in the Azure portal.":::
-
-1. Select your data source: **Azure Blob Storage** or **Azure Data Lake Storage Gen2**.
-
-   :::image type="content" source="../../media/search-get-started-portal-images/select-data-source.png" alt-text="Screenshot of the options for selecting a data source in the wizard." border="true" lightbox="../../media/search-get-started-portal-images/select-data-source.png":::
-
-1. Select **Keyword search**.
-
-   :::image type="content" source="../../media/search-get-started-portal/keyword-search-tile.png" alt-text="Screenshot of the keyword search tile in the Azure portal." border="true" lightbox="../../media/search-get-started-portal/keyword-search-tile.png":::
-
-### Connect to a data source
-
-Azure AI Search requires a connection to a data source for content ingestion and indexing. In this case, the data source is your Azure Storage account.
-
-To connect to the sample data:
-
-1. On the **Connect to your data** page, select your Azure subscription.
-
-1. Select your storage account, and then select the **hotels-sample** container.
-
-1. Select **JSON array** for the parsing mode.
-
-   :::image type="content" source="../../media/search-get-started-portal/connect-to-your-data.png" alt-text="Screenshot of the Connect to your data page in the Azure portal." lightbox="../../media/search-get-started-portal/connect-to-your-data.png":::
-
-1. Select **Next**.
-
-### Skip AI enrichment
-
-The wizard supports skillset creation and [AI enrichment](../../cognitive-search-concept-intro.md) during indexing, which are beyond the scope of this quickstart. Skip this step by selecting **Next**.
-
-> [!TIP]
-> For a similar walkthrough that focuses on AI enrichment, see [Quickstart: Create a skillset in the Azure portal](../../search-get-started-skillset.md).
-
-### Configure the index
-
-Based on the structure and content of the sample hotel data, the wizard infers a schema for your search index.
-
-To configure the index:
-
-1. For each of the following fields, select **Configure field**, and then set the respective attributes.
-
-   | Fields | Attributes |
-   |-------|------------|
-   | `HotelId` | Key, Retrievable, Filterable, Sortable, Searchable |
-   | `HotelName`, `Category` | Retrievable, Filterable, Sortable, Searchable |
-   | `Description`, `Description_fr` | Retrievable, Searchable |
-   | `Tags` | Retrievable, Filterable, Searchable |
-   | `ParkingIncluded`, `IsDeleted` | Retrievable, Filterable, Facetable |
-   | `LastRenovationDate`, `Rating`, `Location` | Retrievable, Filterable, Sortable |
-   | `Address.StreetAddress`, `Rooms.Description`, `Rooms.Description_fr` | Retrievable, Searchable |
-   | `Address.City`, `Address.StateProvince`, `Address.PostalCode`, `Address.Country` | Retrievable, Filterable, Facetable, Searchable, Sortable|
-   | `Rooms.Type`, `Rooms.BedOptions`, `Rooms.Tags` | Retrievable, Filterable, Facetable, Searchable |
-   | `Rooms.BaseRate`, `Rooms.SleepsCount`, `Rooms.SmokingAllowed` | Retrievable, Filterable, Facetable |
-
-   :::image type="content" source="../../media/search-get-started-portal/configure-index.gif" alt-text="GIF that shows how to configure attributes for fields in the index." lightbox="../../media/search-get-started-portal/configure-index.gif":::
-
-1. Select **Next**.
-
-At a minimum, the index requires a name and a collection of fields. The wizard scans for unique string fields and marks one as the document key, which uniquely identifies each document in the index.
-
-Each field has a name, [data type](/rest/api/searchservice/supported-data-types), and attributes that control how the field is used in the index. You can enable or disable the following attributes:
-
-| Attribute | Description | Applicable data types |
-|-----------|-------------|------------------------|
-| Retrievable | Fields returned in a query response. | Strings and integers |
-| Filterable | Fields that accept a filter expression. | Strings and integers |
-| Sortable | Fields that accept an orderby expression. | Strings and integers |
-| Facetable | Fields used in a faceted navigation structure. | Strings and integers |
-| Searchable | Fields used in full-text search. Strings are searchable, but numeric and Boolean fields are often marked as not searchable. | Strings |
-
-Attributes affect storage in different ways. For example, filterable fields consume extra storage, while retrievable fields don't. For more information about attributes and data types, see [Configure field definitions](/azure/search/search-how-to-create-search-index#configure-field-definitions).
-
-If you want autocomplete or suggested queries, specify **Suggesters**.
-
-### Skip advanced settings
-
-The wizard offers advanced settings for semantic ranking and index scheduling, which are beyond the scope of this quickstart. Skip this step by selecting **Next**.
-
-### Finish the wizard
-
-The last step is to review your configuration and create the index, indexer, and data source on your search service. The indexer automates the process of extracting content from your data source and loading it into the index, enabling keyword search.
-
-To finish the wizard:
-
-1. Change the object name prefix to **hotels-sample**.
-
-1. Review the object configurations.
-
-   :::image type="content" source="../../media/search-get-started-portal/review-and-create.png" alt-text="Screenshot of the object configuration page in the Azure portal." lightbox="../../media/search-get-started-portal/review-and-create.png":::
-
-   AI enrichment, semantic ranker, and indexer scheduling are either disabled or set to their default values because you skipped their wizard steps.
-
-1. Select **Create** to simultaneously create the objects and run the indexer.

@@ -68,7 +68,7 @@ In Azure AI Search, a vector index has an index schema that defines vector and n
     az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv
     ```
 
-1. Replace the placeholder value for `@token` with the access token from the previous step.
+1. Replace the placeholder value for `@token` with the token from the previous step.
 
 ## Run the code
 

@@ -74,6 +74,12 @@ In Azure AI Search, a vector index has an index schema that defines vector and n
 
    When the installation completes, you should see a `node_modules` folder in the project directory.
 
+1. Build the TypeScript files.
+
+   ```bash
+   npm run build
+   ```
+
 1. For keyless authentication with Microsoft Entra ID, sign in to your Azure account. If you have multiple subscriptions, select the one that contains your Azure AI Search service.
 
    ```azurecli
@@ -85,32 +91,32 @@ In Azure AI Search, a vector index has an index schema that defines vector and n
 1. Create a vector index.
 
     ```bash
-    npm run build && node -r dotenv/config dist/createIndex.js
+    node -r dotenv/config dist/createIndex.js
     ```
 
 1. Load documents that contain precomputed embeddings.
 
     ```bash
-    npm run build && node -r dotenv/config dist/uploadDocuments.js
+    node -r dotenv/config dist/uploadDocuments.js
     ```
 
 1. Run a vector search query.
 
     ```bash
-    npm run build && node -r dotenv/config dist/searchSingle.js
+    node -r dotenv/config dist/searchSingle.js
     ```
 
 1. (Optional) Run additional query variations.
 
     ```bash
-    npm run build && node -r dotenv/config dist/searchSingleWithFilter.js
-    npm run build && node -r dotenv/config dist/searchSingleWithFilterGeo.js
-    npm run build && node -r dotenv/config dist/searchHybrid.js
-    npm run build && node -r dotenv/config dist/searchSemanticHybrid.js
+    node -r dotenv/config dist/searchSingleWithFilter.js
+    node -r dotenv/config dist/searchSingleWithFilterGeo.js
+    node -r dotenv/config dist/searchHybrid.js
+    node -r dotenv/config dist/searchSemanticHybrid.js
     ```
 
-> [!NOTE]
-> The `npm run build` command compiles the TypeScript files in `src/` to JavaScript in `dist/`.
+    > [!NOTE]
+    > These commands run `.js` files from the `dist` folder because you previously transpiled from TypeScript to JavaScript with `npm run build`.
 
 ### Output
 

@@ -4,442 +4,377 @@ ms.author: haileytapia
 ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
+  - dev-focus
 ms.topic: include
-ms.date: 11/20/2025
+ms.date: 03/04/2026
+ai-usage: ai-assisted
 ---
 
-[!INCLUDE [Semantic ranker introduction](semantic-ranker-intro.md)]
+In this quickstart, you use the [Azure AI Search client library for .NET](/dotnet/api/overview/azure/search) to add [semantic ranking](../../semantic-search-overview.md) to an existing search index and query the index.
 
-## Set up the client
+Semantic ranking is query-side functionality that uses machine reading comprehension to rescore search results, promoting the most semantically relevant matches to the top of the list. You can add a semantic configuration to an existing index with no rebuild requirement. Semantic ranking is most effective for informational or descriptive text.
 
-In this quickstart, you use an IDE and the [**Azure.Search.Documents**](/dotnet/api/overview/azure/search.documents-readme) client library to add semantic ranking to an existing search index.
+> [!TIP]
+> Want to get started right away? Download the [source code](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-semantic-ranking) on GitHub.
 
-We recommend [Visual Studio](https://visualstudio.microsoft.com/vs/community/) for this quickstart.
+## Prerequisites
 
-> [!TIP]
-> You can download the [source code](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-semantic-ranking) to start with a finished project or follow these steps to create your own.
++ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-### Install libraries
++ An [Azure AI Search service](../../search-create-service-portal.md) with [semantic ranker enabled](../../semantic-how-to-enable-disable.md).
 
-1. Start Visual Studio and open the [quickstart-semantic-ranking.sln](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-semantic-ranking) or create a new project using a console application template.
++ An [index](../../search-how-to-create-search-index.md) with descriptive text fields attributed as `searchable` and `retrievable`.  This quickstart assumes the [hotels-sample index](../../search-get-started-portal.md).
 
-1. In **Tools** > **NuGet Package Manager**, select **Manage NuGet Packages for Solution...**.
++ [.NET 9](https://dotnet.microsoft.com/download) or later.
 
-1. Select **Browse**.
++ [Visual Studio Code](https://code.visualstudio.com/download).
 
-1. Search for the [Azure.Search.Documents package](https://www.nuget.org/packages/Azure.Search.Documents/) and select the latest stable version.
++ [Git](https://git-scm.com/downloads) to clone the sample repository.
 
-1. Search for the [Azure.Identity package](https://www.nuget.org/packages/Azure.Identity) and select the latest stable version.
++ The [Azure CLI](/cli/azure/install-azure-cli) for keyless authentication with Microsoft Entra ID.
 
-1. Select **Install** to add the assembly to your project and solution.
+## Configure access
 
-### Sign in to Azure
+[!INCLUDE [resource authentication](../resource-authentication-semantic.md)]
 
-If you signed in to the [Azure portal](https://portal.azure.com), you're signed into Azure. If you aren't sure, use the Azure CLI or Azure PowerShell to log in: `az login` or `az connect`. If you have multiple tenants and subscriptions, see [Quickstart: Connect without keys](../../search-get-started-rbac.md) for help on how to connect.
+## Get endpoint
 
-## Update the index
+[!INCLUDE [resource endpoint](../resource-endpoint.md)]
 
-In this section, you update a search index to include a semantic configuration. The code gets the index definition from the search service and adds a semantic configuration.
+## Start with an index
 
-1. Open the [BuildIndex project](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-semantic-ranking/BuildIndex) in Visual Studio. The program consists of the following code.
+[!INCLUDE [start with an index](semantic-ranker-index.md)]
 
-   This code uses a SearchIndexClient to update an index on your search service.
+## Set up the environment
 
-    ```csharp
-    class BuildIndex
-    {
-        static async Task Main(string[] args)
-        {
-            string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
-            string indexName = "hotels-sample-index";
-            string endpoint = $"https://{searchServiceName}.search.windows.net";
-            var credential = new Azure.Identity.DefaultAzureCredential();
-    
-            await ListIndexesAsync(endpoint, credential);
-            await UpdateIndexAsync(endpoint, credential, indexName);
-        }
-    
-        // Print a list of all indexes on the search service
-        // You should see hotels-sample-index in the list
-        static async Task ListIndexesAsync(string endpoint, Azure.Core.TokenCredential credential)
-        {
-            try
-            {
-                var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
-                    new Uri(endpoint),
-                    credential
-                );
-    
-                var indexes = indexClient.GetIndexesAsync();
-    
-                Console.WriteLine("Here's a list of all indexes on the search service. You should see hotels-sample-index:");
-                await foreach (var index in indexes)
-                {
-                    Console.WriteLine(index.Name);
-                }
-                Console.WriteLine(); // Add an empty line for readability
-            }
-            catch (Exception ex)
-            {
-                Console.WriteLine($"Error listing indexes: {ex.Message}");
-            }
-        }
-    
-        static async Task UpdateIndexAsync(string endpoint, Azure.Core.TokenCredential credential, string indexName)
-        {
-            try
-            {
-                var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
-                    new Uri(endpoint),
-                    credential
-                );
-    
-                // Get the existing definition of hotels-sample-index
-                var indexResponse = await indexClient.GetIndexAsync(indexName);
-                var index = indexResponse.Value;
-    
-                // Add a semantic configuration
-                const string semanticConfigName = "semantic-config";
-                AddSemanticConfiguration(index, semanticConfigName);
-    
-                // Update the index with the new information
-                var updatedIndex = await indexClient.CreateOrUpdateIndexAsync(index);
-                Console.WriteLine("Index updated successfully.");
-    
-                // Print the updated index definition as JSON
-                var refreshedIndexResponse = await indexClient.GetIndexAsync(indexName);
-                var refreshedIndex = refreshedIndexResponse.Value;
-                var jsonOptions = new JsonSerializerOptions { WriteIndented = true };
-                string indexJson = JsonSerializer.Serialize(refreshedIndex, jsonOptions);
-                Console.WriteLine($"Here is the revised index definition:\n{indexJson}");
-            }
-            catch (Exception ex)
-            {
-                Console.WriteLine($"Error updating index: {ex.Message}");
-            }
-        }
-    
-        // This is the semantic configuration definition
-        static void AddSemanticConfiguration(SearchIndex index, string semanticConfigName)
-        {
-            if (index.SemanticSearch == null)
-            {
-                index.SemanticSearch = new SemanticSearch();
-            }
-            var configs = index.SemanticSearch.Configurations;
-            if (configs == null)
-            {
-                throw new InvalidOperationException("SemanticSearch.Configurations is null and cannot be assigned. Your service must be Basic tier or higher.");
-            }
-            if (!configs.Any(c => c.Name == semanticConfigName))
-            {
-                var prioritizedFields = new SemanticPrioritizedFields
-                {
-                    TitleField = new SemanticField("HotelName"),
-                    ContentFields = { new SemanticField("Description") },
-                    KeywordsFields = { new SemanticField("Tags") }
-                };
-    
-                configs.Add(
-                    new SemanticConfiguration(
-                        semanticConfigName,
-                        prioritizedFields
-                    )
-                );
-                Console.WriteLine($"Added new semantic configuration '{semanticConfigName}' to the index definition.");
-            }
-            else
-            {
-                Console.WriteLine($"Semantic configuration '{semanticConfigName}' already exists in the index definition.");
-            }
-            index.SemanticSearch.DefaultConfigurationName = semanticConfigName;
-        }
-    }
+1. Use Git to clone the sample repository.
+
+    ```bash
+    git clone https://github.com/Azure-Samples/azure-search-dotnet-samples
     ```
 
-1. Replace the search service URL with a valid endpoint.
+1. Navigate to the quickstart folder and open it in Visual Studio Code.
 
-1. Run the program.
+    ```bash
+    cd azure-search-dotnet-samples/quickstart-semantic-ranking
+    code .
+    ```
 
-1. Output is logged to a console window from [Console.WriteLine](/dotnet/api/system.console.writeline). You should see messages for each step, including the JSON of the index schema with the new semantic configuration included.
+1. In `BuildIndex/Program.cs`, replace the placeholder value for `endpoint` with the URL you obtained in [Get endpoint](#get-endpoint).
 
-## Run semantic queries
+1. Repeat the previous step for `QueryIndex/Program.cs`.
 
-In this section, the program runs several semantic queries in sequence.
+1. For keyless authentication with Microsoft Entra ID, sign in to your Azure account. If you have multiple subscriptions, select the one that contains your Azure AI Search service.
 
-1. Open the [QueryIndex project](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/main/quickstart-semantic-ranking/QueryIndex) in Visual Studio. The program consists of the following code.
+    ```azurecli
+    az login
+    ```
 
-   This code uses a SearchClient for sending queries to an index.
+## Run the code
 
-    ```csharp
-    class SemanticQuery
-    {
-        static async Task Main(string[] args)
-        {
-            string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
-            string indexName = "hotels-sample-index";
-            string endpoint = $"https://{searchServiceName}.search.windows.net";
-            var credential = new Azure.Identity.DefaultAzureCredential();
-    
-            var client = new SearchClient(new Uri(endpoint), indexName, credential);
-    
-            // Query 1: Simple query
-            string searchText = "walking distance to live music";
-            Console.WriteLine("\nQuery 1: Simple query using the search string 'walking distance to live music'.");
-            await RunQuery(client, searchText, new SearchOptions
-            {
-                Size = 5,
-                QueryType = SearchQueryType.Simple,
-                IncludeTotalCount = true,
-                Select = { "HotelId", "HotelName", "Description" }
-            });
-            Console.WriteLine("Press Enter to continue to the next query...");
-            Console.ReadLine();
-    
-            // Query 2: Semantic query (no captions, no answers)
-            Console.WriteLine("\nQuery 2: Semantic query (no captions, no answers) for 'walking distance to live music'.");
-            var semanticOptions = new SearchOptions
-            {
-                Size = 5,
-                QueryType = SearchQueryType.Semantic,
-                SemanticSearch = new SemanticSearchOptions
-                {
-                    SemanticConfigurationName = "semantic-config"
-                },
-                IncludeTotalCount = true,
-                Select = { "HotelId", "HotelName", "Description" }
-            };
-            await RunQuery(client, searchText, semanticOptions);
-            Console.WriteLine("Press Enter to continue to the next query...");
-            Console.ReadLine();
-    
-            // Query 3: Semantic query with captions
-            Console.WriteLine("\nQuery 3: Semantic query with captions.");
-            var captionsOptions = new SearchOptions
-            {
-                Size = 5,
-                QueryType = SearchQueryType.Semantic,
-                SemanticSearch = new SemanticSearchOptions
-                {
-                    SemanticConfigurationName = "semantic-config",
-                    QueryCaption = new QueryCaption(QueryCaptionType.Extractive)
-                    {
-                        HighlightEnabled = true
-                    }
-                },
-                IncludeTotalCount = true,
-                Select = { "HotelId", "HotelName", "Description" }
-            };
-            // Add the field(s) you want captions for to the QueryCaption.Fields collection
-            captionsOptions.HighlightFields.Add("Description");
-            await RunQuery(client, searchText, captionsOptions, showCaptions: true);
-            Console.WriteLine("Press Enter to continue to the next query...");
-            Console.ReadLine();
-    
-            // Query 4: Semantic query with answers
-            // This query uses different search text designed for an answers scenario
-            string searchText2 = "what's a good hotel for people who like to read";
-            searchText = searchText2; // Update searchText for the next query
-            Console.WriteLine("\nQuery 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.");
-            var answersOptions = new SearchOptions
-            {
-                Size = 5,
-                QueryType = SearchQueryType.Semantic,
-                SemanticSearch = new SemanticSearchOptions
-                {
-                    SemanticConfigurationName = "semantic-config",
-                    QueryAnswer = new QueryAnswer(QueryAnswerType.Extractive)
-                },
-                IncludeTotalCount = true,
-                Select = { "HotelId", "HotelName", "Description" }
-            };
-            await RunQuery(client, searchText2, answersOptions, showAnswers: true);
-    
-            static async Task RunQuery(
-            SearchClient client,
-            string searchText,
-            SearchOptions options,
-            bool showCaptions = false,
-            bool showAnswers = false)
-            {
-                try
-                {
-                    var response = await client.SearchAsync<SearchDocument>(searchText, options);
-    
-                    if (showAnswers && response.Value.SemanticSearch?.Answers != null)
-                    {
-                        Console.WriteLine("Extractive Answers:");
-                        foreach (var answer in response.Value.SemanticSearch.Answers)
-                        {
-                            Console.WriteLine($"  {answer.Highlights}");
-                        }
-                        Console.WriteLine(new string('-', 40));
-                    }
-    
-                    await foreach (var result in response.Value.GetResultsAsync())
-                    {
-                        var doc = result.Document;
-                        // Print captions first if available
-                        if (showCaptions && result.SemanticSearch?.Captions != null)
-                        {
-                            foreach (var caption in result.SemanticSearch.Captions)
-                            {
-                                Console.WriteLine($"Caption: {caption.Highlights}");
-                            }
-                        }
-                        Console.WriteLine($"HotelId: {doc.GetString("HotelId")}");
-                        Console.WriteLine($"HotelName: {doc.GetString("HotelName")}");
-                        Console.WriteLine($"Description: {doc.GetString("Description")}");
-                        Console.WriteLine($"@search.score: {result.Score}");
-    
-                        // Print @search.rerankerScore if available
-                        if (result.SemanticSearch != null && result.SemanticSearch.RerankerScore.HasValue)
-                        {
-                            Console.WriteLine($"@search.rerankerScore: {result.SemanticSearch.RerankerScore.Value}");
-                        }
-                        Console.WriteLine(new string('-', 40));
-                    }
-                }
-                catch (Exception ex)
-                {
-                    Console.WriteLine($"Error querying index: {ex.Message}");
-                }
-            }
-        }
-    }
+1. Run the first project to update the index with a semantic configuration.
+
+    ```bash
+    dotnet run --project BuildIndex
     ```
 
-1. Replace the search service URL with a valid endpoint.
+1. Run the second project to query the index. Press **Enter** between queries to see the progression from simple query to semantic query with captions and answers.
 
-1. Run the program.
+    ```bash
+    dotnet run --project QueryIndex
+    ```
 
-1. Output is logged to a console window from [Console.WriteLine](/dotnet/api/system.console.writeline). You should see search results for each query.
+### Output
+
+The first project updates the hotels-sample index with a semantic configuration. The output includes confirmation of the semantic configuration.
+
+```output
+Here's a list of all indexes on the search service. You should see hotels-sample:
+hotels-sample
+
+Added new semantic configuration 'semantic-config' to the index definition.
+Index updated successfully.
+Here is the revised index definition:
+{
+  "Name": "hotels-sample",
+  ... // Trimmed for brevity
+  "SemanticSearch": {
+    "DefaultConfigurationName": "semantic-config",
+    "Configurations": [
+      {
+        "Name": "hotels-sample-semantic-configuration",
+        ... // Trimmed for brevity
+      },
+      {
+        "Name": "semantic-config",
+        "PrioritizedFields": {
+          "TitleField": {
+            "FieldName": "HotelName"
+          },
+          "ContentFields": [
+            {
+              "FieldName": "Description"
+            }
+          ],
+          "KeywordsFields": [
+            {
+              "FieldName": "Tags"
+            }
+          ]
+        },
+        "RankingOrder": {}
+      }
+    ]
+  }
+}
+```
 
-### Output for semantic query (no captions or answers)
+The second project runs four queries. The output includes the search results with relevance scores, captions, and answers.
 
-This output is from the semantic query, with no captions or answers. The query string is 'walking distance to live music'.
+```output
+Query 1: Simple query using the search string 'walking distance to live music'.
+HotelId: 2
+HotelName: Old Century Hotel
+Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
+@search.score: 5.004435
+----------------------------------------
+HotelId: 24
+HotelName: Uptown Chic Hotel
+Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
+@search.score: 4.555706
+----------------------------------------
+... // Trimmed for brevity
+Press Enter to continue to the next query...
 
-Here, the initial results from the term query are rescored using the semantic ranking models. For this particular dataset and query, the first several results are in similar positions. The effects of semantic ranking are more pronounced in the remainder of the results.
 
-```bash
+Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
 HotelId: 24
 HotelName: Uptown Chic Hotel
 Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
-@search.score: 5.074317
+@search.score: 4.555706
 @search.rerankerScore: 2.613231658935547
 ----------------------------------------
 HotelId: 2
 HotelName: Old Century Hotel
 Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
-@search.score: 5.5153193
+@search.score: 5.004435
 @search.rerankerScore: 2.271434783935547
 ----------------------------------------
-HotelId: 4
-HotelName: Sublime Palace Hotel
-Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
-@search.score: 4.8959594
-@search.rerankerScore: 1.9861756563186646
-----------------------------------------
-HotelId: 39
-HotelName: White Mountain Lodge & Suites
-Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
-@search.score: 0.7334347
-@search.rerankerScore: 1.9615401029586792
-----------------------------------------
-HotelId: 15
-HotelName: By the Market Hotel
-Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
-@search.score: 1.5502293
-@search.rerankerScore: 1.9085469245910645
-----------------------------------------
+... // Trimmed for brevity
 Press Enter to continue to the next query...
-```
 
-### Output for a semantic query with captions
 
-Here are the results for the query that adds captions with hit highlighting.
-
-```
+Query 3: Semantic query with captions.
 Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
 HotelId: 24
 HotelName: Uptown Chic Hotel
 Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
-@search.score: 5.074317
+@search.score: 4.555706
 @search.rerankerScore: 2.613231658935547
 ----------------------------------------
-Caption:
-HotelId: 2
-HotelName: Old Century Hotel
-Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
-@search.score: 5.5153193
-@search.rerankerScore: 2.271434783935547
-----------------------------------------
-Caption: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within<em> short walking distance </em>to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort,.
-HotelId: 4
-HotelName: Sublime Palace Hotel
-Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
-@search.score: 4.8959594
-@search.rerankerScore: 1.9861756563186646
-----------------------------------------
-Caption: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend<em> evening entertainment </em>on the patio features special<em> guest musicians </em>or.
-HotelId: 39
-HotelName: White Mountain Lodge & Suites
-Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
-@search.score: 0.7334347
-@search.rerankerScore: 1.9615401029586792
-----------------------------------------
-Caption: Book now and Save up to 30%. Central location. <em>Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood.</em> Brand new rooms. Impeccable service.
-HotelId: 15
-HotelName: By the Market Hotel
-Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
-@search.score: 1.5502293
-@search.rerankerScore: 1.9085469245910645
-----------------------------------------
+... // Trimmed for brevity
 Press Enter to continue to the next query...
+
+
+Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
+Extractive Answers:
+  Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
+----------------------------------------
+... // Trimmed for brevity
 ```
 
-### Output for semantic answers
+## Understand the code
 
-The final query returns a semantic answer. Notice that we changed the query string for this example: 'what's a good hotel for people who like to read'.
+[!INCLUDE [understand code note](../understand-code-note.md)]
 
-Semantic ranker can produce an answer to a query string that has the characteristics of a question. The generated answer is extracted verbatim from your content so it won't include composed content like what you might expect from a chat completion model. If the semantic answer isn't useful for your scenario, you can omit `semantic_answers` from your code.
+Now that you've run the code, let's break down the key steps:
 
-To produce a semantic answer, the question and answer must be closely aligned, and the model must find content that clearly answers the question. If potential answers fail to meet a confidence threshold, the model doesn't return an answer. For demonstration purposes, the question in this example is designed to get a response so that you can see the syntax.
+1. [Configuration and authentication](#configuration-and-authentication)
+1. [Update the index with a semantic configuration](#update-the-index-with-a-semantic-configuration)
+1. [Query the index](#query-the-index)
 
-Recall that answers are *verbatim content* pulled from your index and might be missing phrases that a user would expect to see. To get *composed answers* as generated by a chat completion model, considering using a [RAG pattern](../../retrieval-augmented-generation-overview.md) or [agentic retrieval](../../agentic-retrieval-overview.md).
+### Configuration and authentication
 
-```bash
-Extractive Answers:
-  Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
-----------------------------------------
-HotelId: 1
-HotelName: Stay-Kay City Hotel
-Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
-@search.score: 2.0361428
-@search.rerankerScore: 2.124817371368408
-----------------------------------------
-HotelId: 16
-HotelName: Double Sanctuary Resort
-Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
-@search.score: 3.759768
-@search.rerankerScore: 2.0705394744873047
-----------------------------------------
-HotelId: 38
-HotelName: Lakeside B & B
-Description: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
-@search.score: 0.7308748
-@search.rerankerScore: 2.041472911834717
-----------------------------------------
-HotelId: 2
-HotelName: Old Century Hotel
-Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
-@search.score: 3.391012
-@search.rerankerScore: 2.0231292247772217
-----------------------------------------
-HotelId: 15
-HotelName: By the Market Hotel
-Description: Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
-@search.score: 1.3198771
-@search.rerankerScore: 2.021622657775879
-----------------------------------------
+Both projects share the same configuration pattern. The `Program.cs` files define the search endpoint and use `DefaultAzureCredential` for keyless authentication.
+
+```csharp
+var endpoint = new Uri("PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE");
+var credential = new DefaultAzureCredential();
+var indexClient = new SearchIndexClient(endpoint, credential);
+```
+
+Key takeaways:
+
++ `DefaultAzureCredential` provides keyless authentication using Microsoft Entra ID. It chains multiple credential types, including the Azure CLI credential from `az login`.
++ `SearchIndexClient` manages index-level operations, such as updating the index schema.
++ `SearchClient` handles document-level operations, such as querying the index.
+
+### Update the index with a semantic configuration
+
+The following code in `BuildIndex/Program.cs` adds a semantic configuration to the existing index. This operation doesn't delete any search documents, and your index remains operational after the configuration is added.
+
+```csharp
+static void AddSemanticConfiguration(
+    SearchIndex index,
+    string semanticConfigName)
+{
+    if (index.SemanticSearch == null)
+    {
+        index.SemanticSearch = new SemanticSearch();
+    }
+    var configs = index.SemanticSearch.Configurations;
+    if (!configs.Any(c => c.Name == semanticConfigName))
+    {
+        var prioritizedFields =
+            new SemanticPrioritizedFields
+        {
+            TitleField = new SemanticField("HotelName"),
+            ContentFields =
+            {
+                new SemanticField("Description")
+            },
+            KeywordsFields =
+            {
+                new SemanticField("Tags")
+            }
+        };
+
+        configs.Add(
+            new SemanticConfiguration(
+                semanticConfigName,
+                prioritizedFields
+            )
+        );
+    }
+    index.SemanticSearch.DefaultConfigurationName =
+        semanticConfigName;
+}
 ```
+
+Key takeaways:
+
++ A semantic configuration specifies the fields used for semantic ranking.
++ Semantic configurations can be added to existing indexes without rebuilding.
++ `TitleField` sets the field that represents the document title.
++ `ContentFields` sets the fields containing the main content.
++ `KeywordsFields` sets the fields containing keywords or tags.
+
+### Query the index
+
+The `QueryIndex` project runs four queries in sequence, progressing from a simple keyword search to semantic ranking with captions and answers.
+
+#### Simple query
+
+The first query is a simple keyword search that doesn't use semantic ranking. This query serves as a baseline for comparing results with and without semantic reranking.
+
+```csharp
+await RunQuery(client, searchText, new SearchOptions
+{
+    Size = 5,
+    QueryType = SearchQueryType.Simple,
+    IncludeTotalCount = true,
+    Select = { "HotelId", "HotelName", "Description" }
+});
+```
+
+Key takeaways:
+
++ `SearchQueryType.Simple` uses the default BM25 ranking algorithm.
++ Results are ranked by keyword relevance (`@search.score`) only.
+
+#### Semantic query (no captions, no answers)
+
+The next query adds semantic ranking with no captions or answers. The following code shows the minimum requirement for invoking semantic ranking.
+
+```csharp
+var semanticOptions = new SearchOptions
+{
+    Size = 5,
+    QueryType = SearchQueryType.Semantic,
+    SemanticSearch = new SemanticSearchOptions
+    {
+        SemanticConfigurationName = "semantic-config"
+    },
+    IncludeTotalCount = true,
+    Select =
+    {
+        "HotelId", "HotelName", "Description"
+    }
+};
+await RunQuery(client, searchText, semanticOptions);
+```
+
+Key takeaways:
+
++ `SearchQueryType.Semantic` enables semantic ranking on the query.
++ `SemanticConfigurationName` specifies which semantic configuration to use.
++ `@search.rerankerScore` indicates semantic relevance (higher is better).
++ The initial results from the term query are rescored using semantic ranking models. For this dataset and query, the effects of semantic ranking are more pronounced in the lower-ranked results.
+
+#### Semantic query with captions
+
+The following code adds captions to extract the most relevant passages from each result, with hit highlighting applied to the important terms and phrases.
+
+```csharp
+var captionsOptions = new SearchOptions
+{
+    Size = 5,
+    QueryType = SearchQueryType.Semantic,
+    SemanticSearch = new SemanticSearchOptions
+    {
+        SemanticConfigurationName = "semantic-config",
+        QueryCaption =
+            new QueryCaption(QueryCaptionType.Extractive)
+        {
+            HighlightEnabled = true
+        }
+    },
+    IncludeTotalCount = true,
+    Select =
+    {
+        "HotelId", "HotelName", "Description"
+    }
+};
+captionsOptions.HighlightFields.Add("Description");
+await RunQuery(
+    client, searchText, captionsOptions, showCaptions: true
+);
+```
+
+Key takeaways:
+
++ `QueryCaption` enables extractive captions from the content fields.
++ Captions surface the most relevant passages and add `<em>` tags around important terms.
+
+#### Semantic query with answers
+
+The final query adds semantic answers. This query uses a different search string (`searchText2`) because semantic answers work best when the query is phrased as a question. The answer is a verbatim passage extracted from your index, not a composed response from a chat completion model.
+
+The query and the indexed content must be closely aligned for an answer to be returned. If no candidate meets the confidence threshold, the response doesn't include an answer. This example uses a question that's known to produce a result so that you can see the syntax. If answers aren't useful for your scenario, omit `QueryAnswer` from your code. For composed answers, consider a [RAG pattern](../../retrieval-augmented-generation-overview.md) or [agentic retrieval](../../agentic-retrieval-overview.md).
+
+```csharp
+var answersOptions = new SearchOptions
+{
+    Size = 5,
+    QueryType = SearchQueryType.Semantic,
+    SemanticSearch = new SemanticSearchOptions
+    {
+        SemanticConfigurationName = "semantic-config",
+        QueryAnswer =
+            new QueryAnswer(QueryAnswerType.Extractive)
+    },
+    IncludeTotalCount = true,
+    Select =
+    {
+        "HotelId", "HotelName", "Description"
+    }
+};
+await RunQuery(
+    client, searchText2, answersOptions, showAnswers: true
+);
+```
+
+Key takeaways:
+
++ `QueryAnswer` enables extractive answers for question-like queries.
++ Answers are verbatim content extracted from your index, not generated text.

@@ -0,0 +1,69 @@
+---
+manager: nitinme
+author: haileytap
+ms.author: haileytapia
+ms.service: azure-ai-search
+ms.topic: include
+ms.date: 03/04/2026
+---
+
+This quickstart modifies an existing index to include a semantic configuration. We recommend the hotels-sample index, which you can create in minutes using an Azure portal wizard.
+
+To use a different index, replace the index name, field names in the semantic configuration, and field names in query `select` statements throughout the sample code. Your index should contain descriptive text fields that are attributed as `searchable` and `retrievable`.
+
+To review and query the hotels-sample index before semantic ranking:
+
+1. Sign in to the [Azure portal](https://portal.azure.com/) and select your search service.
+
+1. From the left pane, select **Search management** > **Indexes**.
+
+1. Select **hotels-sample**.
+
+1. Select **Semantic configurations** to view any existing configurations. If you enabled semantic ranking during the wizard creation flow, there should be a default configuration.
+
+   :::image type="content" source="../../media/search-get-started-semantic/default-semantic-configuration.png" alt-text="Screenshot of the default semantic configuration in the Azure portal." lightbox="../../media/search-get-started-semantic/default-semantic-configuration.png":::
+
+1. Select **Search explorer**, and then select **View** > **JSON view**.
+
+1. Paste the following JSON into the query editor.
+
+    ```json
+    {
+      "search": "walking distance to live music",
+      "select": "HotelId, HotelName, Description",
+      "count": true
+    }
+    ```
+
+1. Select **Search** to run the query.
+
+   The response should be similar to the following example. This is a full-text query ranked by BM25, so results match on individual query terms and linguistic variants rather than the overall meaning of the query. For example, `walking` matches `walk`, and `live` and `music` match independently rather than as a phrase.
+
+    ```json
+    "@odata.count": 30,
+    "value": [
+      {
+        "@search.score": 5.004435,
+        "HotelId": "2",
+        "HotelName": "Old Century Hotel",
+        "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
+      },
+      {
+        "@search.score": 4.555706,
+        "HotelId": "24",
+        "HotelName": "Uptown Chic Hotel",
+        "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
+      },
+      {
+        "@search.score": 3.5625167,
+        "HotelId": "4",
+        "HotelName": "Sublime Palace Hotel",
+        "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
+      },
+      ... // Trimmed for brevity
+    ]
+   ```
+
+    > [!TIP]
+    > This query shows how the response looks before semantic ranking is applied. After you configure a semantic configuration, add `"queryType": "semantic"` and `"semanticConfiguration": "semantic-config"` to see how the same query is ranked differently by semantic ranking.
+

@@ -1,163 +0,0 @@
----
-manager: nitinme
-author: haileytap
-ms.author: haileytapia
-ms.service: azure-ai-search
-ms.topic: include
-ms.date: 11/20/2025
----
-
-In this quickstart, you learn how to use [semantic ranking](../../semantic-search-overview.md) by adding a semantic configuration to a search index and adding semantic parameters to a query. You can use the hotels-sample-index or one of your own.
-
-In Azure AI Search, semantic ranking is query-side functionality that uses machine reading comprehension from Microsoft to rescore search results, promoting the most semantically relevant matches to the top of the list. Depending on the content and the query, semantic ranking can [significantly improve search relevance](https://techcommunity.microsoft.com/t5/azure-ai-services-blog/azure-cognitive-search-outperforming-vector-search-with-hybrid/ba-p/3929167) with minimal developer effort.
-
-You can add a semantic configuration to an existing index with no rebuild requirement. Semantic ranking is most effective on text that's informational or descriptive.
-
-## Prerequisites
-
-+ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
-
-+ An [Azure AI Search service](../../search-create-service-portal.md) with [semantic ranker enabled](../../semantic-how-to-enable-disable.md).
-
-+ A [new or existing index](../../search-how-to-create-search-index.md) with descriptive or verbose text fields that are attributed as retrievable. This quickstart assumes the [hotels-sample-index](../../search-get-started-portal.md).
-
-## Configure access
-
-You can connect to your Azure AI Search service using API keys or Microsoft Entra ID with role assignments. Keys are easier to start with, but roles are more secure. For more information, see [Connect to Azure AI Search using roles](../../search-security-rbac.md).
-
-To configure role-based access:
-
-1. Sign in to the [Azure portal](https://portal.azure.com/) and select your search service.
-
-1. From the left pane, select **Settings** > **Keys**.
-
-1. Under **API Access control**, select **Role-based access control** or **Both** if you need time to transition clients to role-based access.
-
-1. From the left pane, select **Access control (IAM)**.
-
-1. Select **Add** > **Add role assignment**.
-
-1. Assign the **Search Service Contributor** and **Search Index Data Contributor** roles to your user account.
-
-## Start with an index
-
-This quickstart assumes an existing index and modifies it to include a semantic configuration. We recommend the [hotels-sample-index](../../search-get-started-portal.md) that you can create in minutes using an Azure portal wizard.
-
-To start with an existing index:
-
-1. Sign in to the [Azure portal](https://portal.azure.com/) and find your search service.
-
-1. Under **Search management** > **Indexes**, select the hotels-sample-index.
-
-1. Select **Semantic configurations** to ensure the index doesn't have a semantic configuration.
-
-   :::image type="content" source="../../media/search-get-started-semantic/no-semantic-configuration.png" alt-text="Screenshot of an empty semantic configuration page in the Azure portal.":::
-
-1. Select **Search explorer**, and then select the **JSON view**.
-
-1. Paste the following JSON into the query editor.
-
-    ```json
-    {
-      "search": "walking distance to live music",
-      "select": "HotelId, HotelName, Description",
-      "count": true
-    }
-    ```
-
-   :::image type="content" source="../../media/search-get-started-semantic/search-explorer-simple-query.png" alt-text="Screenshot of a query in Search Explorer in the portal.":::
-
-1. Select **Search** to run the query.
-
-   This query is a keyword search. The response should be similar to the following example, as scored by the default BM25 L1 ranker for full-text search.
-
-   For readability, the example only selects the `HotelId`, `HotelName`, and `Description` fields. The results contain verbatim matches on the query terms (`walking`, `distance`, `live`, `music`) or linguistic variants (`walk`, `living`).
-
-    ```json
-    "@odata.count": 13,
-    "value": [
-      {
-        "@search.score": 5.5153193,
-        "HotelId": "2",
-        "HotelName": "Old Century Hotel",
-        "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
-      },
-      {
-        "@search.score": 5.074317,
-        "HotelId": "24",
-        "HotelName": "Uptown Chic Hotel",
-        "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
-      },
-      {
-        "@search.score": 4.8959594,
-        "HotelId": "4",
-        "HotelName": "Sublime Palace Hotel",
-        "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
-      },
-      {
-        "@search.score": 2.5966604,
-        "HotelId": "35",
-        "HotelName": "Bellevue Suites",
-        "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
-      },
-      {
-        "@search.score": 2.566386,
-        "HotelId": "47",
-        "HotelName": "Country Comfort Inn",
-        "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
-      },
-      {
-        "@search.score": 2.2405157,
-        "HotelId": "9",
-        "HotelName": "Smile Up Hotel",
-        "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime location. Don't miss our weekend live music series featuring who's new/next on the scene."
-      },
-      {
-        "@search.score": 2.1737604,
-        "HotelId": "8",
-        "HotelName": "Foot Happy Suites",
-        "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
-      },
-      {
-        "@search.score": 2.0364518,
-        "HotelId": "31",
-        "HotelName": "Country Residence Hotel",
-        "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
-      },
-      {
-        "@search.score": 1.7595702,
-        "HotelId": "49",
-        "HotelName": "Swirling Currents Hotel",
-        "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
-      },
-      {
-        "@search.score": 1.5502293,
-        "HotelId": "15",
-        "HotelName": "By the Market Hotel",
-        "Description": "Book now and Save up to 30%. Central location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
-      },
-      {
-        "@search.score": 1.3302404,
-        "HotelId": "42",
-        "HotelName": "Rock Bottom Resort & Campground",
-        "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
-      },
-      {
-        "@search.score": 0.9050383,
-        "HotelId": "38",
-        "HotelName": "Lakeside B & B",
-        "Description": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
-      },
-      {
-        "@search.score": 0.7334347,
-        "HotelId": "39",
-        "HotelName": "White Mountain Lodge & Suites",
-        "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
-      }
-    ]
-   ```
-
-This query shows how the response looks *before* semantic ranking is applied. Later, you can run the same query after semantic ranking is configured to see how the response changes.
-
-> [!TIP]
-> You can add a semantic configuration in the Azure portal. However, if you want to learn how to add a semantic configuration programmatically, continue with this quickstart.

@@ -1,163 +1,499 @@
 ---
 author: KarlErickson
-ms.author: karler
+ms.author: haileytapia
 ms.service: azure-ai-search
 ms.custom: devx-track-java
 ms.topic: include
-ms.date: 12/15/2025
+ms.date: 03/04/2026
 ai-usage: ai-assisted
 ---
 
-[!INCLUDE [Semantic ranker introduction](semantic-ranker-intro.md)]
+In this quickstart, you use the [Azure AI Search client library for Java](/java/api/overview/azure/search-documents-readme) to add [semantic ranking](../../semantic-search-overview.md) to an existing search index and query the index.
 
-## Set up the client
+Semantic ranking is query-side functionality that uses machine reading comprehension to rescore search results, promoting the most semantically relevant matches to the top of the list. You can add a semantic configuration to an existing index with no rebuild requirement. Semantic ranking is most effective for informational or descriptive text.
 
-In this quickstart, you use an IDE and the [**Azure AI Search Java SDK**](https://search.maven.org/artifact/com.azure/azure-search-documents) client library to add semantic ranking to an existing search index.
+> [!TIP]
+> Want to get started right away? Download the [source code](https://github.com/Azure-Samples/azure-search-java-samples/tree/main/quickstart-semantic-ranking) on GitHub.
 
-The quickstart assumes the following is available on your computer:
-- [Visual Studio Code](https://code.visualstudio.com/) with Java extensions or IntelliJ IDEA
-- [Java 21 (LTS)](/java/openjdk/install).
-- [Maven](https://maven.apache.org/download.cgi).
+## Prerequisites
 
-### Set up local development environment
++ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
 
-1. Create a new Maven project directory.
++ An [Azure AI Search service](../../search-create-service-portal.md) with [semantic ranker enabled](../../semantic-how-to-enable-disable.md).
 
-   ```bash
-   mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
-   code .
-   ```
++ An [index](../../search-how-to-create-search-index.md) with descriptive text fields attributed as `searchable` and `retrievable`.  This quickstart assumes the [hotels-sample index](../../search-get-started-portal.md).
 
-1. Create a `pom.xml` file with required dependencies.
++ [Java 21 (LTS)](/java/openjdk/install) and [Maven](https://maven.apache.org/download.cgi).
 
-   :::code language="xml" source="~/azure-search-java-samples/quickstart-semantic-ranking/pom.xml" :::
++ [Visual Studio Code](https://code.visualstudio.com/download).
 
-1. Compile the project to resolve the dependencies.
++ [Git](https://git-scm.com/downloads) to clone the sample repository.
 
-    ```bash
-    mvn compile
-    ```
-
-1. Create the source directory structure.
-
-   ```bash
-   mkdir -p src/main/java/com/azure/search/quickstart
-   mkdir -p src/main/resources
-   ```
-
-1. Create an `application.properties` file in the `src/main/resources` directory and provide your search service endpoint. You can get the endpoint from the Azure portal on the search service **Overview** page.
-
-    ```properties
-    azure.search.endpoint=YOUR-SEARCH-SERVICE-ENDPOINT
-    azure.search.index.name=hotels-sample-index
-    semantic.configuration.name=semantic-config
-    ```
++ The [Azure CLI](/cli/azure/install-azure-cli) for keyless authentication with Microsoft Entra ID.
 
-### Sign in to Azure
+## Configure access
 
-If you signed in to the [Azure portal](https://portal.azure.com), you're signed into Azure. If you aren't sure, use the Azure CLI to log in: `az login`. If you have multiple tenants and subscriptions, see [Quickstart: Connect without keys](../../search-get-started-rbac.md) for help on how to connect.
+[!INCLUDE [resource authentication](../resource-authentication-semantic.md)]
 
-## Create a common configuration class
+## Get endpoint
 
-Create a `SearchConfig.java` file in the `src/main/java/com/azure/search/quickstart` directory to read the properties file and hold the configuration values and authentication credential.
+[!INCLUDE [resource endpoint](../resource-endpoint.md)]
 
-:::code language="java" source="~/azure-search-java-samples/quickstart-semantic-ranking/src/main/java/com/azure/search/quickstart/SearchConfig.java" :::
+## Start with an index
 
-## Get the index schema
+[!INCLUDE [start with an index](semantic-ranker-index.md)]
 
-In this section, you get settings for the existing `hotels-sample-index` index on your search service.
+## Set up the environment
 
-1. Create a `GetIndexSettings.java` file in the `src/main/java/com/azure/search/quickstart` directory.
-
-   :::code language="java" source="~/azure-search-java-samples/quickstart-semantic-ranking/src/main/java/com/azure/search/quickstart/GetIndexSettings.java" :::
-
-1. Compile and run the code.
+1. Use Git to clone the sample repository.
 
     ```bash
-    mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.GetIndexSettings"
+    git clone https://github.com/Azure-Samples/azure-search-java-samples
     ```
 
-1. Output is the name of the index, list of fields, and a statement indicating whether a semantic configuration exists. For the purposes of this quickstart, the message should say `No semantic configuration exists for this index`.
-
-## Update the index with a semantic configuration
-
-1. Create an `UpdateIndexSettings.java` file in the `src/main/java/com/azure/search/quickstart` directory to add a semantic configuration to the existing `hotels-sample-index` index on your search service.
-
-   :::code language="java" source="~/azure-search-java-samples/quickstart-semantic-ranking/src/main/java/com/azure/search/quickstart/UpdateIndexSettings.java" :::
-
-1. Compile and run the code.
+1. Navigate to the quickstart folder and open it in Visual Studio Code.
 
     ```bash
-    mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.UpdateIndexSettings"
+    cd azure-search-java-samples/quickstart-semantic-ranking
+    code .
     ```
 
-1. Output is the semantic configuration you just added, `Semantic configuration updated successfully.`.
-
-## Run semantic queries
-
-After the `hotels-sample-index` index has a semantic configuration, you can run queries that include semantic parameters.
+1. In `src/main/resources/application.properties`, replace the placeholder value for `azure.search.endpoint` with the URL you obtained in [Get endpoint](#get-endpoint).
 
-1. Create a `SemanticQuery.java` file in the `src/main/java/com/azure/search/quickstart` directory to create a semantic query of the index.
-
-   :::code language="java" source="~/azure-search-java-samples/quickstart-semantic-ranking/src/main/java/com/azure/search/quickstart/SemanticQuery.java" :::
-
-1. Compile and run the code.
+1. Compile the project to resolve dependencies, including [azure-search-documents](https://search.maven.org/artifact/com.azure/azure-search-documents).
 
     ```bash
-    mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.SemanticQuery"
+    mvn compile
     ```
 
-1. Output should consist of 13 documents, ordered by the reranker score.
-
-### Return captions
+    When the build completes, verify that no errors appear in the output.
 
-Optionally, you can add captions to extract portions of the text and apply hit highlighting to the important terms and phrases.
+1. For keyless authentication with Microsoft Entra ID, sign in to your Azure account. If you have multiple subscriptions, select the one that contains your Azure AI Search service.
 
-1. Create a `SemanticQueryWithCaptions.java` file in the `src/main/java/com/azure/search/quickstart` directory.
+    ```azurecli
+    az login
+    ```
 
-   :::code language="java" source="~/azure-search-java-samples/quickstart-semantic-ranking/src/main/java/com/azure/search/quickstart/SemanticQueryWithCaptions.java" :::
+## Run the code
 
-1. Compile and run the code.
+1. Get the existing index settings.
 
     ```bash
-    mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.SemanticQueryWithCaptions"
+    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.GetIndexSettings"
     ```
 
-1. Output should include a new caption element alongside search field. Captions are the most relevant passages in a result. If your index includes larger chunks of text, a caption is helpful for extracting the most interesting sentences.
-
-    ```output
-    Search result #1:
-      Re-ranker Score: 2.613231658935547
-      HotelName: Uptown Chic Hotel
-      Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
+1. Update the index with a semantic configuration.
 
-      Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
+    ```bash
+    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.UpdateIndexSettings"
     ```
 
-### Return semantic answers
-
-In this final query, return semantic answers.
+1. Run a semantic query.
 
-Semantic ranker can produce an answer to a query string that has the characteristics of a question. The generated answer is extracted verbatim from your content so it won't include composed content like what you might expect from a chat completion model.
-
-To produce a semantic answer, the question and answer must be closely aligned, and the model must find content that clearly answers the question. If potential answers fail to meet a confidence threshold, the model doesn't return an answer. For demonstration purposes, the question in this example is designed to get a response so that you can see the syntax.
-
-1. Create a `SemanticAnswer.java` file in the `src/main/java/com/azure/search/quickstart` directory.
-
-   :::code language="java" source="~/azure-search-java-samples/quickstart-semantic-ranking/src/main/java/com/azure/search/quickstart/SemanticAnswer.java" :::
+    ```bash
+    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQuery"
+    ```
 
-1. Compile and run the code.
+1. Run a semantic query with captions.
 
     ```bash
-    mvn compile exec:java -Dexec.mainClass="com.azure.search.quickstart.SemanticAnswer"
+    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQueryWithCaptions"
     ```
 
-1. Output should look similar to the following example, where the best answer to question is pulled from one of the results.
-
-    Recall that answers are *verbatim content* pulled from your index and might be missing phrases that a user would expect to see. To get *composed answers* as generated by a chat completion model, considering using a [RAG pattern](../../retrieval-augmented-generation-overview.md) or [agentic retrieval](../../agentic-retrieval-overview.md).
+1. Run a semantic query with answers.
 
-    ```output
-    Semantic answer result #1:
-    Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
-    Semantic Answer Score: 0.9829999804496765
+    ```bash
+    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticAnswer"
     ```
+
+### Output
+
+The output of `GetIndexSettings.java` is the name of the index, its fields, and its semantic configurations. Before you add a new configuration, the index has only the default one.
+
+```output
+Index name: hotels-sample
+Number of fields: 23
+Field: HotelId, Type: Edm.String, Searchable: true
+Field: HotelName, Type: Edm.String, Searchable: true
+Field: Description, Type: Edm.String, Searchable: true
+// Trimmed for brevity
+Semantic search configurations: 1
+Configuration name: hotels-sample-semantic-configuration
+```
+
+The output of `UpdateIndexSettings.java` lists all semantic configurations on the index, including the one the code added, followed by a success message.
+
+```output
+// Trimmed for brevity
+Configuration name: semantic-config
+Title field: HotelName
+Keywords fields: Tags
+Content fields: Description
+----------------------------------------
+Semantic configuration updated successfully.
+```
+
+The output of `SemanticQuery.java` returns all matching documents ordered by the semantic ranking re-ranker score.
+
+```output
+Search result #1:
+  Re-ranker Score: 2.61
+  HotelId: 24
+  HotelName: Uptown Chic Hotel
+  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
+
+Search result #2:
+  Re-ranker Score: 2.27
+  HotelId: 2
+  HotelName: Old Century Hotel
+  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
+
+Search result #3:
+  Re-ranker Score: 1.99
+  HotelId: 4
+  HotelName: Sublime Palace Hotel
+  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
+// Trimmed for brevity
+```
+
+The output of `SemanticQueryWithCaptions.java` adds a caption element with hit highlighting alongside search fields. Captions are the most relevant passages in a result. If your index includes larger text, captions help extract the most interesting sentences.
+
+```output
+Search result #1:
+  Re-ranker Score: 2.61
+  HotelName: Uptown Chic Hotel
+  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
+
+  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
+------------------------------------------------------------
+Search result #2:
+  Re-ranker Score: 2.27
+  HotelName: Old Century Hotel
+  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
+
+  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
+------------------------------------------------------------
+// Trimmed for brevity
+```
+
+The output of `SemanticAnswer.java` includes a semantic answer pulled from one of the results that best matches the question, followed by search results with captions.
+
+```output
+Semantic answer result #1:
+Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
+Semantic Answer Score: 0.98
+
+Search Results:
+
+Search result #1:
+Re-ranker Score: 2.12
+Hotel: Stay-Kay City Hotel
+Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
+Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
+
+Search result #2:
+Re-ranker Score: 2.07
+Hotel: Double Sanctuary Resort
+Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
+Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
+// Trimmed for brevity
+```
+
+## Understand the code
+
+[!INCLUDE [understand code note](../understand-code-note.md)]
+
+Now that you've run the code, let's break down the key steps:
+
+1. [Configuration and authentication](#configuration-and-authentication)
+1. [Update the index with a semantic configuration](#update-the-index-with-a-semantic-configuration)
+1. [Query the index](#query-the-index)
+
+### Configuration and authentication
+
+The `SearchConfig.java` class loads properties from `application.properties` and creates a `DefaultAzureCredential` for keyless authentication.
+
+```java
+import com.azure.identity.DefaultAzureCredential;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Properties;
+
+public class SearchConfig {
+    private static final Properties properties =
+        new Properties();
+
+    static {
+        try (InputStream input = SearchConfig.class
+            .getClassLoader()
+            .getResourceAsStream(
+                "application.properties")) {
+            properties.load(input);
+        } catch (IOException e) {
+            throw new RuntimeException(
+                "Failed to load application.properties",
+                e);
+        }
+    }
+
+    public static final String SEARCH_ENDPOINT =
+        properties.getProperty(
+            "azure.search.endpoint");
+    public static final String INDEX_NAME =
+        properties.getProperty(
+            "azure.search.index.name");
+    public static final String SEMANTIC_CONFIG_NAME =
+        properties.getProperty(
+            "semantic.configuration.name");
+
+    public static final DefaultAzureCredential
+        CREDENTIAL = new DefaultAzureCredentialBuilder()
+            .build();
+}
+```
+
+Key takeaways:
+
++ `DefaultAzureCredential` provides keyless authentication using Microsoft Entra ID. It chains multiple credential types, including the Azure CLI credential from `az login`.
++ Properties are loaded from the `application.properties` file in the classpath.
++ Static fields (`SEARCH_ENDPOINT`, `INDEX_NAME`, `SEMANTIC_CONFIG_NAME`, `CREDENTIAL`) are shared across all classes in the project.
+
+### Update the index with a semantic configuration
+
+The `UpdateIndexSettings.java` class adds a semantic configuration to the existing `hotels-sample` index. This operation doesn't delete any search documents, and your index remains operational after the configuration is added.
+
+```java
+import com.azure.search.documents.indexes
+    .SearchIndexClientBuilder;
+import com.azure.search.documents.indexes.models
+    .SearchIndex;
+import com.azure.search.documents.indexes.models
+    .SemanticConfiguration;
+import com.azure.search.documents.indexes.models
+    .SemanticField;
+import com.azure.search.documents.indexes.models
+    .SemanticPrioritizedFields;
+import com.azure.search.documents.indexes.models
+    .SemanticSearch;
+
+import java.util.ArrayList;
+import java.util.List;
+
+var indexClient = new SearchIndexClientBuilder()
+    .endpoint(SearchConfig.SEARCH_ENDPOINT)
+    .credential(SearchConfig.CREDENTIAL)
+    .buildClient();
+
+SearchIndex existingIndex =
+    indexClient.getIndex(SearchConfig.INDEX_NAME);
+
+var prioritizedFields =
+    new SemanticPrioritizedFields()
+        .setTitleField(
+            new SemanticField("HotelName"))
+        .setKeywordsFields(
+            List.of(new SemanticField("Tags")))
+        .setContentFields(
+            List.of(
+                new SemanticField("Description")));
+
+var newSemanticConfiguration =
+    new SemanticConfiguration(
+        SearchConfig.SEMANTIC_CONFIG_NAME,
+        prioritizedFields);
+
+SemanticSearch semanticSearch =
+    existingIndex.getSemanticSearch();
+if (semanticSearch == null) {
+    semanticSearch = new SemanticSearch();
+    existingIndex.setSemanticSearch(semanticSearch);
+}
+
+List<SemanticConfiguration> configurations =
+    semanticSearch.getConfigurations();
+if (configurations == null) {
+    configurations = new ArrayList<>();
+    semanticSearch.setConfigurations(configurations);
+}
+
+configurations.add(newSemanticConfiguration);
+
+indexClient.createOrUpdateIndex(existingIndex);
+```
+
+Key takeaways:
+
++ `SemanticPrioritizedFields` defines which fields the semantic ranker evaluates. `setTitleField` sets the document title, `setContentFields` sets the main content, and `setKeywordsFields` sets the keyword or tag fields.
++ `SemanticConfiguration` pairs a name with the prioritized fields, identifying which semantic configuration to use at query time.
++ `createOrUpdateIndex` pushes the updated schema to the search service without rebuilding the index or deleting documents.
+
+### Query the index
+
+The following three classes query the index in sequence, progressing from a basic semantic search to semantic ranking with captions and answers.
+
+#### Semantic query (no captions, no answers)
+
+The first query adds semantic ranking with no captions or answers. The `SemanticQuery.java` class shows the minimum requirement for invoking semantic ranking.
+
+```java
+import com.azure.search.documents
+    .SearchClientBuilder;
+import com.azure.search.documents.SearchDocument;
+import com.azure.search.documents.models.QueryType;
+import com.azure.search.documents.models.SearchOptions;
+import com.azure.search.documents.models.SearchResult;
+import com.azure.search.documents.models
+    .SemanticSearchOptions;
+import com.azure.search.documents.util
+    .SearchPagedIterable;
+
+var searchClient = new SearchClientBuilder()
+    .endpoint(SearchConfig.SEARCH_ENDPOINT)
+    .indexName(SearchConfig.INDEX_NAME)
+    .credential(SearchConfig.CREDENTIAL)
+    .buildClient();
+
+var searchOptions = new SearchOptions()
+    .setQueryType(QueryType.SEMANTIC)
+    .setSemanticSearchOptions(
+        new SemanticSearchOptions()
+            .setSemanticConfigurationName(
+                SearchConfig.SEMANTIC_CONFIG_NAME))
+    .setSelect("HotelId", "HotelName", "Description");
+
+SearchPagedIterable results = searchClient.search(
+    "walking distance to live music",
+    searchOptions, null);
+
+for (SearchResult result : results) {
+    var document = result.getDocument(
+        SearchDocument.class);
+    double rerankerScore = result
+        .getSemanticSearch().getRerankerScore();
+
+    System.out.printf("Re-ranker Score: %.2f%n",
+        rerankerScore);
+    System.out.printf("HotelName: %s%n",
+        document.get("HotelName"));
+    System.out.printf("Description: %s%n%n",
+        document.get("Description"));
+}
+```
+
+Key takeaways:
+
++ `QueryType.SEMANTIC` enables semantic ranking on the query.
++ `setSemanticConfigurationName` specifies which semantic configuration to use.
++ `SearchPagedIterable` provides an iterable over the reranked results. Each `SearchResult` contains a `getSemanticSearch()` accessor for the reranker score.
+
+#### Semantic query with captions
+
+The `SemanticQueryWithCaptions.java` class adds captions to extract the most relevant passages from each result, with hit highlighting applied to the important terms and phrases.
+
+```java
+import com.azure.search.documents.models
+    .QueryCaption;
+import com.azure.search.documents.models
+    .QueryCaptionResult;
+import com.azure.search.documents.models
+    .QueryCaptionType;
+
+var searchOptions = new SearchOptions()
+    .setQueryType(QueryType.SEMANTIC)
+    .setSemanticSearchOptions(
+        new SemanticSearchOptions()
+            .setSemanticConfigurationName(
+                SearchConfig.SEMANTIC_CONFIG_NAME)
+            .setQueryCaption(
+                new QueryCaption(
+                    QueryCaptionType.EXTRACTIVE)
+                    .setHighlightEnabled(true)))
+    .setSelect(
+        "HotelId", "HotelName", "Description");
+
+SearchPagedIterable results = searchClient.search(
+    "walking distance to live music",
+    searchOptions, null);
+
+for (SearchResult result : results) {
+    List<QueryCaptionResult> captions =
+        result.getSemanticSearch()
+            .getQueryCaptions();
+    if (captions != null && !captions.isEmpty()) {
+        QueryCaptionResult caption = captions.get(0);
+        if (caption.getHighlights() != null) {
+            System.out.printf(
+                "Caption: %s%n",
+                caption.getHighlights());
+        }
+    }
+}
+```
+
+Key takeaways:
+
++ `QueryCaption(QueryCaptionType.EXTRACTIVE)` enables extractive captions from the content fields.
++ `setHighlightEnabled(true)` adds `<em>` tags around important terms in captions.
++ Each `SearchResult` provides `getQueryCaptions()` on the semantic search accessor.
+
+#### Semantic query with answers
+
+The `SemanticAnswer.java` class adds semantic answers. This class uses a question as the search text because semantic answers work best when the query is phrased as a question. The answer is a verbatim passage extracted from your index, not a composed response from a chat completion model.
+
+The query and the indexed content must be closely aligned for an answer to be returned. If no candidate meets the confidence threshold, the response doesn't include an answer. This example uses a question that's known to produce a result so that you can see the syntax. If answers aren't useful for your scenario, omit `setQueryAnswer` from your code. For composed answers, consider a [RAG pattern](../../retrieval-augmented-generation-overview.md) or [agentic retrieval](../../agentic-retrieval-overview.md).
+
+```java
+import com.azure.search.documents.models
+    .QueryAnswer;
+import com.azure.search.documents.models
+    .QueryAnswerResult;
+import com.azure.search.documents.models
+    .QueryAnswerType;
+
+var searchOptions = new SearchOptions()
+    .setQueryType(QueryType.SEMANTIC)
+    .setSemanticSearchOptions(
+        new SemanticSearchOptions()
+            .setSemanticConfigurationName(
+                SearchConfig.SEMANTIC_CONFIG_NAME)
+            .setQueryCaption(
+                new QueryCaption(
+                    QueryCaptionType.EXTRACTIVE))
+            .setQueryAnswer(
+                new QueryAnswer(
+                    QueryAnswerType.EXTRACTIVE)))
+    .setSelect(
+        "HotelName", "Description", "Category");
+
+SearchPagedIterable results = searchClient.search(
+    "What's a good hotel for people who like to read",
+    searchOptions, null);
+
+List<QueryAnswerResult> semanticAnswers =
+    results.getSemanticResults().getQueryAnswers();
+
+for (QueryAnswerResult answer :
+    semanticAnswers != null ? semanticAnswers
+        : List.<QueryAnswerResult>of()) {
+    if (answer.getHighlights() != null) {
+        System.out.printf(
+            "Semantic Answer: %s%n",
+            answer.getHighlights());
+    } else {
+        System.out.printf(
+            "Semantic Answer: %s%n",
+            answer.getText());
+    }
+    System.out.printf(
+        "Semantic Answer Score: %.2f%n",
+        answer.getScore());
+}
+```
+
+Key takeaways:
+
++ `QueryAnswer(QueryAnswerType.EXTRACTIVE)` enables extractive answers for question-like queries.
++ Answers are verbatim content extracted from your index, not generated text.
++ `results.getSemanticResults().getQueryAnswers()` retrieves the answer objects separately from the search results.

@@ -4,423 +4,429 @@ ms.author: haileytapia
 ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
+  - dev-focus
 ms.topic: include
-ms.date: 11/20/2025
+ms.date: 03/04/2026
+ai-usage: ai-assisted
 ---
 
-[!INCLUDE [Semantic ranker introduction](semantic-ranker-intro.md)]
+In this quickstart, you use the [Azure AI Search client library for JavaScript](/javascript/api/overview/azure/search-documents-readme) to add [semantic ranking](../../semantic-search-overview.md) to an existing search index and query the index.
 
-## Set up the client
+Semantic ranking is query-side functionality that uses machine reading comprehension to rescore search results, promoting the most semantically relevant matches to the top of the list. You can add a semantic configuration to an existing index with no rebuild requirement. Semantic ranking is most effective for informational or descriptive text.
 
-In this quickstart, you use an IDE and the [**@azure/search-documents**](https://www.npmjs.com/package/@azure/search-documents) client library to add semantic ranking to an existing search index.
+> [!TIP]
+> Want to get started right away? Download the [source code](https://github.com/Azure-Samples/azure-search-javascript-samples/tree/main/quickstart-semantic-ranking-js) on GitHub.
 
-The quickstart assumes the following is available on your computer:
-- [Visual Studio Code](https://code.visualstudio.com/) for this quickstart.
-- [Node.js](https://nodejs.org/) (LTS) for running the sample.
+## Prerequisites
 
-> [!TIP]
-> You can download the [source code](https://github.com/Azure-Samples/azure-search-javascript-samples/tree/main/quickstart-semantic-ranking-js) to start with a finished project or follow these steps to create your own.
++ An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).
+
++ An [Azure AI Search service](../../search-create-service-portal.md) with [semantic ranker enabled](../../semantic-how-to-enable-disable.md).
+
++ An [index](../../search-how-to-create-search-index.md) with descriptive text fields attributed as `searchable` and `retrievable`.  This quickstart assumes the [hotels-sample index](../../search-get-started-portal.md).
+
++ [Node.js 20 LTS](https://nodejs.org/en/download/) or later.
+
++ [Visual Studio Code](https://code.visualstudio.com/download).
+
++ [Git](https://git-scm.com/downloads) to clone the sample repository.
+
++ The [Azure CLI](/cli/azure/install-azure-cli) for keyless authentication with Microsoft Entra ID.
 
-### Set up local development environment
+## Configure access
 
-1. Start Visual Studio Code in a new directory.
+[!INCLUDE [resource authentication](../resource-authentication-semantic.md)]
 
-   ```bash
-   mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
-   code .
-   ```
+## Get endpoint
 
-1. Create a new package for ESM modules in your project directory.
+[!INCLUDE [resource endpoint](../resource-endpoint.md)]
 
-   ```bash
-   npm init -y
-   npm pkg set type=module
-   ```
+## Start with an index
 
-1. Install packages, including [azure-search-documents](/javascript/api/%40azure/search-documents).
+[!INCLUDE [start with an index](semantic-ranker-index.md)]
+
+## Set up the environment
+
+1. Use Git to clone the sample repository.
 
     ```bash
-   npm install @azure/identity @azure/search-documents dotenv
+    git clone https://github.com/Azure-Samples/azure-search-javascript-samples
     ```
 
-1. Create `.env`, and provide your search service endpoint. You can get the endpoint from the Azure portal on the search service **Overview** page.
+1. Navigate to the quickstart folder and open it in Visual Studio Code.
 
-    ```ini
-    AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
-    AZURE_SEARCH_INDEX_NAME=hotels-sample-index
-    SEMANTIC_CONFIGURATION_NAME=semantic-config
+    ```bash
+    cd azure-search-javascript-samples/quickstart-semantic-ranking-js
+    code .
     ```
 
-1. Create a `src` directory in your project directory.
+1. In `sample.env`, replace the placeholder value for `AZURE_SEARCH_ENDPOINT` with the URL you obtained in [Get endpoint](#get-endpoint).
 
-   ```bash
-   mkdir src
-   ```
+1. Rename `sample.env` to `.env`.
 
-### Sign in to Azure
+    ```bash
+    mv sample.env .env
+    ```
 
-If you signed in to the [Azure portal](https://portal.azure.com), you're signed into Azure. If you aren't sure, use the Azure CLI or Azure PowerShell to log in: `az login` or `az connect`. If you have multiple tenants and subscriptions, see [Quickstart: Connect without keys](../../search-get-started-rbac.md) for help on how to connect.
+1. Install the dependencies.
 
-## Create a common authentication file
+    ```bash
+    npm install
+    ```
 
-Create a file in `./src` called `config.ts` to read the `.env` file and hold the environment variables and authentication credential. Copy in the following code; don't change it. This file will be used by all the other files in this quickstart.
+    When the installation completes, you should see a `node_modules` folder in the project directory.
 
-```javascript
-import { DefaultAzureCredential } from "@azure/identity";
+1. For keyless authentication with Microsoft Entra ID, sign in to your Azure account. If you have multiple subscriptions, select the one that contains your Azure AI Search service.
 
-// Configuration - use environment variables
-export const searchEndpoint = process.env.AZURE_SEARCH_ENDPOINT || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
-export const indexName = process.env.AZURE_SEARCH_INDEX_NAME || "hotels-sample-index";
-export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";
+    ```azurecli
+    az login
+    ```
 
-// Create credential
-export const credential = new DefaultAzureCredential();
+## Run the code
 
-console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
-console.log(`Using index name: ${indexName}\n\n`);
-```
+1. Get the existing index settings.
 
-## Get the index schema
-
-In this section, you get settings for the existing `hotels-sample-index` index on your search service.
-
-1. Create a file in `./src` called `getIndexSettings.js` and copy in the following code.
-
-    ```javascript
-    import {
-        SearchIndexClient
-    } from "@azure/search-documents";
-    import { searchEndpoint, indexName, credential } from "./config.js";
-    
-    const indexClient = new SearchIndexClient(searchEndpoint, credential);
-    
-    console.log('Getting semantic search index settings...');
-    
-    // Get the existing schema
-    const index = await indexClient.getIndex(indexName);
-    
-    console.log(`Index name: ${index.name}`);
-    console.log(`Number of fields: ${index.fields.length}`);
-    
-    for(const field of index.fields) {
-        console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
-    }
-    
-    if(index.semanticSearch && index.semanticSearch.configurations) {
-        console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
-        for(const config of index.semanticSearch.configurations) {
-            console.log(`Configuration name: ${config.name}`);
-            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
-        }
-    } else {
-        console.log("No semantic configuration exists for this index.");
-    }
+    ```bash
+    node -r dotenv/config src/getIndexSettings.js
     ```
 
-1. Run the code.
+1. Update the index with a semantic configuration.
 
     ```bash
-    node -r dotenv/config src/getIndexSettings.js
+    node -r dotenv/config src/updateIndexSettings.js
     ```
 
-1. Output is the name of the index, list of fields, and a statement indicating whether a semantic configuration exists. For the purposes of this quickstart, the message should say `No semantic configuration exists for this index`.
-
-## Update the index with a semantic configuration
-
-1. Create a file in `./src` called `updateIndexSettings.js` and copy in the following code to add a semantic configuration to the existing `hotels-sample-index` index on your search service. No search documents are deleted by this operation and your index is still operational after the configuration is added.
-
-    ```javascript
-    import {
-        SearchIndexClient
-    } from "@azure/search-documents";
-    import { searchEndpoint, indexName, credential, semanticConfigurationName } from "./config.js";
-    
-    try {
-    
-        const indexClient = new SearchIndexClient(searchEndpoint, credential);
-    
-        const existingIndex = await indexClient.getIndex(indexName);
-    
-        const fields = {
-            titleField: {
-                name: "HotelName"
-            },
-            keywordsFields: [{
-                name: "Tags"
-            }],
-            contentFields: [{
-                name: "Description"
-            }]
-        };
-    
-        const newSemanticConfiguration = {
-            name: semanticConfigurationName,
-            prioritizedFields: fields
-        };
-    
-        // Add the new semantic configuration to the existing index
-        if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
-            existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
-        } else {
-            const configExists = existingIndex.semanticSearch?.configurations?.some(
-                config => config.name === semanticConfigurationName
-            );
-            if (!configExists) {
-                existingIndex.semanticSearch = {
-                    configurations: [newSemanticConfiguration]
-                };
-            }
-        }
-    
-        await indexClient.createOrUpdateIndex(existingIndex);
-    
-        const updatedIndex = await indexClient.getIndex(indexName);
-    
-        console.log(`Semantic configurations:`);
-        console.log("-".repeat(40));
-    
-        if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
-            for (const config of updatedIndex.semanticSearch.configurations) {
-                console.log(`Configuration name: ${config.name}`);
-                console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
-                console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
-                console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
-                console.log("-".repeat(40));
-            }
-        } else {
-            console.log("No semantic configurations found.");
-        }
-    
-        console.log("Semantic configuration updated successfully.");
-    } catch (error) {
-        console.error("Error updating semantic configuration:", error);
-    }
+1. Run a semantic query.
+
+    ```bash
+    node -r dotenv/config src/semanticQuery.js
     ```
 
-1. Run the code.
+1. Run a semantic query with captions.
 
     ```bash
-    node -r dotenv/config src/updateIndexSettings.js
+    node -r dotenv/config src/semanticQueryReturnCaptions.js
     ```
 
-1. Output is the semantic configuration you just added, `Semantic configuration updated successfully.`.
+1. Run a semantic query with answers.
 
-## Run semantic queries
+    ```bash
+    node -r dotenv/config src/semanticAnswer.js
+    ```
 
-Once the `hotels-sample-index` index has a semantic configuration, you can run queries that include semantic parameters.
+### Output
+
+The `getIndexSettings.js` script returns the name of the index, its fields, and any existing semantic configurations.
+
+```output
+Getting semantic ranking index settings...
+Index name: hotels-sample
+Number of fields: 23
+Field: HotelId, Type: Edm.String, Searchable: true
+Field: HotelName, Type: Edm.String, Searchable: true
+Field: Description, Type: Edm.String, Searchable: true
+Field: Description_fr, Type: Edm.String, Searchable: true
+Field: Category, Type: Edm.String, Searchable: true
+Field: Tags, Type: Collection(Edm.String), Searchable: true
+// Trimmed for brevity
+Semantic ranking configurations: 1
+Configuration name: hotels-sample-semantic-configuration
+Title field: undefined
+```
 
-1. Create a file in `./src` called `semanticQuery.js` and copy in the following code to create a semantic query of the index. This is the minimum requirement for invoking semantic ranking.
+The `updateIndexSettings.js` script returns all semantic configurations on the index, including the one the code added, followed by a success message.
+
+```output
+Semantic configurations:
+----------------------------------------
+Configuration name: hotels-sample-semantic-configuration
+Title field: undefined
+Keywords fields:
+Content fields: AzureSearch_DocumentKey
+----------------------------------------
+Configuration name: semantic-config
+Title field: HotelName
+Keywords fields: Tags
+Content fields: Description
+----------------------------------------
+Semantic configuration updated successfully.
+```
 
-    ```javascript
-    import { SearchClient } from "@azure/search-documents";
-    import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";
-    
-    const searchClient = new SearchClient(
-        searchEndpoint,
-        indexName,
-        credential
-    );
-    
-    const results = await searchClient.search("walking distance to live music", {
+The `semanticQuery.js` script returns all matching documents ordered by the semantic ranking re-ranker score.
+
+```output
+Search result #1:
+  Re-ranker Score: 2.613231658935547
+  HotelId: 24
+  HotelName: Uptown Chic Hotel
+  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
+
+Search result #2:
+  Re-ranker Score: 2.271434783935547
+  HotelId: 2
+  HotelName: Old Century Hotel
+  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
+
+Search result #3:
+  Re-ranker Score: 1.9861756563186646
+  HotelId: 4
+  HotelName: Sublime Palace Hotel
+  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
+// Trimmed for brevity
+```
+
+The `semanticQueryReturnCaptions.js` script returns a caption element with hit highlighting alongside search fields. Captions are the most relevant passages in a result. If your index includes larger text, captions help extract the most interesting sentences.
+
+```output
+Search result #1:
+  Re-ranker Score: 2.613231658935547
+  HotelName: Uptown Chic Hotel
+  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
+
+  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
+------------------------------------------------------------
+Search result #2:
+  Re-ranker Score: 2.271434783935547
+  HotelName: Old Century Hotel
+  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
+
+  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
+------------------------------------------------------------
+// Trimmed for brevity
+```
+
+The `semanticAnswer.js` script returns a semantic answer pulled from one of the results that best matches the question, followed by search results with captions.
+
+```output
+Answers:
+
+Semantic answer result #1:
+Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
+Semantic Answer Score: 0.9829999804496765
+
+Search Results:
+
+Search result #1:
+2.124817371368408
+Stay-Kay City Hotel
+This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
+Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
+// Trimmed for brevity
+```
+
+## Understand the code
+
+[!INCLUDE [understand code note](../understand-code-note.md)]
+
+Now that you've run the code, let's break down the key steps:
+
+1. [Configuration and authentication](#configuration-and-authentication)
+1. [Update the index with a semantic configuration](#update-the-index-with-a-semantic-configuration)
+1. [Query the index](#query-the-index)
+
+### Configuration and authentication
+
+The `config.js` file loads environment variables and creates a `DefaultAzureCredential` for authentication.
+
+```javascript
+import { DefaultAzureCredential }
+    from "@azure/identity";
+
+export const searchEndpoint =
+    process.env.AZURE_SEARCH_ENDPOINT
+    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
+export const indexName =
+    process.env.AZURE_SEARCH_INDEX_NAME
+    || "hotels-sample";
+export const semanticConfigurationName =
+    process.env.SEMANTIC_CONFIGURATION_NAME
+    || "semantic-config";
+
+export const credential = new DefaultAzureCredential();
+```
+
+Key takeaways:
+
++ `DefaultAzureCredential` provides keyless authentication using Microsoft Entra ID. It chains multiple credential types, including the Azure CLI credential from `az login`.
++ Environment variables are loaded from the `.env` file using `dotenv`.
+
+### Update the index with a semantic configuration
+
+The `updateIndexSettings.js` file adds a semantic configuration to the existing `hotels-sample` index. This operation doesn't delete any search documents, and your index remains operational after the configuration is added.
+
+```javascript
+import { SearchIndexClient }
+    from "@azure/search-documents";
+import {
+    searchEndpoint, indexName,
+    credential, semanticConfigurationName
+} from "./config.js";
+
+const indexClient = new SearchIndexClient(
+    searchEndpoint, credential
+);
+const existingIndex =
+    await indexClient.getIndex(indexName);
+
+const fields = {
+    titleField: { name: "HotelName" },
+    keywordsFields: [{ name: "Tags" }],
+    contentFields: [{ name: "Description" }]
+};
+
+const newSemanticConfiguration = {
+    name: semanticConfigurationName,
+    prioritizedFields: fields
+};
+
+if (existingIndex.semanticSearch
+    && existingIndex.semanticSearch.configurations) {
+    existingIndex.semanticSearch.configurations
+        .push(newSemanticConfiguration);
+} else {
+    existingIndex.semanticSearch = {
+        configurations: [newSemanticConfiguration]
+    };
+}
+
+await indexClient.createOrUpdateIndex(existingIndex);
+```
+
+Key takeaways:
+
++ A semantic configuration specifies the fields used for semantic ranking. `titleField` defines the document title, `contentFields` defines the main content, and `keywordsFields` defines the keyword or tag fields.
++ You create a configuration object and push it to the existing index's `semanticSearch.configurations` array.
++ `createOrUpdateIndex` pushes the updated schema to the search service without rebuilding the index or deleting documents.
+
+### Query the index
+
+The query scripts run three queries in sequence, progressing from a basic semantic search to semantic ranking with captions and answers.
+
+#### Semantic query (no captions, no answers)
+
+The following code shows the minimum requirement for invoking semantic ranking.
+
+```javascript
+import { SearchClient }
+    from "@azure/search-documents";
+import {
+    credential, searchEndpoint,
+    indexName, semanticConfigurationName
+} from "./config.js";
+
+const searchClient = new SearchClient(
+    searchEndpoint, indexName, credential
+);
+
+const results = await searchClient.search(
+    "walking distance to live music",
+    {
         queryType: "semantic",
         semanticSearchOptions: {
-            configurationName: semanticConfigurationName
+            configurationName:
+                semanticConfigurationName
         },
-        select: ["HotelId", "HotelName", "Description"]
-    });
-    
-    let rowNumber = 1;
-    for await (const result of results.results) {
-        // Log each result
-        const doc = result.document;
-        const score = result.score;
-        const rerankerScoreDisplay = result.rerankerScore;
-    
-        console.log(`Search result #${rowNumber++}:`);
-        console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
-        console.log(`  HotelId: ${doc.HotelId}`);
-        console.log(`  HotelName: ${doc.HotelName}`);
-        console.log(`  Description: ${doc.Description || 'N/A'}\n`);
+        select: [
+            "HotelId", "HotelName", "Description"
+        ]
     }
-    ```
-
-1. Run the code.
-
-    ```bash
-    node -r dotenv/config src/semanticQuery.js
-    ```
+);
+```
 
-1. Output should consist of 13 documents, ordered by the `rerankerScoreDisplay`.
+Key takeaways:
 
-### Return captions
++ `queryType: "semantic"` enables semantic ranking on the query.
++ `semanticSearchOptions.configurationName` specifies which semantic configuration to use.
++ The `rerankerScore` in results indicates semantic relevance (higher is better).
 
-Optionally, you can add captions to extract portions of the text and apply hit highlighting to the important terms and phrases. This query adds captions.
+#### Semantic query with captions
 
-1. Create a file in `./src` called `semanticQueryReturnCaptions.js` and copy in the following code to add captions to the query.
+The following code adds captions to extract the most relevant passages from each result, with hit highlighting applied to the important terms and phrases.
 
-    ```javascript
-    import { SearchClient } from "@azure/search-documents";
-    import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";
-    
-    const searchClient = new SearchClient(
-        searchEndpoint,
-        indexName,
-        credential
-    );
-    
-    console.log(`Using semantic configuration: ${semanticConfigurationName}`);
-    console.log("Search query: walking distance to live music");
-    
-    const results = await searchClient.search("walking distance to live music", {
+```javascript
+const results = await searchClient.search(
+    "walking distance to live music",
+    {
         queryType: "semantic",
         semanticSearchOptions: {
-            configurationName: semanticConfigurationName,
+            configurationName:
+                semanticConfigurationName,
             captions: {
                 captionType: "extractive",
                 highlight: true
             }
         },
-        select: ["HotelId", "HotelName", "Description"],
-    });
-    
-    console.log(`Found ${results.count} results with semantic search\n`);
-    let rowNumber = 1;
-    
-    for await (const result of results.results) {
-        // Log each result
-        const doc = result.document;
-        const rerankerScoreDisplay = result.rerankerScore;
-    
-        console.log(`Search result #${rowNumber++}:`);
-        console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
-        console.log(`  HotelName: ${doc.HotelName}`);
-        console.log(`  Description: ${doc.Description || 'N/A'}\n`);
-    
-        // Caption handling with better debugging
-        const captions = result.captions;
-        
-        if (captions && captions.length > 0) {
-            const caption = captions[0];
-            
-            if (caption.highlights) {
-                console.log(`  Caption with highlights: ${caption.highlights}`);
-            } else if (caption.text) {
-                console.log(`  Caption text: ${caption.text}`);
-            } else {
-                console.log(`  Caption exists but has no text or highlights content`);
-            }
-        } else {
-            console.log("  No captions found for this result");
+        select: [
+            "HotelId", "HotelName", "Description"
+        ]
+    }
+);
+
+for await (const result of results.results) {
+    const captions = result.captions;
+    if (captions && captions.length > 0) {
+        const caption = captions[0];
+        if (caption.highlights) {
+            console.log(
+                `Caption: ${caption.highlights}`
+            );
         }
-        console.log("-".repeat(60));
     }
-    ```
-
-1. Run the code.
-
-    ```bash
-    node -r dotenv/config src/semanticQueryReturnCaptions.js
-    ```
-
-1. Output should include a new caption element alongside search field. Captions are the most relevant passages in a result. If your index includes larger chunks of text, a caption is helpful for extracting the most interesting sentences.
-
-    ```console
-    Search result #1:
-      Re-ranker Score: 2.613231658935547
-      HotelName: Uptown Chic Hotel
-      Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
-    
-      Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
-    ```
+}
+```
 
-### Return semantic answers
+Key takeaways:
 
-In this final query, return semantic answers.
++ `captions.captionType: "extractive"` enables extractive captions from the content fields.
++ Captions surface the most relevant passages and add `<em>` tags around important terms.
 
-Semantic ranker can produce an answer to a query string that has the characteristics of a question. The generated answer is extracted verbatim from your content so it won't include composed content like what you might expect from a chat completion model. If the semantic answer isn't useful for your scenario, you can omit `semantic_answers` from your code.
+#### Semantic query with answers
 
-To produce a semantic answer, the question and answer must be closely aligned, and the model must find content that clearly answers the question. If potential answers fail to meet a confidence threshold, the model doesn't return an answer. For demonstration purposes, the question in this example is designed to get a response so that you can see the syntax.
+The final query adds semantic answers. This query uses a question as the search text because semantic answers work best when the query is phrased as a question. The answer is a verbatim passage extracted from your index, not a composed response from a chat completion model.
 
-1. Create a file in `./src` called `semanticAnswer.js` and copy in the following code to get semantic answers. 
+The query and the indexed content must be closely aligned for an answer to be returned. If no candidate meets the confidence threshold, the response doesn't include an answer. This example uses a question that's known to produce a result so that you can see the syntax. If answers aren't useful for your scenario, omit `answers` from your code. For composed answers, consider a [RAG pattern](../../retrieval-augmented-generation-overview.md) or [agentic retrieval](../../agentic-retrieval-overview.md).
 
-    ```javascript
-    import { SearchClient } from "@azure/search-documents";
-    import { credential, searchEndpoint, indexName, semanticConfigurationName } from "./config.js";
-    
-    const searchClient = new SearchClient(
-        searchEndpoint,
-        indexName,
-        credential
-    );
-    
-    const results = await searchClient.search("What's a good hotel for people who like to read", {
+```javascript
+const results = await searchClient.search(
+    "What's a good hotel for people who "
+    + "like to read",
+    {
         queryType: "semantic",
         semanticSearchOptions: {
-            configurationName: semanticConfigurationName,
+            configurationName:
+                semanticConfigurationName,
             captions: {
                 captionType: "extractive"
             },
             answers: {
                 answerType: "extractive"
             }
         },
-        select: ["HotelName", "Description", "Category"]
-    });
-    
-    console.log(`Answers:\n\n`);
-    let rowNumber = 1; 
-    
-    // Extract semantic answers from the search results
-    const semanticAnswers = results.answers;
-    for (const answer of semanticAnswers || []) {
-        console.log(`Semantic answer result #${rowNumber++}:`);
-        if (answer.highlights) {
-            console.log(`Semantic Answer: ${answer.highlights}`);
-        } else {
-            console.log(`Semantic Answer: ${answer.text}`);
-        }
-        console.log(`Semantic Answer Score: ${answer.score}\n\n`);
+        select: [
+            "HotelName", "Description", "Category"
+        ]
     }
-    
-    console.log(`Search Results:\n\n`);
-    rowNumber = 1;
-    
-    // Iterate through the search results
-    for await (const result of results.results) {
-        // Log each result
-        const doc = result.document;
-        const rerankerScoreDisplay = result.rerankerScore;
-    
-        console.log(`Search result #${rowNumber++}:`);
-        console.log(`${rerankerScoreDisplay}`);
-        console.log(`${doc.HotelName}`);
-        console.log(`${doc.Description || 'N/A'}`);
-    
-        const captions = result.captions;
-    
-        if (captions && captions.length > 0) {
-            const caption = captions[0];
-            if (caption.highlights) {
-                console.log(`Caption: ${caption.highlights}\n`);
-            } else {
-                console.log(`Caption: ${caption.text}\n`);
-            }
-        }
+);
+
+const semanticAnswers = results.answers;
+for (const answer of semanticAnswers || []) {
+    if (answer.highlights) {
+        console.log(
+            `Semantic Answer: ${answer.highlights}`
+        );
+    } else {
+        console.log(
+            `Semantic Answer: ${answer.text}`
+        );
     }
-    ```
-
-1. Run the code.
-
-    ```bash
-    node -r dotenv/config src/semanticAnswer.js
-    ```
-
-1. Output should look similar to the following example, where the best answer to question is pulled from one of the results.
+    console.log(
+        `Semantic Answer Score: ${answer.score}`
+    );
+}
+```
 
-    Recall that answers are *verbatim content* pulled from your index and might be missing phrases that a user would expect to see. To get *composed answers* as generated by a chat completion model, considering using a [RAG pattern](../../retrieval-augmented-generation-overview.md) or [agentic retrieval](../../agentic-retrieval-overview.md).
+Key takeaways:
 
-    ```console
-    Semantic answer result #1:
-    Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
-    Semantic Answer Score: 0.9829999804496765
-    ```
++ `answers.answerType: "extractive"` enables extractive answers for question-like queries.
++ Answers are verbatim content extracted from your index, not generated text.
++ `results.answers` retrieves the answer objects separately from the search results.