Merge pull request #298200 from jovanpop-msft/patch-844322

Cosmosdb more improvements

Author: prmerger-automator[bot]

articles/synapse-analytics/sql/query-cosmos-db-analytical-store.md

@@ -34,50 +34,62 @@ This article explains how to write a query with a serverless SQL pool that queri
 ## Overview
 
 Serverless SQL pool enables you to query Azure Cosmos DB analytical storage using `OPENROWSET` function. 
-- `OPENROWSET` that uses workspace managed identity to access the analytical store.
-- `OPENROWSET` with inline key. This syntax can be used to query Azure Cosmos DB collections without the need to prepare credentials.
-- `OPENROWSET` that references a credential that contains the Azure Cosmos DB account key. This syntax can be used to create views on Azure Cosmos DB collections.
-
-### [OPENROWSET with key or managed identity](#tab/openrowset-key)
-
-To support querying and analyzing data in an Azure Cosmos DB analytical store, a serverless SQL pool is used. The serverless SQL pool uses the `OPENROWSET` SQL syntax, so you must first convert your Azure Cosmos DB connection string to this format:
 
 ```sql
 OPENROWSET( 
        'CosmosDB',
        '<SQL connection string for Azure Cosmos DB>',
-       <Container name>
+       <other parameters>
     )  [ < with clause > ] AS alias
 ```
 
 The SQL connection string for Azure Cosmos DB includes the following components:
-- **Account Name** - The name of the Azure Cosmos DB account you are targeting.
-- **Database Name** - The container name, specified without quotation marks in the OPENROWSET syntax. If the container name contains special characters (for example, a dash -), it should be enclosed in square brackets ([]).
-- **Region Name** (optional) - The region of your CosmosDB analytical storage. If omitted, the container's primary region is used.
-- **AuthType** - set this option to `ManagedIdentity` if accessing CosmosDB using the Synapse workspace Managed Identity instead of the account key.
-- **Key** - The master key for accessing CosmosDB data, used if not utilizing the Synapse workspace managed identity.
-- **Endpoint** (optional) - required if your CosmosDB account does not follow the standard `*.documents.azure.com` format.
+- **account** - The name of the Azure Cosmos DB account you are targeting.
+- **database** - The container name, specified without quotation marks in the OPENROWSET syntax. If the container name contains special characters (for example, a dash -), it should be enclosed in square brackets ([]).
+- **region** (optional) - The region of your CosmosDB analytical storage. If omitted, the container's primary region is used.
+- **endpoint** (optional) - required if your CosmosDB account does not follow the standard `*.documents.azure.com` format.
 
-Some of this information can be derived from the standard Azure Cosmos DB connection string:
+> [!IMPORTANT]
+> The `endpoint` parameter is needed for accounts that don't match the standard `*.documents.azure.com` format. For example, if your Azure Cosmos DB account ends with `.documents.azure.us`, make sure that you add `endpoint=<account name>.documents.azure.us` in the connection string.
 
+These properties can be identified from the standard CosmosDb connection string, for example:
 ```
 AccountEndpoint=https://<database account name>.documents.azure.com:443/;AccountKey=<database account master key>;
 ```
 
 The SQL connection string can be formatted as follows:
-- Using the CosmosDB database account master key for authentication:
 ```sql
-'account=<database account name>;database=<database name>;region=<region name>;key=<database account master key>'
+'account=<database account name>;database=<database name>;region=<region name>'
 ```
 
-- Using the workspace managed identity instead of the CosmosDB account key:
+This connection string does not include the authentication information required to connect to CosmosDB analytical storage. Additional information is needed depending on the type of authentication used:
+- If `OPENROWSET` uses workspace managed identity to access the analytical store, you should add the `AuthType` property.
+- If `OPENROWSET` uses an inline account key, you should add the `key` property. This allows you to query Azure Cosmos DB collections without needing to prepare credentials.
+- Instead of including authentication information in the connection string, `OPENROWSET` can reference a credential that contains the Azure Cosmos DB account key. This approach can be used to create views on Azure Cosmos DB collections.
+
+These options are described below.
+
+### [OPENROWSET with key or managed identity](#tab/openrowset-key)
+
+To support querying and analyzing data in an Azure Cosmos DB analytical store, a serverless SQL pool is used. The serverless SQL pool uses the `OPENROWSET` SQL syntax, so you must first convert your Azure Cosmos DB connection string to this format:
+
 ```sql
-'account=<databases account name>;database=<database_name>;authtype=ManagedIdentity'
+OPENROWSET( 
+       'CosmosDB',
+       '<SQL connection string for Azure Cosmos DB>',
+       <Container name>
+    )  [ < with clause > ] AS alias
 ```
+In addition to the common properties in the SQL connection string that are described above (**account**, **database**, **region**, and **endpoint**), in this case, you need to add **one** of the following options:
+- **AuthType** - set this option to `ManagedIdentity` if accessing CosmosDB using the Synapse workspace Managed Identity.
+- **key** - The master key for accessing CosmosDB data, used if not utilizing the Synapse workspace managed identity.
 
-> [!IMPORTANT]
-> There's another optional parameter in connection string called `endpoint`. The `endpoint` param is needed for accounts that don't match the standard `*.documents.azure.com` format. For example, if your Azure Cosmos DB account ends with `.documents.azure.us`, make sure that you add `endpoint=<account name>.documents.azure.us` in the connection string.
+The examples of connection strings are shown in the following table:
 
+| Authentication type | Connection string |
+| --- | --- |
+| CosmosDB database account master key | `account=<account name>;database=<db name>;region=<region name>;key=<account master key>` |
+| Synapse workspace managed identity | `account=<account name>;database=<db name>;region=<region name>;authtype=ManagedIdentity` |
 
 ### [OPENROWSET with credential](#tab/openrowset-credential)