Merge pull request #228337 from HeidiSteen/heidist-sql

[azure search] Facet restrictions noted in the sql relational doc

Author: prmerger-automator[bot]

articles/search/index-sql-relational-data.md

@@ -8,31 +8,31 @@ manager: nitinme
 ms.author: heidist
 ms.service: cognitive-search
 ms.topic: how-to
-ms.date: 02/08/2023
+ms.date: 02/22/2023
 ---
 # How to model relational SQL data for import and indexing in Azure Cognitive Search
 
 Azure Cognitive Search accepts a flat rowset as input to the [indexing pipeline](search-what-is-an-index.md). If your source data originates from joined tables in a SQL Server relational database, this article explains how to construct the result set, and how to model a parent-child relationship in an Azure Cognitive Search index.
 
-As an illustration, we'll refer to a hypothetical hotels database, based on [demo data](https://github.com/Azure-Samples/azure-search-sample-data/tree/master/hotels). Assume the database consists of a Hotels$ table with 50 hotels, and a Rooms$ table with rooms of varying types, rates, and amenities, for a total of 750 rooms. There is a one-to-many relationship between the tables. In our approach, a view will provide the query that returns 50 rows, one row per hotel, with associated room detail embedded into each row.
+As an illustration, we refer to a hypothetical hotels database, based on [demo data](https://github.com/Azure-Samples/azure-search-sample-data/tree/master/hotels). Assume the database consists of a Hotels$ table with 50 hotels, and a Rooms$ table with rooms of varying types, rates, and amenities, for a total of 750 rooms. There's a one-to-many relationship between the tables. In our approach, a view provides the query that returns 50 rows, one row per hotel, with associated room detail embedded into each row.
 
    ![Tables and view in the Hotels database](media/index-sql-relational-data/hotels-database-tables-view.png "Tables and view in the Hotels database")
 
 ## The problem of denormalized data
 
-One of the challenges in working with one-to-many relationships is that standard queries built on joined tables will return denormalized data, which doesn't work well in an Azure Cognitive Search scenario. Consider the following example that joins hotels and rooms.
+One of the challenges in working with one-to-many relationships is that standard queries built on joined tables return denormalized data, which doesn't work well in an Azure Cognitive Search scenario. Consider the following example that joins hotels and rooms.
 
 ```sql
 SELECT * FROM Hotels$
 INNER JOIN Rooms$
 ON Rooms$.HotelID = Hotels$.HotelID
 ```
+
 Results from this query return all of the Hotel fields, followed by all Room fields, with preliminary hotel information repeating for each room value.
 
    ![Denormalized data, redundant hotel data when room fields are added](media/index-sql-relational-data/denormalize-data-query.png "Denormalized data, redundant hotel data when room fields are added")
 
-
-While this query succeeds on the surface (providing all of the data in a flat row set), it fails in delivering the right document structure for the expected search experience. During indexing, Azure Cognitive Search will create one search document for each row ingested. If your search documents looked like the above results, you would have perceived duplicates - seven separate documents for the Twin Dome hotel alone. A query on "hotels in Florida" would return seven results for just the Twin Dome hotel, pushing other relevant hotels deep into the search results.
+While this query succeeds on the surface (providing all of the data in a flat row set), it fails in delivering the right document structure for the expected search experience. During indexing, Azure Cognitive Search creates one search document for each row ingested. If your search documents looked like the above results, you would have perceived duplicates - seven separate documents for the Twin Dome hotel alone. A query on "hotels in Florida" would return seven results for just the Twin Dome hotel, pushing other relevant hotels deep into the search results.
 
 To get the expected experience of one document per hotel, you should provide a rowset at the right granularity, but with complete information. This article explains how.
 
@@ -42,7 +42,7 @@ To deliver the expected search experience, your data set should consist of one r
 
 The solution is to capture the room detail as nested JSON, and then insert the JSON structure into a field in a view, as shown in the second step. 
 
-1. Assume you have two joined tables, Hotels$ and Rooms$, that contain details for 50 hotels and 750 rooms, and are joined on the HotelID field. Individually, these tables contain 50 hotels and 750 related rooms.
+1. Assume you've two joined tables, Hotels$ and Rooms$, that contain details for 50 hotels and 750 rooms and are joined on the HotelID field. Individually, these tables contain 50 hotels and 750 related rooms.
 
     ```sql
     CREATE TABLE [dbo].[Hotels$](
@@ -107,7 +107,7 @@ This rowset is now ready for import into Azure Cognitive Search.
 
 On the Azure Cognitive Search side, create an index schema that models the one-to-many relationship using nested JSON. The result set you created in the previous section generally corresponds to the index schema provided below (we cut some fields for brevity).
 
-The following example is similar to the example in [How to model complex data types](search-howto-complex-data-types.md#create-complex-fields). The *Rooms* structure, which has been the focus of this article, is in the fields collection of an index named *hotels*. This example also shows a complex type for *Address*, which differs from *Rooms* in that it is composed of a fixed set of items, as opposed to the multiple, arbitrary number of items allowed in a collection.
+The following example is similar to the example in [How to model complex data types](search-howto-complex-data-types.md#create-complex-fields). The *Rooms* structure, which has been the focus of this article, is in the fields collection of an index named *hotels*. This example also shows a complex type for *Address*, which differs from *Rooms* in that it's composed of a fixed set of items, as opposed to the multiple, arbitrary number of items allowed in a collection.
 
 ```json
 {
@@ -117,8 +117,9 @@ The following example is similar to the example in [How to model complex data ty
     { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false },
     { "name": "Description", "type": "Edm.String", "searchable": true, "analyzer": "en.lucene" },
     { "name": "Description_fr", "type": "Edm.String", "searchable": true, "analyzer": "fr.lucene" },
-    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": false },
+    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "facetable": true },
     { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "facetable": true },
+    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true },
     { "name": "Address", "type": "Edm.ComplexType",
       "fields": [
         { "name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
@@ -132,17 +133,25 @@ The following example is similar to the example in [How to model complex data ty
         { "name": "Description_fr", "type": "Edm.String", "searchable": true, "analyzer": "fr.lucene" },
         { "name": "Type", "type": "Edm.String", "searchable": true },
         { "name": "BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
-        { "name": "BedOptions", "type": "Edm.String", "searchable": true, "filterable": true, "facetable": true },
+        { "name": "BedOptions", "type": "Edm.String", "searchable": true, "filterable": true, "facetable": false },
         { "name": "SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
-        { "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
+        { "name": "SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": false},
         { "name": "Tags", "type": "Edm.Collection", "searchable": true }
       ]
     }
   ]
 }
 ```
 
-Given the previous result set and the above index schema, you have all the required components for a successful indexing operation. The flattened data set meets indexing requirements yet preserves detail information. In the Azure Cognitive Search index, search results will fall easily into hotel-based entities, while preserving the context of individual rooms and their attributes.
+Given the previous result set and the above index schema, you've all the required components for a successful indexing operation. The flattened data set meets indexing requirements yet preserves detail information. In the Azure Cognitive Search index, search results will fall easily into hotel-based entities, while preserving the context of individual rooms and their attributes.
+
+## Facet behavior on complex type subfields
+
+Fields that have a parent, such as the fields under Address and Rooms, are called *subfields*. Although you can assign a "facetable" attribute to a subfield, the count of the facet will always be for the main document.
+
+For complex types like Address, where there's just one "Address/City" or "Address/stateProvince" in the document, the facet behavior works as expected. However, in the case of Rooms, where there are multiple subdocuments for each main document, the facet counts can be misleading.
+
+As noted in [Model complex types](search-howto-complex-data-types.md): "the document counts returned in the facet results are calculated for the parent document (a hotel), not the subdocuments in a complex collection (rooms). For example, suppose a hotel has 20 rooms of type "suite". Given this facet parameter facet=Rooms/Type, the facet count is one for the hotel, not 20 for the rooms."
 
 ## Next steps
 

articles/search/search-indexer-howto-access-private.md

@@ -54,7 +54,7 @@ When evaluating shared private links for your scenario, remember these constrain
 
 + An Azure PaaS resource from the following list of supported resource types, configured to run in a virtual network, with a private endpoint created through Azure Private Link.
 
-+ You should have a minimum of Contributor permissions on both Cognitive Search and the Azure PaaS resource for which you're creating the shared private link.
++ You should have a minimum of Contributor permissions on both Azure Cognitive Search and the Azure PaaS resource for which you're creating the shared private link.
 
 <a name="group-ids"></a>
 
@@ -142,7 +142,9 @@ When you complete these steps, you have a shared private link that's provisioned
 > Preview API versions, either `2020-08-01-preview` or `2021-04-01-preview`, are required for group IDs that are in preview. The following resource types are in preview: `managedInstance`, `mySqlServer`, `sites`. 
 > For `managedInstance`, see [create a shared private link for SQL Managed Instance](#create-a-shared-private-link-for-a-sql-managed-instance) for help formulating a fully qualified domain name.
 
-Other tools like the portal, Azure PowerShell, or the Azure CLI have built-in mechanisms for account sign-in. If you're using a REST client, such as Postman, you'll need to provide a bearer token that allows your request to go through. Because it's easy and quick, this section uses Azure CLI steps for getting a bearer token. For other approaches, see [Manage with REST](search-manage-rest.md).
+While tools like Azure portal, Azure PowerShell, or the Azure CLI have built-in mechanisms for account sign-in, a REST client like Postman needs to provide a bearer token that allows your request to go through. 
+
+Because it's easy and quick, this section uses Azure CLI steps for getting a bearer token. For more durable approaches, see [Manage with REST](search-manage-rest.md).
 
 1. Open a command line and run `az login` for Azure sign-in.
 
@@ -152,6 +154,12 @@ Other tools like the portal, Azure PowerShell, or the Azure CLI have built-in me
    az account show
    ```
 
+   Change the subscription if it's not the right one:
+
+   ```azurecli
+   az account set --subscription {{Azure PaaS subscription ID}}
+   ```
+
 1. Create a bearer token, and then copy the entire token (everything between the quotation marks).
 
    ```azurecli
@@ -168,7 +176,7 @@ Other tools like the portal, Azure PowerShell, or the Azure CLI have built-in me
 
 1. Set the content type to JSON.
 
-1. Send the request. You should get a list of all shared private link resources that exist for your search service.
+1. Send the request. You should get a list of all shared private link resources that exist for your search service. Make sure there's no existing shared private link for the resource and sub-resource combination.
 
 1. Formulate a PUT request to [Create or Update Shared Private Link](/rest/api/searchmanagement/2020-08-01/shared-private-link-resources/create-or-update) for the Azure PaaS resource. Provide a URI and request body similar to the following example:
 
@@ -197,7 +205,7 @@ Other tools like the portal, Azure PowerShell, or the Azure CLI have built-in me
    az account get-access-token
    ```
 
-1. To check the status, rerun the first GET Shared Private Link request to monitor the provisioning state as it transitions from updating to succeeded.
+1. Send the request. To check the status, rerun the first GET Shared Private Link request to monitor the provisioning state as it transitions from updating to succeeded.
 
 ### [**PowerShell**](#tab/ps-create)