Merge pull request #921 from eric-urban/eur/semantic-config

refresh semantic config

Author: v-dirichards

articles/search/media/search-import-data-portal/import-data-cmd.png

@@ -2,14 +2,12 @@
 title: Create an index
 titleSuffix: Azure AI Search
 description: Create a search index using the Azure portal, REST APIs, or an Azure SDK.
-
 manager: nitinme
 author: HeidiSteen
 ms.author: heidist
-
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 07/01/2024
+ms.date: 10/20/2024
 ---
 
 # Create an index in Azure AI Search
@@ -20,7 +18,7 @@ In this article, learn the steps for defining a schema for a [**search index**](
 
 + Write permissions as a [**Search Service Contributor**](search-security-rbac.md) or an [admin API key](search-security-api-keys.md) for key-based authentication.
 
-+ An understanding of the data you want to index. A search index is based on external content that you want to make searchable. Searchable content is stored as fields in an index. You should have a clear idea of which source fields you want to make searchable, retrievable, filterable, facetable, and sortable (see the [schema checklist](#schema-checklist) for guidance).
++ An understanding of the data you want to index. A search index is based on external content that you want to make searchable. Searchable content is stored as fields in an index. You should have a clear idea of which source fields you want to make searchable, retrievable, filterable, facetable, and sortable. See the [schema checklist](#schema-checklist) for guidance.
 
 + You must also have a unique field in source data that can be used as the [document key (or ID)](#document-keys) in the index.
 
@@ -46,7 +44,7 @@ Use this checklist to assist the design decisions for your search index.
 
 1. Review [supported data types](/rest/api/searchservice/supported-data-types). The data type affects how the field is used. For example, numeric content is filterable but not full text searchable. The most common data type is `Edm.String` for searchable text, which is tokenized and queried using the full text search engine. The most common data type for a vector field is `Edm.Single` but you can use other types as well.
 
-1. Identify a [document key](#document-keys). A document key is an index requirement. It's a single string field and it's populated from a source data field that contains unique values. For example, if you're indexing from Blob Storage, the metadata storage path is often used as the document key because it uniquely identifies each blob in the container.
+1. Identify a [document key](#document-keys). A document key is an index requirement. It's a single string field populated from a source data field that contains unique values. For example, if you're indexing from Blob Storage, the metadata storage path is often used as the document key because it uniquely identifies each blob in the container.
 
 1. Identify the fields in your data source that contribute searchable content in the index.
 
@@ -93,16 +91,18 @@ Index design through the portal enforces requirements and schema rules for speci
 
 1. Check for space. Search services are subject to [maximum number of indexes](search-limits-quotas-capacity.md), varying by service tier. Make sure you have room for a second index.
 
-1. In the search service Overview page, choose either option for creating a search index: 
+1. In the search service **Overview** page, choose either option for creating a search index: 
 
    + **Add index**, an embedded editor for specifying an index schema
    + [**Import wizards**](search-import-data-portal.md)
 
    The wizard is an end-to-end workflow that creates an indexer, a data source, and a finished index. It also loads the data. If this is more than what you want, use **Add index** instead.
 
-The following screenshot highlights where **Add index** and **Import data** appear on the command bar. After an index is created, you can find it again in the **Indexes** tab.
+The following screenshot highlights where **Add index**, **Import data**, and **Import and vectorize data** appear on the command bar. 
+
+:::image type="content" source="media/search-what-is-an-index/add-index.png" alt-text="Screenshot of the options to add an index." border="true":::
 
-  :::image type="content" source="media/search-what-is-an-index/add-index.png" alt-text="Add index command" border="true":::
+After an index is created, you can find it again on the **Indexes** page from the left navigation pane.
 
 > [!TIP]
 > After creating an index in the portal, you can copy the JSON representation and add it to your application code.

articles/search/media/search-what-is-an-index/add-index-import-samples.png

@@ -31,13 +31,19 @@ This article isn't a step by step. For help with using the wizard with built-in
 
 ## Starting the wizards
 
-In the [Azure portal](https://portal.azure.com), open the search service page from the dashboard or [find your service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) in the service list. 
+1. In the [Azure portal](https://portal.azure.com), open the search service page from the dashboard or [find your service](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.Search%2FsearchServices) in the service list. 
 
-In the service Overview page at the top, select **Import data** or **Import and vectorize data**.
+1. In the service Overview page at the top, select **Import data** or **Import and vectorize data**.
 
-:::image type="content" source="media/search-import-data-portal/import-data-cmd.png" alt-text="Screenshot of the import wizard options on the action bar.":::
+    :::image type="content" source="media/search-what-is-an-index/add-index.png" alt-text="Screenshot of the add index options." border="true"::: 
 
-The wizards open fully expanded in the browser window so that you have more room to work. 
+    The wizards open fully expanded in the browser window so that you have more room to work. 
+
+1. If you selected **Import data**, you can select the **Samples** option to use a prebuilt sample of data from a supported data source.
+
+    :::image type="content" source="media/search-what-is-an-index/add-index-import-samples.png" alt-text="Screenshot of the import data page with the samples option selected." border="true":::
+
+1. Follow the remaining steps in the wizard to create the index and indexer.
 
 You can also launch **Import data** from other Azure services, including Azure Cosmos DB, Azure SQL Database, SQL Managed Instance, and Azure Blob Storage. Look for **Add Azure AI Search** in the left-navigation pane on the service overview page.
 

articles/search/media/search-what-is-an-index/add-index.png

@@ -2,15 +2,14 @@
 title: Configure semantic ranker
 titleSuffix: Azure AI Search
 description: Add a semantic configuration to a search index.
-
 manager: nitinme
 author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.custom:
   - ignite-2023
 ms.topic: how-to
-ms.date: 09/24/2024
+ms.date: 10/20/2024
 ---
 
 # Configure semantic ranker and return captions in search results
@@ -29,7 +28,7 @@ This article explains how to configure a search index for semantic reranking.
 
 ## Choose a client
 
-You can use any of the following tools and SDKs to add a semantic configuration:
+You can use any of the following tools and software development kits (SDKs) to add a semantic configuration:
 
 + [Azure portal](https://portal.azure.com), using the index designer to add a semantic configuration.
 + [Visual Studio Code](https://code.visualstudio.com/download) with the [REST client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client)
@@ -61,15 +60,18 @@ Across all semantic configuration properties, the fields you assign must be:
 
 1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to a search service that has [semantic ranking enabled](semantic-how-to-enable-disable.md).
 
-1. From **Indexes** on the left-navigation pane, open an index.
+1. From **Indexes** on the left-navigation pane, select an index.
+
+1. Select **Semantic configurations** and then select **Add semantic configuration**.
 
-1. Select **Semantic Configurations** and then select **Add Semantic Configuration**.
+   :::image type="content" source="./media/semantic-search-overview/add-semantic-config.png" alt-text="Screenshot that shows the option to add a semantic configuration in the Azure portal." lightbox="./media/semantic-search-overview/add-semantic-config.png" border="true":::
 
-   The **New Semantic Configuration** page opens with options for selecting a title field, content fields, and keyword fields. Only searchable and retrievable string fields are eligible. Make sure to list content fields and keyword fields in priority order.
+1. On the **New semantic configuration** page, enter a semantic configuration name and select the fields to use in the semantic configuration. Only searchable and retrievable string fields are eligible. Make sure to list content fields and keyword fields in priority order.
 
    :::image type="content" source="./media/semantic-search-overview/create-semantic-config.png" alt-text="Screenshot that shows how to create a semantic configuration in the Azure portal." lightbox="./media/semantic-search-overview/create-semantic-config.png" border="true":::
 
-   Select **OK** to save the changes.
+1. Select **Save** to save the configuration settings.
+1. Select **Save** again on the index page to save the semantic configuration in the index.
 
 ### [**REST API**](#tab/rest)
 
@@ -163,27 +165,20 @@ If your semantic ranking code is using preview APIs, this section explains how t
 + [Azure SDK for Java (11.6) change log](https://github.com/Azure/azure-sdk-for-java/blob/azure-search-documents_11.6.1/sdk/search/azure-search-documents/CHANGELOG.md#1160-2023-11-13)
 + [Azure SDK for JavaScript (12.0) change log](https://github.com/Azure/azure-sdk-for-js/blob/%40azure/search-documents_12.0.0/sdk/search/search-documents/CHANGELOG.md#1200-2023-11-13)
 
-**Behavior changes:**
-
-+ As of July 14, 2023, semantic ranker is language agnostic. It can rerank results composed of multilingual content, with no bias towards a specific language. In preview versions, semantic ranking would deprioritize results differing from the language specified by the field analyzer.
-
-+ In 2021-04-30-Preview and all later versions, for the REST API and all SDK packages targeting the same version: `semanticConfiguration` (in an index definition) defines which search fields are used in semantic ranking. Previously in the 2020-06-30-Preview REST API, `searchFields` (in a query request) was used for field specification and prioritization. This approach only worked in 2020-06-30-Preview and is obsolete in all other versions.
-
-### Step 1: Remove queryLanguage
 
-The semantic ranking engine is now language agnostic. If `queryLanguage` is specified in your query logic, it's no longer used for semantic ranking, but still applies to [spell correction](speller-how-to-add.md). 
+### queryLanguage for semantic ranker
 
-Keep `queryLanguage` if you're using speller, and if the language value is [supported by speller](speller-how-to-add.md#supported-languages). Spell check has limited availability across languages. 
+As of July 14, 2023, semantic ranker is language agnostic. It can rerank results composed of multilingual content, with no bias towards a specific language. In preview versions, semantic ranking would deprioritize results differing from the language specified by the field analyzer.
 
-Otherwise, delete `queryLanguage`.
+Stop using `queryLanguage` in your code if you were using it for semantic ranking. The `queryLanguage` property is still applicable to features such as [spell correction](speller-how-to-add.md), but not to semantic ranking.
 
-### Step 2: Replace `searchFields` with `semanticConfiguration`
+### searchFields for semantic ranker
 
-If your code calls the 2020-06-30-Preview REST API or beta SDK packages targeting that REST API version, you might be using `searchFields` in a query request to specify semantic fields and priorities. In initial beta versions, `searchFields` had a dual purpose, constraining the initial query to the fields listed in `searchFields`, and also setting field priority if semantic ranking was used. In later versions, `searchFields` retains its original purpose, but is no longer used for semantic ranking.
+For the REST API and all SDK packages targeting version `2021-04-30-Preview` and later, the `searchFields` property is no longer used for semantic ranking.
 
-Keep `searchFields` in query requests if you're using it to limit full text search to the list of named fields.
+Instead, use the `semanticConfiguration` property (in a search index) to determine which search fields are used in semantic ranking. To specify field prioritization, add a `semanticConfiguration` to in an index schema following the [instructions in this article](#add-a-semantic-configuration).
 
-Add a `semanticConfiguration` to an index schema to specify field prioritization, following the [instructions in this article](#add-a-semantic-configuration).
+You can keep `searchFields` in query requests if you're using it to limit full text search to the list of named fields. 
 
 ## Next steps
 

articles/search/media/semantic-search-overview/add-semantic-config.png

@@ -15,7 +15,7 @@ ms.date: 09/24/2024
 
 # Enable or disable semantic ranker
 
-Semantic ranker is a premium feature that's billed by usage. By default, semantic ranker is turned off on a new search service, but it can be enabled by anyone with **Contributor** permissions. If you don't want anyone enabling it inadvertently, you can [disable it using the REST API](#disable-semantic-ranker-using-the-rest-api).
+Semantic ranker is a premium feature billed by usage. By default, semantic ranker is turned off on a new search service, but it can be enabled by anyone with **Contributor** permissions. If you don't want anyone enabling it inadvertently, you can [disable it using the REST API](#disable-semantic-ranker-using-the-rest-api).
 
 ## Check availability
 
@@ -31,13 +31,13 @@ Follow these steps to enable [semantic ranker](semantic-search-overview.md) at t
 
 1. Navigate to your search service. On the **Overview** page, make sure the service is a billable tier, Basic or higher.
 
-1. On the left-nav pane, select **Settings** > **Semantic ranking**.
+1. On the left-navigation pane, select **Settings** > **Semantic ranker**.
 
 1. Select either the **Free plan** or the **Standard plan**. You can switch between the free plan and the standard plan at any time.
 
    :::image type="content" source="media/semantic-search-overview/semantic-search-billing.png" alt-text="Screenshot of enabling semantic ranking in the Azure portal." border="true":::
 
-The free plan is capped at 1,000 queries per month. After the first 1,000 queries in the free plan, an error message indicates you've exhausted your quota on the next semantic query. When quota is exhausted, you should upgrade to the standard plan to continue using semantic ranking.
+The free plan is capped at 1,000 queries per month. After the first 1,000 queries in the free plan, an error message indicates you exhausted your quota on the next semantic query. When quota is exhausted, you should upgrade to the standard plan to continue using semantic ranking.
 
 ### [**REST**](#tab/enable-rest)