Merge pull request #111355 from HeidiSteen/heidist-master

[Azure Cog Search] Add autocomplete/suggestions to a client app

Author: v-albemi

articles/search/TOC.yml

@@ -232,7 +232,7 @@
       items:
       - name: Create a suggester
         href: index-add-suggesters.md
-      - name: Add suggestions or autocomplete
+      - name: Add autocomplete and suggestions
         href: search-autocomplete-tutorial.md
     - name: Query from Power Apps   
       href: search-howto-powerapps.md  

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/10/2020
+ms.date: 04/14/2020
 ---
 
 # Create a suggester to enable autocomplete and suggested results in a query
@@ -38,15 +38,15 @@ When creating prefixes, a suggester has its own analysis chain, similar to the o
 
 ## Define a suggester
 
-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 example, a travel app might want to enable autocomplete on destinations, cities, and attractions. As such, all three fields would go in the fields collection.
+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.
 
-To create a suggester, add one to an index schema. You can have one suggester in an index (specifically, one suggester in the suggesters collection). A suggester takes a list of fields. 
+### Choose fields
 
-+ For suggestions, choose fields that best represent a single result. Names, titles, or other unique fields that distinguish among documents work best. If fields consist of similar or identical values, the suggestions will be composed 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 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.
 
-+ Make sure each field in the suggester `sourceFields` list uses either the default standard Lucene analyzer (`"analyzer": null`) or a [language analyzer](index-add-language-analyzers.md) (for example, `"analyzer": "en.Microsoft"`). 
+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"`). 
 
-  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.
+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.
 
 > [!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.
@@ -57,7 +57,7 @@ The best time to create a suggester is when you are also creating the field defi
 
 If you try to create a suggester using pre-existing fields, the API will disallow 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 will have to rebuild the index if you want to add them to a suggester. For more information, see [How to rebuild an Azure Cognitive Search index](search-howto-reindex.md).
 
-### Create using the REST API
+## 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). 
@@ -96,7 +96,7 @@ In the REST API, add suggesters through [Create Index](https://docs.microsoft.co
   }
   ```
 
-### Create using the .NET SDK
+## Create using .NET
 
 In C#, define a [Suggester object](https://docs.microsoft.com/dotnet/api/microsoft.azure.search.models.suggester?view=azure-dotnet). `Suggesters` is a collection but it can only take one item. 
 
@@ -119,37 +119,40 @@ private static void CreateHotelsIndex(SearchServiceClient serviceClient)
 }
 ```
 
-### Property reference
+## Property reference
 
 |Property      |Description      |
 |--------------|-----------------|
 |`name`        |The name of the suggester.|
-|`searchMode`  |The strategy used to search for candidate phrases. The only mode currently supported is `analyzingInfixMatching`, which performs flexible matching of phrases at the beginning or in the middle of sentences.|
+|`searchMode`  |The strategy used to search for candidate phrases. The only mode currently supported is `analyzingInfixMatching`, which currently matches on the beginning of a term.|
 |`sourceFields`|A list of one or more fields that are the source of the content for suggestions. Fields must be of type `Edm.String` and `Collection(Edm.String)`. If an analyzer is specified on the field, it must be a named analyzer from [this list](https://docs.microsoft.com/dotnet/api/microsoft.azure.search.models.analyzername?view=azure-dotnet) (not a custom analyzer).<p/> 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.<p/>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. |
 
 <a name="how-to-use-a-suggester"></a>
 
 ## Use a suggester
 
-A suggester is used in a query. After a suggester is created, call the appropriate API in your query logic to invoke the feature. 
+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](https://docs.microsoft.com/rest/api/searchservice/suggestions) 
 + [Autocomplete REST API](https://docs.microsoft.com/rest/api/searchservice/autocomplete) 
 + [SuggestWithHttpMessagesAsync method](https://docs.microsoft.com/dotnet/api/microsoft.azure.search.idocumentsoperations.suggestwithhttpmessagesasync?view=azure-dotnet)
 + [AutocompleteWithHttpMessagesAsync method](https://docs.microsoft.com/dotnet/api/microsoft.azure.search.idocumentsoperations.autocompletewithhttpmessagesasync?view=azure-dotnet&viewFallbackFrom=azure-dotnet)
 
-API usage is illustrated in the following call to the Autocomplete REST API. There are two takeaways from this example. First, as with all queries, the operation is against the documents collection of an index. Second, you can add query parameters. While many query parameters are common to both APIs, the list is different for each one.
+In a search application, client code should leverage a library like [jQuery UI Autocomplete](https://jqueryui.com/autocomplete/) to collect the partial query and provide the match. For more information about this task, see [Add autocomplete or suggested results to client code](search-autocomplete-tutorial.md).
+
+API usage is illustrated in the following call to the Autocomplete REST API. There are two takeaways from this example. First, as with all queries, the operation is against the documents collection of an index and the query includes a **search** parameter, which in this case provides the partial query. Second, you must add **suggesterName** to the request. If a suggester is not defined in the index, a call to autocomplete or suggestions will fail.
 
 ```http
-GET https://[service name].search.windows.net/indexes/[index name]/docs/autocomplete?[query parameters]  
-api-key: [admin or query key]
+POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2019-05-06
+{
+  "search": "minecraf",
+  "suggesterName": "sg"
+}
 ```
 
-If a suggester is not defined in the index, a call to autocomplete or suggestions will fail.
-
 ## Sample code
 
-+ [Create your first app in C#](tutorial-csharp-type-ahead-and-suggestions.md) sample demonstrates a suggester construction, suggested queries, autocomplete, and faceted navigation. This code sample runs on a sandbox Azure Cognitive Search service and uses a pre-loaded Hotels index so all you have to do is press F5 to run the application. No subscription or sign-in is necessary.
++ [Create your first app in C# (lesson 3 - Add search-as-you-type)](tutorial-csharp-type-ahead-and-suggestions.md) sample demonstrates a suggester construction, suggested queries, autocomplete, and faceted navigation. This code sample runs on a sandbox Azure Cognitive Search service and uses a pre-loaded Hotels index so all you have to do is press F5 to run the application. No subscription or sign-in is necessary.
 
 + [DotNetHowToAutocomplete](https://github.com/Azure-Samples/search-dotnet-getting-started/tree/master/DotNetHowToAutocomplete) is an older sample containing both C# and Java code. It also demonstrates a suggester construction, suggested queries, autocomplete, and faceted navigation. This code sample uses the hosted [NYCJobs](https://github.com/Azure-Samples/search-dotnet-asp-net-mvc-jobs) sample data. 
 
@@ -158,4 +161,4 @@ If a suggester is not defined in the index, a call to autocomplete or suggestion
 We recommend the following example to see how the requests are formulated.
 
 > [!div class="nextstepaction"]
-> [Suggestions and autocomplete examples](search-autocomplete-tutorial.md) 
+> [Add autocomplete and suggestions to client code](search-autocomplete-tutorial.md)