Merge pull request #940 from cdpark/refresh-oct-heidist2

Feature 322546: Q&M: Freshness - AI Services & Search 180d target - Oct sprint - heidist2

Author: JamesJBarnett

articles/search/index-add-suggesters.md

@@ -1,5 +1,5 @@
 ---
-title: Configure a suggester
+title: Configure a suggester for autocomplete and suggestions
 titleSuffix: Azure AI Search
 description: Enable typeahead query actions in Azure AI Search by creating suggesters and formulating requests that invoke autocomplete or autosuggested query terms.
 
@@ -8,46 +8,46 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: conceptual
-ms.date: 01/18/2024
+ms.date: 10/21/2024
 ms.custom:
   - devx-track-csharp
   - devx-track-dotnet
   - ignite-2023
 ---
 
-# Configure a suggester for autocomplete and suggested matches in a query
+# Configure a suggester for autocomplete and suggestions in a query
 
-In Azure AI Search, typeahead (autocomplete) or "search-as-you-type" is enabled through a *suggester*. A suggester is a configuration in an index specifying which fields should be used to populate autocomplete and suggestions. These fields undergo extra tokenization, generating prefix sequences to support matches on partial terms. For example, a suggester that includes a City field with a value for "Seattle" will have prefix combinations of "sea", "seat", "seatt", and "seattl" to support typeahead.
+In Azure AI Search, typeahead or "search-as-you-type" is enabled by using a *suggester*. A suggester is a configuration in an index that specifies which fields should be used to populate autocomplete and suggested matches. These fields undergo extra tokenization, generating prefix sequences to support matches on partial terms. For example, a suggester that includes a `city` field with a value for *Seattle* has prefix combinations of *sea*, *seat*, *seatt*, and *seattl* to support typeahead.
 
 Matches on partial terms can be either an autocompleted query or a suggested match. The same suggester supports both experiences.
 
 ## Typeahead experiences in Azure AI Search
 
-Typeahead can be *autocomplete*, which completes a partial input for a whole term query, or *suggestions* that invite click through to a particular match. Autocomplete produces a query. Suggestions produce a matching document.
+Typeahead can use *autocomplete*, which completes a partial input for a whole term query, or *suggestions* that invite click through to a particular match. Autocomplete produces a query. Suggestions produce a matching document.
 
-The following screenshot illustrates both. Autocomplete anticipates a potential term, finishing "tw" with "in". Suggestions are mini search results, where a field like hotel name represents a matching hotel search document from the index. For suggestions, you can surface any field that provides descriptive information.
+The following screenshot illustrates both. Autocomplete anticipates a potential term, finishing *tw* with *in*. Suggestions are mini search results, where a field like `hotel name` represents a matching hotel search document from the index. For suggestions, you can surface any field that provides descriptive information.
 
-![Visual comparison of autocomplete and suggested queries](./media/index-add-suggesters/hotel-app-suggestions-autocomplete.png "Visual comparison of autocomplete and suggested queries")
+:::image type="content" source="media/index-add-suggesters/hotel-app-suggestions-autocomplete.png" alt-text="Screenshot showing visual comparison of autocomplete and suggested queries.":::
 
 You can use these features separately or together. To implement these behaviors in Azure AI Search, there's an index and query component. 
 
-+ Add a suggester to a search index definition. The remainder of this article is focused on creating a suggester.
++ Add a suggester to a search index definition. The remainder of this article focuses on creating a suggester.
 
-+ Call a suggester-enabled query, in the form of a Suggestion request or Autocomplete request, using one of the [APIs listed in a later section](#how-to-use-a-suggester).
++ Call a suggester-enabled query, in the form of a suggestion request or autocomplete request, by using one of the APIs listed in [Use a suggester](#how-to-use-a-suggester).
 
-Search-as-you-type is enabled on a per-field basis for string fields. You can implement both typeahead behaviors within the same search solution if you want an experience similar to the one indicated in the screenshot. Both requests target the *documents* collection of specific index and responses are returned after a user provides at least a three character input string.
+Search-as-you-type is enabled on a per-field basis for string fields. You can implement both typeahead behaviors within the same search solution if you want an experience similar to the one indicated in the screenshot. Both requests target the *documents* collection of a specific index, and responses are returned after a user provides at least a three-character input string.
 
 ## How to create a suggester
 
 To create a suggester, add one to an [index definition](/rest/api/searchservice/indexes/create). A suggester takes a name and a collection of fields over which the typeahead experience is enabled. The best time to create a suggester is when you're also defining the field that uses it.
 
 + Use string fields only.
 
-+ If the string field is part of a complex type (for example, a City field within Address), include the parent in the field path: `"Address/City"` (REST and C# and Python), or `["Address"]["City"]` (JavaScript).
++ If the string field is part of a complex type (for example, a City field within Address), include the parent in the field path: `"Address/City"` (REST, C#, and Python), or `["Address"]["City"]` (JavaScript).
 
 + Use the default standard Lucene analyzer (`"analyzer": null`) or a [language analyzer](index-add-language-analyzers.md) (for example, `"analyzer": "en.Microsoft"`) on the field.
 
-If you try to create a suggester using pre-existing fields, the API disallows it. Prefixes are generated during indexing, when partial terms in two or more character combinations are tokenized alongside whole terms. Given that existing fields are already tokenized, you have to rebuild the index if you want to add them to a suggester. For more information, see [How to rebuild an Azure AI Search index](search-howto-reindex.md).
+If you try to create a suggester using preexisting fields, the API disallows it. Prefixes are generated during indexing, when partial terms in two or more character combinations are tokenized alongside whole terms. Given that existing fields are already tokenized, you have to rebuild the index if you want to add them to a suggester. For more information, see [Update or rebuild an index in Azure AI Search](search-howto-reindex.md).
 
 ### Choose fields
 
@@ -61,28 +61,28 @@ To satisfy both search-as-you-type experiences, add all of the fields that you n
 
 ### Choose analyzers
 
-Your choice of an analyzer determines how fields are tokenized and prefixed. For example, for a hyphenated string like "context-sensitive", using a language analyzer results in these token combinations: "context", "sensitive", "context-sensitive". Had you used the standard Lucene analyzer, the hyphenated string wouldn't exist. 
+Your choice of an analyzer determines how fields are tokenized and prefixed. For example, for a hyphenated string like *context-sensitive*, using a language analyzer results in these token combinations: *context*, *sensitive*, *context-sensitive*. Had you used the standard Lucene analyzer, the hyphenated string wouldn't exist. 
 
 When evaluating analyzers, consider using the [Analyze Text API](/rest/api/searchservice/indexes/analyze) for insight into how terms are processed. Once you build an index, you can try various analyzers on a string to view token output.
 
-Fields that use [custom analyzers](index-add-custom-analyzers.md) or [built-in analyzers](index-add-custom-analyzers.md#built-in-analyzers) (except for standard Lucene) are explicitly disallowed to prevent poor outcomes.
+Fields that use [custom analyzers](index-add-custom-analyzers.md) or [built-in analyzers](index-add-custom-analyzers.md#built-in-analyzers), (except for standard Lucene) are explicitly disallowed to prevent poor outcomes.
 
 > [!NOTE]
-> If you need to work around the analyzer constraint, for example if you need a keyword or ngram analyzer for certain query scenarios, you should use two separate fields for the same content. This will allow one of the fields to have a suggester, while the other can be set up with a custom analyzer configuration.
+> If you need to work around the analyzer constraint, for example if you need a keyword or ngram analyzer for certain query scenarios, you should use two separate fields for the same content. This allows one of the fields to have a suggester, while the other can be set up with a custom analyzer configuration.
 
-## Create using the portal
+## Create using the Azure portal
 
 When using **Add Index** or the **Import data** wizard to create an index, you have the option of enabling a suggester:
 
 1. In the index definition, enter a name for the suggester.
 
-1. In each field definition for new fields, select a checkbox in the Suggester column. A checkbox is available on string fields only. 
+1. In each field definition for new fields, select a checkbox in the **Suggester** column. A checkbox is available on string fields only. 
 
 As previously noted, analyzer choice impacts tokenization and prefixing. Consider the entire field definition when enabling suggesters. 
 
 ## Create using REST
 
-In the REST API, add suggesters through [Create Index](/rest/api/searchservice/indexes/create) or [Update Index](/rest/api/searchservice/indexes/create-or-update). 
+In the REST API, add suggesters by using [Create Index](/rest/api/searchservice/indexes/create) or [Update Index](/rest/api/searchservice/indexes/create-or-update). 
 
   ```json
   {
@@ -142,7 +142,7 @@ private static void CreateIndex(string indexName, SearchIndexClient indexClient)
 |Property      |Description      |
 |--------------|-----------------|
 | name        | Specified in the suggester definition, but also called on an Autocomplete or Suggestions request. |
-| sourceFields | Specified in the suggester definition. It's a list of one or more fields in the index that are the source of the content for suggestions. Fields must be of type `Edm.String`. If an analyzer is specified on the field, it must be a named lexical analyzer from [this list](/dotnet/api/azure.search.documents.indexes.models.lexicalanalyzername) (not a custom analyzer). </br></br>As a best practice, specify only those fields that lend themselves to an expected and appropriate response, whether it's a completed string in a search bar or a dropdown list. </br></br>A hotel name is a good candidate because it has precision. Verbose fields like descriptions and comments are too dense. Similarly, repetitive fields, such as categories and tags, are less effective. In the examples, we include "category" anyway to demonstrate that you can include multiple fields. |
+| sourceFields | Specified in the suggester definition. It's a list of one or more fields in the index that are the source of the content for suggestions. Fields must be of type `Edm.String`. If an analyzer is specified on the field, it must be a named lexical analyzer listed on [LexicalAnalyzerName Struct](/dotnet/api/azure.search.documents.indexes.models.lexicalanalyzername) (not a custom analyzer). </br></br>As a best practice, specify only those fields that lend themselves to an expected and appropriate response, whether it's a completed string in a search bar or a dropdown list. </br></br>A hotel name is a good candidate because it has precision. Verbose fields like descriptions and comments are too dense. Similarly, repetitive fields, such as categories and tags, are less effective. In the examples, we include *category* anyway to demonstrate that you can include multiple fields. |
 | searchMode  | REST-only parameter, but also visible in the portal. This parameter isn't available in the .NET SDK. It indicates the strategy used to search for candidate phrases. The only mode currently supported is `analyzingInfixMatching`, which currently matches on the beginning of a term.|
 
 <a name="how-to-use-a-suggester"></a>
@@ -151,7 +151,7 @@ private static void CreateIndex(string indexName, SearchIndexClient indexClient)
 
 A suggester is used in a query. After a suggester is created, call one of the following APIs for a search-as-you-type experience:
 
-+ [Suggestions REST API](/rest/api/searchservice/documents/suggest-post)
++ [Suggest REST API](/rest/api/searchservice/documents/suggest-post)
 + [Autocomplete REST API](/rest/api/searchservice/documents/autocomplete-post)
 + [SuggestAsync method](/dotnet/api/azure.search.documents.searchclient.suggestasync)
 + [AutocompleteAsync method](/dotnet/api/azure.search.documents.searchclient.autocompleteasync)
@@ -170,11 +170,11 @@ POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2024-07-01
 
 ## Sample code
 
-+ [Add search to a web site (C#)](tutorial-csharp-search-query-integration.md) uses an open source Suggestions package for partial term completion in the client app.
+To learn how to use an open source Suggestions package for partial term completion in the client app, see [Explore the .NET search code](tutorial-csharp-search-query-integration.md).
 
-## Next steps
+## Next step
 
-Learn more about requests\ formulation.
+Learn more about request formulation.
 
 > [!div class="nextstepaction"]
-> [Add autocomplete and suggestions to client code](search-add-autocomplete-suggestions.md)
+> [Add autocomplete and search suggestions in client apps](search-add-autocomplete-suggestions.md)