First draft

Author: seesharprun

articles/cosmos-db/merge.md

@@ -1,13 +1,14 @@
 ---
-title: Merge partitions in Azure Cosmos DB (preview)
-description: Learn more about the merge partitions capability in Azure Cosmos DB
+title: Merge partitions (preview)
+titleSuffix: Azure Cosmos DB
+description: Reduce the number of physical partitions used for your container with the merge capability in Azure Cosmos DB.
+ms.topic: conceptual
 author: seesharprun
 ms.author: sidandrews
+ms.reviewer: dech
 ms.service: cosmos-db
+ms.date: 02/07/2023
 ms.custom: event-tier1-build-2022, ignite-2022
-ms.topic: conceptual
-ms.reviewer: dech
-ms.date: 10/26/2022
 ---
 
 # Merge partitions in Azure Cosmos DB (preview)
@@ -70,69 +71,111 @@ Based on conditions 1 and 2, our container can potentially benefit from merging
 ### Merging physical partitions
 
 In PowerShell, when the flag `-WhatIf` is passed in, Azure Cosmos DB will run a simulation and return the expected result of the merge, but won't run the merge itself. When the flag isn't passed in, the merge will execute against the resource. When finished, the command will output the current amount of storage in KB per physical partition post-merge.
+
 > [!TIP]
 > Before running a merge, it's recommended to set your provisioned RU/s (either manual RU/s or autoscale max RU/s) as close as possible to your desired steady state RU/s post-merge, to help ensure the system calculates an efficient partition layout.
 
 #### [PowerShell](#tab/azure-powershell)
 
-```azurepowershell
-// Add the preview extension
-$parameters = @{
-    Name = "Az.CosmosDB"
-    AllowPrerelease = $true
-    Force = $true
-}
-Install-Module @parameters
-```
-
-```azurepowershell
-// API for NoSQL
-$parameters = @{
-    ResourceGroupName = "<resource-group-name>"
-    AccountName = "<cosmos-account-name>"
-    DatabaseName = "<cosmos-database-name>"
-    Name = "<cosmos-container-name>"
-    WhatIf = $true
-}
-Invoke-AzCosmosDBSqlContainerMerge @parameters
-```
-
-```azurepowershell
-// API for MongoDB
-$parameters = @{
-    ResourceGroupName = "<resource-group-name>"
-    AccountName = "<cosmos-account-name>"
-    DatabaseName = "<cosmos-database-name>"
-    Name = "<cosmos-container-name>"
-    WhatIf = $true
-}
-Invoke-AzCosmosDBMongoDBCollectionMerge @parameters
-```
+1. First, use [`Install-Module`](/powershell/module/powershellget/install-module) to install the [Az.CosmosDB](/powershell/module/az.cosmosdb/) module with pre-release features enabled.
+
+    ```azurepowershell-interactive
+    $parameters = @{
+        Name = "Az.CosmosDB"
+        AllowPrerelease = $true
+        Force = $true
+    }
+    Install-Module @parameters
+    ```
+
+##### [API for NoSQL](#tab/azure-powershell/nosql)
+
+1. Next, use `Invoke-AzCosmosDBSqlContainerMerge` with the `-WhatIf` parameter to preview the merge without actually performing the operation.
+
+    ```azurepowershell-interactive
+    $parameters = @{
+        ResourceGroupName = "<resource-group-name>"
+        AccountName = "<cosmos-account-name>"
+        DatabaseName = "<cosmos-database-name>"
+        Name = "<cosmos-container-name>"
+        WhatIf = $true
+    }
+    Invoke-AzCosmosDBSqlContainerMerge @parameters
+    ```
+
+1. Finally, start the merge by running the same command without the `-WhatIf` parameter.
+
+    ```azurepowershell-interactive
+    $parameters = @{
+        ResourceGroupName = "<resource-group-name>"
+        AccountName = "<cosmos-account-name>"
+        DatabaseName = "<cosmos-database-name>"
+        Name = "<cosmos-container-name>"
+    }
+    Invoke-AzCosmosDBSqlContainerMerge @parameters
+    ```
+
+##### [API for MongoDB](#tab/azure-powershell/mongodb)
+
+1. Next, use `Invoke-AzCosmosDBMongoDBCollectionMerge` with the `-WhatIf` parameter to preview the merge without actually performing the operation.
+
+    ```azurepowershell-interactive
+    $parameters = @{
+        ResourceGroupName = "<resource-group-name>"
+        AccountName = "<cosmos-account-name>"
+        DatabaseName = "<cosmos-database-name>"
+        Name = "<cosmos-container-name>"
+        WhatIf = $true
+    }
+    Invoke-AzCosmosDBMongoDBCollectionMerge @parameters
+    ```
+
+1. Finally, start the merge by running the same command without the `-WhatIf` parameter.
+
+    ```azurepowershell-interactive
+    $parameters = @{
+        ResourceGroupName = "<resource-group-name>"
+        AccountName = "<cosmos-account-name>"
+        DatabaseName = "<cosmos-database-name>"
+        Name = "<cosmos-container-name>"
+    }
+    Invoke-AzCosmosDBMongoDBCollectionMerge @parameters
+    ```
+
+---
 
 #### [Azure CLI](#tab/azure-cli)
 
-```azurecli
-// Add the preview extension
-az extension add --name cosmosdb-preview
-```
-
-```azurecli
-// API for NoSQL
-az cosmosdb sql container merge \
-    --resource-group '<resource-group-name>' \
-    --account-name '<cosmos-account-name>' \
-    --database-name '<cosmos-database-name>' \
-    --name '<cosmos-container-name>'
-```
-
-```azurecli
-// API for MongoDB
-az cosmosdb mongodb collection merge \
-    --resource-group '<resource-group-name>' \
-    --account-name '<cosmos-account-name>' \
-    --database-name '<cosmos-database-name>' \
-    --name '<cosmos-collection-name>'
-```
+1. First, use [`az extension add`](/cli/azure/extension#az-extension-add) to install the [cosmosdb-preview](https://github.com/azure/azure-cli-extensions/tree/main/src/cosmosdb-preview) Azure CLI extension.
+
+    ```azurecli-interactive
+    az extension add \
+        --name cosmosdb-preview
+    ```
+
+##### [API for NoSQL](#tab/azure-cli/nosql)
+
+1. Now, start the merge by using [`az cosmosdb sql container merge`](/cli/azure/cosmosdb/sql/container#az-cosmosdb-sql-container-merge).
+
+    ```azurecli-interactive
+    az cosmosdb sql container merge \
+        --resource-group '<resource-group-name>' \
+        --account-name '<cosmos-account-name>' \
+        --database-name '<cosmos-database-name>' \
+        --name '<cosmos-container-name>'
+    ```
+
+##### [API for MongoDB](#tab/azure-cli/mongodb)
+
+1. Now, start the merge by using [`az cosmosdb mongodb collection merge`](/cli/azure/cosmosdb/mongodb/collection#az-cosmosdb-mongodb-collection-merge).
+
+    ```azurecli-interactive
+    az cosmosdb mongodb collection merge \
+        --resource-group '<resource-group-name>' \
+        --account-name '<cosmos-account-name>' \
+        --database-name '<cosmos-database-name>' \
+        --name '<cosmos-collection-name>'
+    ```
 
 ---
 
@@ -146,6 +189,8 @@ You can track whether merge is still in progress by checking the **Activity Log*
 
 ## Limitations
 
+The following are limitations of the merge feature at this time.
+
 ### Preview eligibility criteria
 
 To enroll in the preview, your Azure Cosmos DB account must meet all the following criteria:
@@ -202,15 +247,15 @@ Support for other SDKs is planned for the future.
 
 If you enroll in the preview, the following connectors will fail.
 
-- Azure Data Factory <sup>1</sup>
-- Azure Stream Analytics <sup>1</sup>
-- Logic Apps <sup>1</sup>
-- Azure Functions <sup>1</sup>
-- Azure Search <sup>1</sup>
-- Azure Cosmos DB Spark connector <sup>1</sup>
+- Azure Data Factory ¹
+- Azure Stream Analytics ¹
+- Logic Apps ¹
+- Azure Functions ¹
+- Azure Search ¹
+- Azure Cosmos DB Spark connector ¹
 - Any third party library or tool that has a dependency on an Azure Cosmos DB SDK that isn't .NET V3 SDK v3.27.0 or higher
 
-<sup>1</sup> Support for these connectors is planned for the future.
+¹ Support for these connectors is planned for the future.
 
 ## Next steps