Merge pull request #213135 from Rodrigossz/main

SL for Gremlin API Preview

Author: BCS2022

articles/cosmos-db/analytical-store-introduction.md

@@ -17,6 +17,11 @@ Azure Cosmos DB analytical store is a fully isolated column store for enabling l
 
 Azure Cosmos DB transactional store is schema-agnostic, and it allows you to iterate on your transactional applications without having to deal with schema or index management. In contrast to this, Azure Cosmos DB analytical store is schematized to optimize for analytical query performance. This article describes in detailed about analytical storage.
 
+> [!NOTE]
+> Synapse Link for Gremlin API is now in preview. You can enable Synapse Link in your new or existing graphs using Azure CLI. For more information on how to configure it, click [here](configure-synapse-link.md).
+
+
+
 ## Challenges with large-scale analytics on operational data
 
 The multi-model operational data in an Azure Cosmos DB container is internally stored in an indexed row-based "transactional store". Row store format is designed to allow fast transactional reads and writes in the order-of-milliseconds response times, and operational queries. If your dataset grows large, complex analytical queries can be expensive in terms of provisioned throughput on the data stored in this format. High consumption of provisioned throughput in turn, impacts the performance of transactional workloads that are used by your real-time applications and services.
@@ -220,9 +225,10 @@ df = spark.read\
 
 There are two types of schema representation in the analytical store. These types define the schema representation method for all containers in the database account and have tradeoffs between the simplicity of query experience versus the convenience of a more inclusive columnar representation for polymorphic schemas.
 
-* Well-defined schema representation, default option for SQL (CORE) API accounts. 
+* Well-defined schema representation, default option for SQL (CORE) and Gremlin API accounts. 
 * Full fidelity schema representation, default option for Azure Cosmos DB API for MongoDB accounts.
 
+
 #### Well-defined schema representation
 
 The well-defined schema representation creates a simple tabular representation of the schema-agnostic data in the transactional store. The well-defined schema representation has the following considerations:
@@ -325,7 +331,7 @@ Here's a map of all the property data types and their suffix representations in
 
 ##### Working with the MongoDB `_id` field
 
-the MongoDB `_id` field is fundamental to every collection in MongoDB and originally has a hexadecimal representation. As you can see in the table above, `Full Fidelity Schema` will preserve its characteristics, creating a challenge for its vizualiation in Azure Synapse Analytics. For correct visualization, you must convert the `_id` datatype as below:
+the MongoDB `_id` field is fundamental to every collection in MongoDB and originally has a hexadecimal representation. As you can see in the table above, `Full Fidelity Schema` will preserve its characteristics, creating a challenge for its visualization in Azure Synapse Analytics. For correct visualization, you must convert the `_id` datatype as below:
 
 ###### Spark
 
@@ -353,7 +359,7 @@ FROM OPENROWSET('CosmosDB',
                 HTAP) WITH (_id VARCHAR(1000)) as HTAP
 ```
 
-#### Full fidelity schema for SQL API accounts
+#### Full fidelity schema for SQL or Gremlin API accounts
 
 It's possible to use full fidelity Schema for SQL (Core) API accounts, instead of the default option, by setting the schema type when enabling Synapse Link on a Cosmos DB account for the first time. Here are the considerations about changing the default schema representation type:
 
@@ -447,7 +453,7 @@ Synapse Link, and analytical store by consequence, has different compatibility l
 
 ### Backup Polices
 
-There two possible backup polices and to understand how to use them, two details about Cosmos DB backups are very important:
+There are two possible backup polices and to understand how to use them, the following details about Cosmos DB backups are very important:
 
  * The original container is restored without analytical store in both backup modes.
  * Cosmos DB doesn't support containers overwrite from a restore.
@@ -462,7 +468,7 @@ Now let's see how to use backup and restores from the analytical store perspecti
 
  #### Restoring a container with TTTL < ATTL
 
-When `transactional TTL` is smaller than `analytical TTL`, some data only exists in analytical store and won't be in the restored container. Again your have two possible situations:
+When `transactional TTL` is smaller than `analytical TTL`, some data only exists in analytical store and won't be in the restored container. Again, you have two possible situations:
  * To use the restored container as a replacement for the original container. In this case, when you enable Synapse Link at container level, only the data that was in transactional store will be included in the new analytical store. But please note that the analytical store of the original container remains available for queries as long as the original container exists. You may want to change your application to query both.
  * To use the restored container as a data source to backfill or update the data in the original container:
   * Analytical store will automatically reflect the data operations for the data that is in transactional store.

articles/cosmos-db/analytical-store-private-endpoints.md

@@ -4,7 +4,7 @@ description: Learn how to set up managed private endpoints for Azure Cosmos DB a
 author: AnithaAdusumilli
 ms.service: cosmos-db
 ms.topic: how-to
-ms.date: 03/02/2021
+ms.date: 09/29/2022
 ms.author: anithaa
 
 ---
@@ -17,6 +17,11 @@ In this article, you will learn how to set up managed private endpoints for Azur
 > [!NOTE]
 > If you are using Private DNS Zones for Cosmos DB and wish to create a Synapse managed private endpoint to the analytical store sub-resource, you must first create a DNS zone for the analytical store (`privatelink.analytics.cosmos.azure.com`) linked to your Cosmos DB's virtual network.
 
+
+> [!NOTE]
+> Synapse Link for Gremlin API is now in preview. You can enable Synapse Link in your new or existing graphs using Azure CLI. For more information on how to configure it, click [here](configure-synapse-link.md).
+
+
 ## Enable a private endpoint for the analytical store
 
 ### Set up Azure Synapse Analytics workspace with a managed virtual network and data-exfiltration

articles/cosmos-db/configure-custom-partitioning.md

@@ -1,28 +1,34 @@
 ---
 title: Configure custom partitioning to partition analytical store data (Preview)
-description: Learn how to trigger custom partitioning from Azure Synapse Spark notebook using Azure Synapse link for Azure Cosmos DB. It explains the configuration options.
+description: Learn how to trigger custom partitioning from Azure Synapse Spark notebook using Azure Synapse Link for Azure Cosmos DB. It explains the configuration options.
 author: Rodrigossz
 ms.service: cosmos-db
 ms.topic: conceptual
-ms.date: 11/02/2021
+ms.date: 09/29/2022
 ms.author: rosouz
 ms.custom: ignite-fall-2021
 ---
 
 # Configure custom partitioning to partition analytical store data (Preview)
-[!INCLUDE[appliesto-sql-api](includes/appliesto-sql-api.md)]
+[!INCLUDE[appliesto-sql-mongodb-gremlin-api](includes/appliesto-sql-mongodb-gremlin-api.md)]
+
 
 Custom partitioning enables you to partition analytical store data, on fields that are commonly used as filters in analytical queries, resulting in improved query performance.
 To learn more about custom partitioning, see [what is custom partitioning](custom-partitioning-analytical-store.md) article.
 
-To use custom partitioning, you must enable Azure Synapse Link on your Azure Cosmos DB account. To learn more, see [how to configure Azure Synapse Link](configure-synapse-link.md). Custom partitioning execution can be triggered from Azure Synapse Spark notebook using Azure Synapse link for Azure Cosmos DB.
+To use custom partitioning, you must enable Azure Synapse Link on your Azure Cosmos DB account. To learn more, see [how to configure Azure Synapse Link](configure-synapse-link.md). Custom partitioning execution can be triggered from Azure Synapse Spark notebook using Azure Synapse Link for Azure Cosmos DB.
 
 > [!IMPORTANT]
 > Custom partitioning feature is currently in public preview. This preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
 
 > [!NOTE]
 > Azure Cosmos DB accounts should have Azure Synapse Link enabled to take advantage of custom partitioning. Custom partitioning is currently supported for Azure Synapse Spark 2.0 only.
 
+
+> [!NOTE]
+> Synapse Link for Gremlin API is now in preview. You can enable Synapse Link in your new or existing graphs using Azure CLI. For more information on how to configure it, click [here](configure-synapse-link.md).
+
+
 ## Trigger a custom partitioning job
 
 Partitioning can be triggered from an Azure Synapse Spark notebook using Azure Synapse Link. You can schedule it to run as a background job, once or twice a day, or it can be executed more often if needed.  You can also choose one or more fields from the dataset as the analytical store partition key.

articles/cosmos-db/configure-synapse-link.md

@@ -14,6 +14,9 @@ ms.custom: references_regions, synapse-cosmos-db, devx-track-azurepowershell
 
 [Azure Synapse Link for Azure Cosmos DB](synapse-link.md) is a cloud-native hybrid transactional and analytical processing (HTAP) capability that enables you to run near real-time analytics over operational data in Azure Cosmos DB. Synapse Link creates a tight seamless integration between Azure Cosmos DB and Azure Synapse Analytics.
 
+> [!NOTE]
+> Synapse Link for Gremlin API is now in preview. You can enable Synapse Link in your new or existing Graphs using Azure CLI.
+
 Azure Synapse Link is available for Azure Cosmos DB SQL API or for Azure Cosmos DB API for Mongo DB accounts. Use the following steps to run analytical queries with the Azure Synapse Link for Azure Cosmos DB:
 
 * [Enable Azure Synapse Link for your Azure Cosmos DB accounts](#enable-synapse-link)
@@ -23,11 +26,11 @@ Azure Synapse Link is available for Azure Cosmos DB SQL API or for Azure Cosmos
 * [Improve performance with Best Practices](#best)
 * [Use Azure Synapse serverless SQL pool to analyze and visualize data in Power BI](#analyze-with-powerbi)
 
-You can also checkout the training module on how to [configure Azure Synapse Link for Azure Cosmos DB.](/training/modules/configure-azure-synapse-link-with-azure-cosmos-db/)
+You can also check the training module on how to [configure Azure Synapse Link for Azure Cosmos DB.](/training/modules/configure-azure-synapse-link-with-azure-cosmos-db/)
 
 ## <a id="enable-synapse-link"></a>Enable Azure Synapse Link for Azure Cosmos DB accounts
 
-The first step to use Synapse Link is to enable it for your Azure Cosmos DB database account. This is an one time operation.
+The first step to use Synapse Link is to enable it for your Azure Cosmos DB database account.
 
 > [!NOTE]
 > If you want to use customer-managed keys with Azure Synapse Link, you must configure your account's managed identity in your Azure Key Vault access policy before enabling Synapse Link on your account. To learn more, see how to [Configure customer-managed keys using Azure Cosmos DB accounts' managed identities](how-to-setup-cmk.md#using-managed-identity) article.
@@ -70,6 +73,15 @@ Use `--enable-analytical-storage true` for both **create** or **update** operati
 * [Create a new Azure Cosmos DB account with Synapse Link enabled](/cli/azure/cosmosdb#az-cosmosdb-create-optional-parameters)
 * [Update an existing Azure Cosmos DB account to enable Synapse Link](/cli/azure/cosmosdb#az-cosmosdb-update-optional-parameters)
 
+##### Use Azure CLI to enable Synapse Link for Azure Synapse Link for Gremlin API account. 
+Synapse Link for Gremlin API is now in preview. You can enable Synapse Link in your new or existing graphs using Azure CLI. Use the CLI command below to enable Synapse Link for your Gremlin API account:
+
+```cli
+az cosmosdb create --capabilities EnableGremlin --name MyCosmosDBGremlinDatabaseAccount --resource-group MyResourceGroup --enable-analytical-storage true
+```
+
+For existing Gremlin API accounts, replace `create` with `update`.
+
 #### PowerShell
 
 Use `EnableAnalyticalStorage true` for both **create** or **update** operations. You also need to choose the representation schema type. For SQL API accounts you can use `--analytical-storage-schema-type` with the values `FullFidelity` or `WellDefined`. For MongoDB API accounts, always use `-AnalyticalStorageSchemaType FullFidelity`.
@@ -124,6 +136,16 @@ The following options enable Synapse Link in a container by using Azure CLI by s
 * [Create an Azure Cosmos DB MongoDB collection](/cli/azure/cosmosdb/mongodb/collection#az-cosmosdb-mongodb-collection-create-examples)
 * [Create or update an Azure Cosmos DB SQL API container](/cli/azure/cosmosdb/sql/container#az-cosmosdb-sql-container-create)
 
+##### Use Azure CLI to enable Synapse Link for Azure Synapse Link for Gremlin API Graphs
+
+Synapse Link for Gremlin API is now in preview. You can enable Synapse Link in your new or existing Graphs using Azure CLI. Use the CLI command below to enable Synapse Link for your Gremlin API graphs:
+
+```cli
+az cosmosdb gremlin graph create --g MyResourceGroup --a MyCosmosDBGremlinDatabaseAccount --d MyGremlinDB --n MyGraph --analytical-storage-ttl –1
+```
+
+For existing graphs, replace `create` with `update`.
+
 #### PowerShell
 
 The following options enable Synapse Link in a container by using Azure CLI by setting the `-AnalyticalStorageTtl` property. 
@@ -244,7 +266,7 @@ You can find samples to get started with Azure Synapse Link on [GitHub](https://
 
 To learn more, see the following docs:
 
-* Checkout the training module on how to [configure Azure Synapse Link for Azure Cosmos DB.](/training/modules/configure-azure-synapse-link-with-azure-cosmos-db/)
+* Check the training module on how to [configure Azure Synapse Link for Azure Cosmos DB.](/training/modules/configure-azure-synapse-link-with-azure-cosmos-db/)
 
 * [Azure Cosmos DB analytical store overview.](analytical-store-introduction.md)
 

articles/cosmos-db/graph/TOC.yml

@@ -139,6 +139,18 @@
               href: ../burst-capacity.md
             - name: Burst capacity FAQ
               href: ../burst-capacity-faq.yml
+    - name: Analytics with Azure Synapse Link
+      items:
+        - name: Azure Synapse Link for Azure Cosmos DB
+          href: ../synapse-link.md
+        - name: Azure Synapse Link supported features
+          href: ../../synapse-analytics/synapse-link/concept-synapse-link-cosmos-db-support.md?toc=/azure/cosmos-db/toc.json&bc=/azure/cosmos-db/breadcrumb/toc.json
+        - name: Azure Synapse Link use cases
+          href: ../synapse-link-use-cases.md
+        - name: Azure Synapse Link FAQ
+          href: ../synapse-link-frequently-asked-questions.yml
+        - name: Analytical store - Overview
+          href: ../analytical-store-introduction.md              
     - name: Back up and restore
       items:
         - name: Back up and restore introduction
@@ -284,6 +296,24 @@
           href: ../tutorial-setup-ci-cd.md
         - name: Use Azure Cosmos DB Explorer
           href: ../data-explorer.md
+    - name: Analytics and BI with Azure Synapse Link
+      items:
+        - name: Configure Azure Synapse Link
+          href: ../configure-synapse-link.md
+        - name: Connect to Azure Synapse Link
+          href: ../../synapse-analytics/synapse-link/how-to-connect-synapse-link-cosmos-db.md?toc=/azure/cosmos-db/toc.json&bc=/azure/cosmos-db/breadcrumb/toc.json
+        - name: Analytical store and private endpoints
+          href: ../analytical-store-private-endpoints.md
+        - name: Query with Azure Synapse Spark 3
+          href: ../../synapse-analytics/synapse-link/how-to-query-analytical-store-spark-3.md?toc=/azure/cosmos-db/toc.json&bc=/azure/cosmos-db/breadcrumb/toc.json
+        - name: Query with Azure Synapse Spark 2
+          href: ../../synapse-analytics/synapse-link/how-to-query-analytical-store-spark.md?toc=/azure/cosmos-db/toc.json&bc=/azure/cosmos-db/breadcrumb/toc.json
+        - name: Query with serverless SQL pool
+          href: ../../synapse-analytics/sql/query-cosmos-db-analytical-store.md?toc=/azure/cosmos-db/toc.json&bc=/azure/cosmos-db/breadcrumb/toc.json
+        - name: Use Power BI with Azure Synapse Link
+          href: ../synapse-link-power-bi.md
+        - name: Configure custom partitioning
+          href: ../configure-custom-partitioning.md          
     - name: Back up and restore
       items:
         - name: Manage continuous backup

articles/cosmos-db/synapse-link-frequently-asked-questions.yml

@@ -6,7 +6,7 @@ metadata:
   ms.author: rosouz
   ms.service: cosmos-db
   ms.topic: faq
-  ms.date: 04/06/2022
+  ms.date: 09/29/2022
   ms.custom: synapse-cosmos-db
 title: Frequently asked questions about Azure Synapse Link for Azure Cosmos DB
 summary: |
@@ -21,7 +21,7 @@ sections:
       - question: |
           Is Azure Synapse Link supported for all Azure Cosmos DB APIs?
         answer: |
-          Azure Synapse Link is supported for the Azure Cosmos DB SQL (Core) API and for the Azure Cosmos DB API for MongoDB. 
+          Azure Synapse Link is supported for the Azure Cosmos DB SQL (Core) API and for the Azure Cosmos DB API for MongoDB. The support for Gremlin API is in preview now.
 
       - question: |
           Is Azure Synapse Link supported for multi-region Azure Cosmos DB accounts?
@@ -139,12 +139,12 @@ sections:
       - question: |
           Can I access analytical store with Azure Cosmos DB SDKs?
         answer: |
-          No, you can't access analytical store with the Azure Cosmos DB SDKs. You need to use Azure Synapse analitics, Spark or SQL serverless pools.
+          No, you can't access analytical store with the Azure Cosmos DB SDKs. You need to use Azure Synapse Analytics, Spark or SQL serverless pools.
       
       - question: |
           Can I access analytical store with Azure Cosmos DB REST APIs?
         answer: |
-          No, you can't access analytical store with the Azure Cosmos DB REST APIs. You need to use Azure Synapse analitics, Spark or SQL serverless pools.       
+          No, you can't access analytical store with the Azure Cosmos DB REST APIs. You need to use Azure Synapse Analytics, Spark or SQL serverless pools.       
           
       - question: |
           Is analytical store supported by Terraform?
@@ -196,7 +196,7 @@ sections:
           Yes, Azure Synapse Link supports configuring customer-managed keys using your Azure Cosmos DB account's managed identity. You can seamlessly encrypt the data across transactional and analytical stores using the same customer-managed keys in an automatic and transparent manner. To learn more, see  [configuring customer-managed keys using Azure Cosmos DB accounts' managed identities](how-to-setup-cmk.md#using-managed-identity) article.
       
       - question: |
-           Does Azure Synapse link provide network isolation with Azure Synapse managed virtual networks?
+           Does Azure Synapse Link provide network isolation with Azure Synapse managed virtual networks?
         answer: |
            Yes, You can control network access to the data in the transactional and analytical stores independently. Network isolation is done using separate managed private endpoints for each store, within managed virtual networks in Azure Synapse workspaces. To learn more, see how to [Configure private endpoints for analytical store](analytical-store-private-endpoints.md) article.