Merge pull request #1454 from mattgotteiner/matt/fix-semantic-ranker-doc-update-3

Fix semantic ranker semanticQuery documentation

Author: Stacyrch140

articles/search/semantic-how-to-query-request.md

@@ -51,7 +51,28 @@ A few query capabilities bypass relevance scoring, which makes them incompatible
 
 ## Set up the query
 
-In this step, add parameters to the query request. To be successful, your query should be full text search (using the `search` parameter to pass in a string) or a vector query, and the index should contain text fields with rich semantic content and a semantic configuration.
+By default, queries don't use semantic ranking. To use semantic ranking, two different parameters may be used. Each parameter supports a different set of scenarios:
+
+1. Set `queryType` to `semantic`:
+  + [Text search](search-lucene-query-architecture.md) with a simple plain text query. Empty queries result in no semantic ranking being applied to the results.
+  + [Hybrid search](hybrid-search-overview.md).
+  + [Simple](query-simple-syntax.md) or [full](query-lucene-syntax.md) syntax can't be used.
+1. Specify `semanticQuery`:
+  + [Text search](search-lucene-query-architecture.md) using the [simple](query-simple-syntax.md) or [full](query-lucene-syntax.md) syntax.
+  + [Vector search](vector-search-overview.md).
+  + [Hybrid search](hybrid-search-overview.md).
+  + The query specified for `semanticQuery` must be a plain text query. Empty queries aren't supported.
+
+The following table illustrates the supported scenarios depending on which semantic ranking parameter is used:
+
+| Semantic Ranker Parameter | Plain text search | [Simple text search syntax](query-simple-syntax.md) | [Full text search syntax](query-lucene-syntax.md) | [Vector search](vector-search-overview.md) | [Hybrid Search](hybrid-search-overview.md) | [Semantic answers](semantic-answers.md) and captions |
+|-|-|-|-|-|-|-|
+| Set `queryType` to `semantic` | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ |
+| Set `semanticQuery`<sup>1</sup> | ✅ | ✅ | ✅ | ✅ |✅ | ✅ |
+
+<sup>1</sup> `semanticQuery` isn't supported in the portal [search explorer](search-explorer.md).
+
+Regardless of the parameter chosen, the index should contain text fields with rich semantic content and a [semantic configuration](semantic-how-to-configure.md).
 
 ### [**Azure portal**](#tab/portal-query)
 
@@ -67,11 +88,11 @@ In this step, add parameters to the query request. To be successful, your query
 
 1. Enter a query, such as "historic hotel with good food", and select **Search**.
 
-1. Alternatively, select **JSON view** and paste definitions into the query editor:
+1. Alternatively, select **JSON view** and paste definitions into the query editor. The Azure portal doesn't support using `semanticQuery`, so setting `queryType` to `"semantic"` is required:
 
    :::image type="content" source="./media/semantic-search-overview/semantic-portal-json-query.png" alt-text="Screenshot showing JSON query syntax in the Azure portal." border="true":::
 
-   Here's a JSON example that you can paste into the view:
+   JSON example for setting query type to semantic that you can paste into the view:
 
     ```json
     {
@@ -81,7 +102,6 @@ In this step, add parameters to the query request. To be successful, your query
       "semanticConfiguration": "my-semantic-config",
       "captions": "extractive|highlight-true",
       "answers": "extractive|count-3",
-      "queryLanguage": "en-us",
       "highlightPreTag": "<strong>",
       "highlightPostTag": "</strong>",
       "select": "HotelId,HotelName,Description,Category"
@@ -92,50 +112,72 @@ In this step, add parameters to the query request. To be successful, your query
 
 Use [Search Documents](/rest/api/searchservice/documents/search-post) to formulate the request.
 
-A response includes an `@search.rerankerScore` automatically. If you want captions or answers in the response, add captions and answers to the request.
+A response includes an `@search.rerankerScore` automatically. If you want captions or answers in the response, enable semantic ranking by setting `queryType` to `semantic` or setting `semanticQuery` and adding captions and answers to the request.
 
 The following example in this section uses the [hotels-sample-index](search-get-started-portal.md) to demonstrate semantic ranking with semantic answers and captions.
 
-1. Paste the following request into a web client as a template. Replace `search-service-name` with your search service name and replace `hotels-sample-index` if you have a different index name.
+If you want to set `queryType` to `semantic`, paste the following request into a web client as a template. Replace `search-service-name` with your search service name and replace `hotels-sample-index` if you have a different index name.
 
-    ```http
-    POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01      
-    {
-          "search": "interesting hotel with restaurant on site and cozy lobby or shared area",
-          "count": true,
-          "queryType": "semantic",
-          "semanticConfiguration": "semantic-config",
-          "captions": "extractive|highlight-true",
-          "answers": "extractive|count-3",
-          "queryLanguage": "en-us",
-          "highlightPreTag": "<strong>",
-          "highlightPostTag": "</strong>",
-          "select": "HotelId,HotelName,Description,Category"
-    }
-    ```
+```http
+POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
+{
+      "search": "interesting hotel with restaurant on site and cozy lobby or shared area",
+      "count": true,
+      "queryType": "semantic",
+      "semanticConfiguration": "semantic-config",
+      "captions": "extractive|highlight-true",
+      "answers": "extractive|count-3",
+      "highlightPreTag": "<strong>",
+      "highlightPostTag": "</strong>",
+      "select": "HotelId,HotelName,Description,Category"
+}
+```
 
-1. Set "queryType" to "semantic".
+1. Set `queryType` to `semantic`.
 
-1. Set "search" to a full text search query. Your search string can support either the [simple syntax](query-simple-syntax.md) or [full Lucene syntax](query-lucene-syntax.md). Semantic ranking is an extension of full text search, so while "search" isn't required, you won't get an expected outcome if it's an empty search (`"search": "*"`).
+1. Set `search` to a simple plain text query. Since the `queryType` is set to `semantic`,  [simple syntax](query-simple-syntax.md) or [full Lucene syntax](query-lucene-syntax.md) aren't supported. Supplying `*` or an empty string results in no semantic ranking being applied to the query.
 
-1. Set "semanticConfiguration" to a [predefined semantic configuration](semantic-how-to-configure.md) that's embedded in your index.
+1. Set `semanticConfiguration` to a [predefined semantic configuration](semantic-how-to-configure.md) that's embedded in your index.
 
-1. Set "answers" to specify whether [semantic answers](semantic-answers.md) are included in the result. Currently, the only valid value for this parameter is `extractive`. Answers can be configured to return a maximum of 10. The default is one. This example shows a count of three answers: `extractive|count-3`.
+1. Set `answers` to specify whether [semantic answers](semantic-answers.md) are included in the result. Currently, the only valid value for this parameter is `extractive`. Answers can be configured to return a maximum of 10. The default is one. This example shows a count of three answers: `extractive|count-3`.
 
    Answers aren't guaranteed on every request. To get an answer, the query must look like a question and the content must include text that looks like an answer.
 
-1. Set "captions" to specify whether semantic captions are included in the result. Currently, the only valid value for this parameter is `extractive`. Captions can be configured to return results with or without highlights. The default is for highlights to be returned. This example returns captions without highlights: `extractive|highlight-false`.
+1. Set `captions` to specify whether semantic captions are included in the result. Currently, the only valid value for this parameter is `extractive`. Captions can be configured to return results with or without highlights. The default is for highlights to be returned. This example returns captions without highlights: `extractive|highlight-false`.
 
    The basis for captions and answers are the fields referenced in the "semanticConfiguration". These fields are under a combined limit in the range of 2,000 tokens or approximately 20,000 characters. If you anticipate a token count exceeding this limit, consider a [data chunking step](vector-search-how-to-chunk-documents.md) using the [Text split skill](cognitive-search-skill-textsplit.md). This approach introduces a dependency on an [AI enrichment pipeline](cognitive-search-concept-intro.md) and [indexers](search-indexer-overview.md).
 
-1. Set "highlightPreTag" and "highlightPostTag" if you want to override the default highlight formatting that's applied to captions.
+1. Set `highlightPreTag` and `highlightPostTag` if you want to override the default highlight formatting that's applied to captions.
 
    Captions apply highlight formatting over key passages in the document that summarize the response. The default is `<em>`. If you want to specify the type of formatting (for example, yellow background), you can set the highlightPreTag and highlightPostTag.
 
-1. Set ["select"](search-query-odata-select.md) to specify which fields are returned in the response, and "count" to return the number of matches in the index. These parameters improve the quality of the request and readability of the response.
+1. Set [select](search-query-odata-select.md) to specify which fields are returned in the response, and "count" to return the number of matches in the index. These parameters improve the quality of the request and readability of the response.
 
 1. Send the request to execute the query and return results.
 
+If you want to use "semanticQuery" in order to use [vector search](vector-search-overview.md), [simple text syntax](query-simple-syntax.md), or [full text syntax](query-lucene-syntax.md), adjust your request to the following JSON:
+
+```http
+POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
+{
+    "search": "Description:breakfast",
+    "semanticQuery": "interesting hotel with restaurant on site and cozy lobby or shared area",
+    "count": true,
+    "queryType": "full",
+    "semanticConfiguration": "semantic-config",
+    "captions": "extractive|highlight-true",
+    "answers": "extractive|count-3",
+    "highlightPreTag": "<strong>",
+    "highlightPostTag": "</strong>",
+    "select": "HotelId,HotelName,Description,Category"
+}
+    ```
+
+1. Set `queryType` to the search syntax you're using, either [simple](query-simple-syntax.md) or [full](query-lucene-syntax.md).
+
+1. Set `semanticQuery` to the simple plain text query you want to use for semantic ranking. Empty queries aren't supported.
+
+
 ### [**.NET SDK**](#tab/dotnet-query)
 
 Use QueryType or SemanticQuery to invoke semantic ranker on a semantic query. The [following example](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/search/Azure.Search.Documents/samples/Sample08_SemanticSearch.md) is from the Azure SDK team.
@@ -151,7 +193,6 @@ SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
             QueryCaption = new(QueryCaptionType.Extractive),
             QueryAnswer = new(QueryAnswerType.Extractive)
         },
-        QueryLanguage = QueryLanguage.EnUs,
         QueryType = SearchQueryType.Semantic
     });
 
@@ -187,6 +228,23 @@ await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
 Console.WriteLine($"Total number of search results:{count}");
 ```
 
+To use `semanticQuery` instead of setting `queryType` to `semantic`, the search code snippet can be replaced with the following code snippet:
+
+```csharp
+SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
+    "Luxury hotel",
+    new SearchOptions
+    {
+        SemanticSearch = new()
+        {
+            SemanticConfigurationName = "my-semantic-config",
+            QueryCaption = new(QueryCaptionType.Extractive),
+            QueryAnswer = new(QueryAnswerType.Extractive),
+            SemanticQuery = "Is there any hotel located on the main commercial artery of the city in the heart of New York?"
+        }
+    });
+```
+
 ---
 
 ## Evaluate the response