Merge pull request #112155 from HeidiSteen/heidist-search

[Azure Cog Search] Autocomplete/suggestion fields

Author: v-albemi

articles/search/index-add-suggesters.md

@@ -8,7 +8,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: cognitive-search
 ms.topic: conceptual
-ms.date: 04/14/2020
+ms.date: 04/21/2020
 ---
 
 # Create a suggester to enable autocomplete and suggested results in a query
@@ -29,27 +29,36 @@ Search-as-you-type support is enabled on a per-field basis for string fields. Yo
 
 ## What is a suggester?
 
-A suggester is a data structure that supports search-as-you-type behaviors by storing prefixes for matching on partial queries. Similar to tokenized terms, prefixes are stored in inverted indexes, one for each field specified in a suggester fields collection.
+A suggester is an internal data structure that supports search-as-you-type behaviors by storing prefixes for matching on partial queries. As with tokenized terms, prefixes are stored in inverted indexes, one for each field specified in a suggester fields collection.
 
-When creating prefixes, a suggester has its own analysis chain, similar to the one used for full text search. However, unlike analysis in full text search, a suggester can only operate over fields that use the standard Lucene analyzer (default) or a [language analyzer](index-add-language-analyzers.md). Fields that use [custom analyzers](index-add-custom-analyzers.md) or [predefined analyzers](index-add-custom-analyzers.md#predefined-analyzers-reference) (with the exception of standard Lucene) are explicitly disallowed to prevent poor outcomes.
+## Define a suggester
 
-> [!NOTE]
-> If you need to work around the analyzer constraint, 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.
+To create a suggester, add one to an [index schema](https://docs.microsoft.com/rest/api/searchservice/create-index) and [set each property](#property-reference). The best time to create a suggester is when you are also defining the field that will use it.
 
-## Define a suggester
++ Use string fields only
 
-To create a suggester, add one to an [index schema](https://docs.microsoft.com/rest/api/searchservice/create-index) and [set each property](#property-reference). In the index, you can have one suggester (specifically, one suggester in the suggesters collection). The best time to create a suggester is when you are also defining the field that will use it.
++ 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
 
 ### Choose fields
 
-Although a suggester has several properties, it is primarily a collection of fields for which you are enabling a search-as-you-type experience. For suggestions in particular, choose fields that best represent a single result. Names, titles, or other unique fields that distinguish among multiple matches work best. If fields consist of repetitive values, the suggestions consist of identical results and a user won't know which one to click.
+Although a suggester has several properties, it is primarily a collection of string fields for which you are enabling a search-as-you-type experience. There is one suggester for each index, so the suggester list must include all fields that contribute content for both suggestions and autocomplete.
+
+Autocomplete benefits from a larger pool of fields to draw from because the additional content has more term completion potential.
+
+Suggestions, on the other hand, produce better results when your field choice is selective. Remember that the suggestion is a proxy for a search document so you will want fields that best represent a single result. Names, titles, or other unique fields that distinguish among multiple matches work best. If fields consist of repetitive values, the suggestions consist of identical results and a user won't know which one to click.
 
-Make sure each field uses an analyzer that performs lexical analysis during indexing. You can use either the default standard Lucene analyzer (`"analyzer": null`) or a [language analyzer](index-add-language-analyzers.md) (for example, `"analyzer": "en.Microsoft"`). 
+To satisfy both search-as-you-type experiences, add all of the fields that you need for autocomplete, but then use **$select**, **$top**, **$filter**, and **searchFields** to control results for suggestions.
 
-Your choice of an analyzer determines how fields are tokenized and subsequently prefixed. For example, for a hyphenated string like "context-sensitive", using a language analyzer will result in these token combinations: "context", "sensitive", "context-sensitive". Had you used the standard Lucene analyzer, the hyphenated string would not exist.
+### Choose analyzers
 
-> [!TIP]
-> Consider using the [Analyze Text API](https://docs.microsoft.com/rest/api/searchservice/test-analyzer) for insight into how terms are tokenized and subsequently prefixed. Once you build an index, you can try various analyzers on a string to view the tokens it emits.
+Your choice of an analyzer determines how fields are tokenized and subsequently prefixed. For example, for a hyphenated string like "context-sensitive", using a language analyzer will result in these token combinations: "context", "sensitive", "context-sensitive". Had you used the standard Lucene analyzer, the hyphenated string would not exist. 
+
+When evaluating analyzers, consider using the [Analyze Text API](https://docs.microsoft.com/rest/api/searchservice/test-analyzer) for insight into how terms are tokenized and subsequently prefixed. 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 [predefined analyzers](index-add-custom-analyzers.md#predefined-analyzers-reference) (with the exception of 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.
 
 ### When to create a suggester
 
@@ -59,8 +68,7 @@ If you try to create a suggester using pre-existing fields, the API will disallo
 
 ## Create using REST
 
-In the REST API, add suggesters through [Create Index](https://docs.microsoft.com/rest/api/searchservice/create-index) or 
-[Update Index](https://docs.microsoft.com/rest/api/searchservice/update-index). 
+In the REST API, add suggesters through [Create Index](https://docs.microsoft.com/rest/api/searchservice/create-index) or [Update Index](https://docs.microsoft.com/rest/api/searchservice/update-index). 
 
   ```json
   {
@@ -158,7 +166,7 @@ POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2019-05-06
 
 ## Next steps
 
-We recommend the following example to see how the requests are formulated.
+We recommend the following article to learn more about how requests formulation.
 
 > [!div class="nextstepaction"]
 > [Add autocomplete and suggestions to client code](search-autocomplete-tutorial.md) 

articles/search/search-autocomplete-tutorial.md

@@ -60,12 +60,13 @@ Responses for autocomplete and suggestions are what you might expect for the pat
 
 Responses are shaped by the parameters on the request. For Autocomplete, set [**autocompleteMode**](https://docs.microsoft.com/rest/api/searchservice/autocomplete#autocomplete-modes) to determine whether text completion occurs on one or two terms. For Suggestions, the field you choose determines the contents of the response.
 
-To further refine the response, include more parameters on the request. The following parameters apply to both Autocomplete and Suggestions.
+For suggestions, you should further refine the response to avoid duplicates or what appears to be unrelated results. To control results, include more parameters on the request. The following parameters apply to both autocomplete and suggestions, but are perhaps more necessary for suggestions, especially when a suggester includes multiple fields.
 
 | Parameter | Usage |
 |-----------|-------|
-| **$select** | If you have multiple **sourceFields**, use **$select** to choose which field contributes values (`$select=GameTitle`). |
-| **$filter** | Apply match criteria on the result set (`$filter=ActionAdventure`). |
+| **$select** | If you have multiple **sourceFields** in a suggester, use **$select** to choose which field contributes values (`$select=GameTitle`). |
+| **searchFields** | Constrain the query to specific fields. |
+| **$filter** | Apply match criteria on the result set (`$filter=Category eq 'ActionAdventure'`). |
 | **$top** | Limit the results to a specific number (`$top=5`).|
 
 ## Add user interaction code
@@ -145,6 +146,8 @@ public ActionResult Suggest(bool highlights, bool fuzzy, string term)
     // Call suggest API and return results
     SuggestParameters sp = new SuggestParameters()
     {
+        Select = HotelName,
+        SearchFields = HotelName,
         UseFuzzyMatching = fuzzy,
         Top = 5
     };