Merge pull request #15325 from microsoftgraph/users/tong/spellerRevision

Update Speller Doc For Graph Search API

api-reference/beta/api/search-query.md

@@ -1,6 +1,6 @@
 ---
 title: "searchEntity: query"
-description: "Runs the query specified in the request body. Search results are provided in the response"
+description: "Run a specified search query. Search results are provided in the response."
 ms.localizationpriority: medium
 author: "nmoreau"
 ms.prod: "search"
@@ -13,7 +13,7 @@ Namespace: microsoft.graph
 
 [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
 
-Runs the query specified in the request body. Search results are provided in the response.
+Run a specified search query. Search results are provided in the response.
 
 [!INCLUDE [search-api-deprecation](../../includes/search-api-deprecation.md)]
 
@@ -47,11 +47,10 @@ In the request body, provide a JSON object with the following parameters.
 | Parameter    | Type        | Description |
 |:-------------|:------------|:------------|
 |requests|[searchRequest](../resources/searchrequest.md) collection|A collection of one or more search requests each formatted in a JSON blob. Each JSON blob contains the types of resources expected in the response, the underlying sources, paging parameters, requested fields, and actual search query. <br> Be aware of [known limitations](../resources/search-api-overview.md#known-limitations) on searching specific combinations of entity types, and sorting or aggregating search results. |
-|queryAlterationOptions|[searchAlterationOptions](../resources/searchalterationoptions.md)|Query alteration options formatted in a JSON blob that contains two optional flags to for spelling correction. Optional. |
 
 ## Response
 
-If successful, this method returns a `HTTP 200 OK` response code and a [searchResponse](../resources/searchresponse.md) object in the response body.
+If successful, this method returns an `HTTP 200 OK` response code and a collection of [searchResponse](../resources/searchresponse.md) objects in the response body.
 
 
 ## Examples

api-reference/beta/resources/search-api-overview.md

@@ -145,7 +145,7 @@ See [refine search results](/graph/search-concept-aggregation) for examples that
 
 Spelling correction is a popular way to handle mismatches between typos in a user query and the correct words in matched contents. When typos are detected in the original user query, you can get the search result either for the original user query or the corrected alternate query. You can also get the spelling correction information for typos in the **queryAlterationResponse** property of the [searchresponse](searchresponse.md).
 
-In the request body of the [query](/graph/api/search-query?view=graph-rest-beta&preserve-view=true) method, specify the **queryAlterationOptions** that should be applied to the query for spelling corrections. The description of **queryAlterationOptions** is defined in the [searchAlterationOptions](./searchalterationoptions.md).
+In the [searchRequest](./searchrequest.md), specify the **queryAlterationOptions** that should be applied to the query for spelling corrections. For details about the **queryAlterationOptions** property, see [searchAlterationOptions](./searchalterationoptions.md).
 
 For examples that show how to use spelling corrections, see [Request spelling correction](/graph/search-concept-speller).
 

api-reference/beta/resources/search.md

@@ -1,6 +1,6 @@
 ---
-title: "Search"
-description: "Retrieve the search resource used to execute queries"
+title: "search resource type"
+description: "The top-level object that represents the search endpoint in Microsoft Graph."
 ms.localizationpriority: medium
 author: "nmoreau"
 ms.prod: "search"
@@ -13,29 +13,29 @@ Namespace: microsoft.graph
 
 [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
 
-The search resource is the top level object representing the search endpoint. It serves as an anchor to the [query](../api/search-query.md) action.
+The top-level object that represents the search endpoint. It serves as an anchor to the [query](../api/search-query.md) action.
 
-This resource is not expected to be called as such. Any request on the resource will incur a Bad Request.
+This resource is not called. Any request that calls this the resource will result in an HTTP `400 Bad Request` response.
 
 [!INCLUDE [search-api-preview](../../includes/search-api-preview-signup.md)]
 
-## JSON representation
+## Methods
 
-None
+| Method       | Return Type | Description |
+|:-------------|:------------|:------------|
+| [query](../api/search-query.md) | [searchResponse](searchresponse.md) collection| Run a specified search query. |
 
 ## Properties
 
-None
+None.
 
 ## Relationships
 
-None
+None.
 
-## Methods
+## JSON representation
 
-| Method       | Return Type | Description |
-|:-------------|:------------|:------------|
-| [query](../api/search-query.md) | [searchResponse](searchresponse.md)| Executes the query specified in the [searchRequest](../resources/searchrequest.md) |
+None.
 
 <!-- uuid: 16cd6b66-4b1a-43a1-adaf-3a886856ed98
 2019-02-04 14:57:30 UTC -->

api-reference/beta/resources/searchentity.md

@@ -13,14 +13,14 @@ Namespace: microsoft.graph
 
 [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
 
-A top level object representing the Microsoft Search API endpoint. It does not behave as any other resource in Graph, but serves as an anchor to the [query](../api/search-query.md) action. 
+A top-level object that represents the Microsoft Search API endpoint. This resource serves as an anchor to the [query](../api/search-query.md) action. 
 
 [!INCLUDE [search-api-preview](../../includes/search-api-preview-signup.md)]
 
 ## Methods
 |Method|Return type|Description|
 |:---|:---|:---|
-|[query](../api/search-query.md) |[searchResponse](searchresponse.md) | Runs the query specified in the request body.  |
+|[query](../api/search-query.md) |[searchResponse](searchresponse.md) collection | Run a specified search query.   |
 
 ## Properties
 None.
@@ -43,9 +43,9 @@ The following is a JSON representation of the resource.
 ```
 
 
-## Next steps
+## See also
 
-Explore the [query](../api/search-query.md) action.
+[query](../api/search-query.md)
 
 
 <!-- uuid: 16cd6b66-4b1a-43a1-adaf-3a886856ed98

api-reference/beta/resources/searchrequest.md

@@ -38,7 +38,7 @@ The JSON blob contains the types of resources expected in the response, the unde
 |sortProperties|[sortProperty](sortProperty.md) collection|Contains the ordered collection of fields and direction to sort results. There can be at most 5 sort properties in the collection. Optional.|
 |stored_fields (deprecated)|String collection |This is now replaced by the **fields** property. |
 |resultTemplateOptions|[resultTemplateOption](resultTemplateOption.md) collection|Provides the search result templates options for rendering connectors search results.|
-
+|queryAlterationOptions|[searchAlterationOptions](searchalterationoptions.md)|Query alteration options formatted in a JSON blob that contains two optional flags related to spelling correction. Optional. |
 
 ## JSON representation
 
@@ -65,7 +65,8 @@ The following is a JSON representation of the resource.
   "aggregations": [{"@odata.type": "microsoft.graph.aggregationOption"}],
   "aggregationFilters": ["String"],
   "enableTopResults": true,
-  "resultTemplateOptions": [{"@odata.type": "microsoft.graph.resultTemplateOption"}]  
+  "resultTemplateOptions": [{"@odata.type": "microsoft.graph.resultTemplateOption"}],
+  "queryAlterationOptions": {"@odata.type": "microsoft.graph.searchAlterationOptions"}
 }
 ```
 
@@ -78,6 +79,7 @@ The following is a JSON representation of the resource.
 - [Sort](/graph/search-concept-sort) search results
 - Use [aggregations](/graph/search-concept-aggregation) to refine search results
 - Use [display layout](/graph/search-concept-display-layout.md)
+- Enable [spell corrections](/graph/search-concept-speller) in search results
 
 
 <!-- uuid: 16cd6b66-4b1a-43a1-adaf-3a886856ed98

api-reference/beta/resources/searchresponse.md

@@ -1,6 +1,6 @@
 ---
 title: "searchResponse resource type"
-description: "Description of the searchResponse"
+description: "Represents results from a search query, and the terms used for the query. "
 ms.localizationpriority: medium
 author: "nmoreau"
 ms.prod: "search"
@@ -13,14 +13,16 @@ Namespace: microsoft.graph
 
 [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
 
-Represents the response from a search query. 
+Represents results from a search query, and the terms used for the query. 
 
 ## Properties
 
 | Property     | Type        | Description |
 |:-------------|:------------|:------------|
+|hitsContainers|[searchHitsContainer](searchhitscontainer.md) collection|A collection of search results.|
+|searchTerms|String collection|Contains the search terms sent in the initial search query.|
+|resultTemplates|[resultTemplate](resultTemplate.md) collection|A dictionary of resultTemplateIds and associated values, which include the name and JSON schema of the result templates.
 |queryAlterationResponse|[alterationResponse](alterationResponse.md)|Provides details of query alteration response for spelling correction.|
-|value|[searchResultSet](searchResultSet.md) collection|Represents results from a search query, and the terms used for the query.|
 
 ## JSON representation
 
@@ -38,7 +40,9 @@ The following is a JSON representation of the resource.
 ```json
 {
   "queryAlterationResponse": {"@odata.type": "microsoft.graph.alterationResponse"},
-  "value": [{"@odata.type": "microsoft.graph.searchResultSet"}]
+  "hitsContainers": [{"@odata.type": "microsoft.graph.searchHitsContainer"}],
+  "searchTerms": ["String"],
+  "resultTemplates": [{"@odata.type":"microsoft.graph.resultTemplateDictionary"}]
 }
 ```
 

changelog/Microsoft.MicrosoftSearch.json

@@ -206,7 +206,7 @@
       "WorkloadArea": "Search",
       "SubArea": ""
     },
-	{
+    {
       "ChangeList": [
         {
           "Id": "33000df9-0ed3-4beb-9dab-abfc603fc1a2",
@@ -329,6 +329,72 @@
       "CreatedDateTime": "2021-09-13T08:21:04.628851Z",
       "WorkloadArea": "Search",
       "SubArea": ""
+    },
+    {
+      "ChangeList": [
+        {
+          "Id": "400d3385-87a1-4e12-8f3d-7fa2c24b5c3f",
+          "ApiChange": "Property",
+          "ChangedApiName": "queryAlterationOptions",
+          "ChangeType": "Addition",
+          "Description": "Added the **queryAlterationOptions** property to the [searchRequest](https://docs.microsoft.com/en-us/graph/api/resources/searchRequest?view=graph-rest-beta) resource.",
+          "Target": "searchRequest"
+        },
+        {
+          "Id": "400d3385-87a1-4e12-8f3d-7fa2c24b5c3f",
+          "ApiChange": "Property",
+          "ChangedApiName": "hitsContainers",
+          "ChangeType": "Addition",
+          "Description": "Added the **hitsContainers** property to the [searchResponse](https://docs.microsoft.com/en-us/graph/api/resources/searchResponse?view=graph-rest-beta) resource.",
+          "Target": "searchResponse"
+        },
+        {
+          "Id": "400d3385-87a1-4e12-8f3d-7fa2c24b5c3f",
+          "ApiChange": "Property",
+          "ChangedApiName": "resultTemplates",
+          "ChangeType": "Addition",
+          "Description": "Added the **resultTemplates** property to the [searchResponse](https://docs.microsoft.com/en-us/graph/api/resources/searchResponse?view=graph-rest-beta) resource.",
+          "Target": "searchResponse"
+        },
+        {
+          "Id": "400d3385-87a1-4e12-8f3d-7fa2c24b5c3f",
+          "ApiChange": "Property",
+          "ChangedApiName": "searchTerms",
+          "ChangeType": "Addition",
+          "Description": "Added the **searchTerms** property to the [searchResponse](https://docs.microsoft.com/en-us/graph/api/resources/searchResponse?view=graph-rest-beta) resource.",
+          "Target": "searchResponse"
+        },
+        {
+          "Id": "400d3385-87a1-4e12-8f3d-7fa2c24b5c3f",
+          "ApiChange": "Property",
+          "ChangedApiName": "value",
+          "ChangeType": "Deletion",
+          "Description": "Removed the **value** property from the [searchResponse](https://docs.microsoft.com/en-us/graph/api/resources/searchResponse?view=graph-rest-beta) resource.",
+          "Target": "searchResponse"
+        },
+        {
+          "Id": "400d3385-87a1-4e12-8f3d-7fa2c24b5c3f",
+          "ApiChange": "Resource",
+          "ChangedApiName": "searchResultSet",
+          "ChangeType": "Deletion",
+          "Description": "Removed the **searchResultSet** resource type.",
+          "Target": "searchResultSet"
+        },
+        {
+          "Id": "400d3385-87a1-4e12-8f3d-7fa2c24b5c3f",
+          "ApiChange": "Method",
+          "ChangedApiName": "query",
+          "ChangeType": "Change",
+          "Description": "Updated the [query](https://docs.microsoft.com/en-us/graph/api/query?view=graph-rest-beta) method to return a collection of [searchResponse](https://docs.microsoft.com/en-us/graph/api/resources/searchresponse?view=graph-rest-beta) objects.",
+          "Target": "query"
+        }
+      ],
+      "Id": "400d3385-87a1-4e12-8f3d-7fa2c24b5c3f",
+      "Cloud": "Prod",
+      "Version": "beta",
+      "CreatedDateTime": "2021-01-28T12:49:29.5221544Z",
+      "WorkloadArea": "Search",
+      "SubArea": "Analytics"
     }
   ]
 }