Merge pull request #231797 from seesharprun/cosmos-update-merge

prmerger-automator[bot] · web-flow · commit 6fc77bdfa726 · 2023-03-22T23:01:14.000Z
Cosmos DB | Update merge article with Java v4 support
diff --git a/articles/cosmos-db/merge.md b/articles/cosmos-db/merge.md
@@ -7,7 +7,7 @@ author: seesharprun
 ms.author: sidandrews
 ms.reviewer: dech
 ms.service: cosmos-db
-ms.date: 02/07/2023
+ms.date: 03/22/2023
 ms.custom: event-tier1-build-2022, ignite-2022
 ---
 
@@ -21,10 +21,10 @@ Merging partitions in Azure Cosmos DB (preview) allows you to reduce the number
 
 To get started using partition merge, navigate to the **Features** page in your Azure Cosmos DB account. Select and enable the **Partition merge (preview)** feature.
 
-Before enabling the feature, verify that your Azure Cosmos DB account(s) meet all the [preview eligibility criteria](#preview-eligibility-criteria). Once you've enabled the feature, it will take 15-20 minutes to take effect.
+Before enabling the feature, verify that your Azure Cosmos DB account(s) meet all the [preview eligibility criteria](#preview-eligibility-criteria). Once you've enabled the feature, it takes 15-20 minutes to take effect.
 
 > [!CAUTION]
-> When merge is enabled on an account, only requests from .NET SDK version >= 3.27.0 will be allowed on the account, regardless of whether merges are ongoing or not. Requests from other SDKs (older .NET SDK, Java, JavaScript, Python, Go) or unsupported connectors (Azure Data Factory, Azure Search, Azure Cosmos DB Spark connector, Azure Functions, Azure Stream Analytics, and others) will be blocked and fail. Ensure you have upgraded to a supported SDK version before enabling the feature. After the feature is enabled or disabled, it may take 15-20 minutes to fully propagate to the account. If you plan to disable the feature after you've completed using it, it may take 15-20 minutes before requests from SDKs and connectors that are not supported for merge are allowed.
+> When merge is enabled on an account, only requests from .NET SDK version >= 3.27.0 or Java SDK >= 4.42.0 will be allowed on the account, regardless of whether merges are ongoing or not. Requests from other SDKs (older .NET SDK, older Java SDK, any JavaScript SDK, any Python SDK, any Go SDK) or unsupported connectors (Azure Data Factory, Azure Search, Azure Cosmos DB Spark connector, Azure Functions, Azure Stream Analytics, and others) will be blocked and fail. Ensure you have upgraded to a supported SDK version before enabling the feature. After the feature is enabled or disabled, it may take 15-20 minutes to fully propagate to the account. If you plan to disable the feature after you've completed using it, it may take 15-20 minutes before requests from SDKs and connectors that are not supported for merge are allowed.
 
 :::image type="content" source="media/merge/merge-feature-blade.png" alt-text="Screenshot of Features pane and Partition merge feature.":::
 
@@ -48,7 +48,7 @@ Condition 2 often occurs when you delete/TTL a large volume of data, leaving unu
 
 To determine the current RU/s per physical partition, from your Cosmos account, navigate to **Metrics**. Select the metric **Physical Partition Throughput** and filter to your database and container. Apply splitting by **PhysicalPartitionId**.
 
-For containers using autoscale, this metric will show the max RU/s currently provisioned on each physical partition. For containers using manual throughput, this metric will show the manual RU/s on each physical partition.
+For containers using autoscale, this metric shows the max RU/s currently provisioned on each physical partition. For containers using manual throughput, this metric shows the manual RU/s on each physical partition.
 
 In the below example, we have an autoscale container provisioned with 5000 RU/s (scales between 500 - 5000 RU/s). It has five physical partitions and each physical partition has 1000 RU/s.
 
@@ -70,14 +70,14 @@ 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.
+In PowerShell, when the flag `-WhatIf` is passed in, Azure Cosmos DB runs a simulation and return the expected result of the merge. This result is returned despite the merge itself not running. When the flag isn't passed in, the merge executes against the resource. When finished, the command outputs 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)
 
-Use [`Install-Module`](/powershell/module/powershellget/install-module) to install the [Az.CosmosDB](/powershell/module/az.cosmosdb/) module with pre-release features enabled.
+Use [`Install-Module`](/powershell/module/powershellget/install-module) to install the [Az.CosmosDB](/powershell/module/az.cosmosdb/) module with prerelease features enabled.
 
 ```azurepowershell-interactive
 $parameters = @{
@@ -198,14 +198,14 @@ To enroll in the preview, your Azure Cosmos DB account must meet all the followi
 - Your Azure Cosmos DB account uses API for NoSQL or MongoDB with version >=3.6.
 - Your Azure Cosmos DB account is using provisioned throughput (manual or autoscale). Merge doesn't apply to serverless accounts.
   - Currently, merge isn't supported for shared throughput databases. You may enroll an account that has both shared throughput databases and containers with dedicated throughput (manual or autoscale).
-  - However, only the containers with dedicated throughput will be able to be merged.
+  - However, only the containers with dedicated throughput are able to be merged.
 - Your Azure Cosmos DB account is a single-write region account (merge isn't currently supported for multi-region write accounts).
 - Your Azure Cosmos DB account doesn't use any of the following features:
   - [Point-in-time restore](continuous-backup-restore-introduction.md)
   - [Customer-managed keys](how-to-setup-cmk.md)
   - [Analytical store](analytical-store-introduction.md)
 - Your Azure Cosmos DB account uses bounded staleness, session, consistent prefix, or eventual consistency (merge isn't currently supported for strong consistency).
-- If you're using API for NoSQL, your application must use the Azure Cosmos DB .NET V3 SDK, version 3.27.0 or higher. When merge preview enabled on your account, all requests sent from non .NET SDKs or older .NET SDK versions won't be accepted.
+- If you're using API for NoSQL, your application must use the Azure Cosmos DB .NET v3 SDK (version 3.27.0 or higher) or Java v4 SDK (version 4.42.0 or higher). When merge preview is enabled on your account, the account doesn't accept requests sent from non .NET/Java SDKs or older .NET/Java SDK versions.
   - There are no SDK or driver requirements to use the feature with API for MongoDB.
 - Your Azure Cosmos DB account doesn't use any currently unsupported connectors:
   - Azure Data Factory
@@ -214,13 +214,13 @@ To enroll in the preview, your Azure Cosmos DB account must meet all the followi
   - 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
+  - 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 Java v4 SDK >= 4.42.0
 
 ### Account resources and configuration
 
 - Merge is only available for API for NoSQL and MongoDB accounts. For API for MongoDB accounts, the MongoDB account version must be 3.6 or greater.
 - Merge is only available for single-region write accounts. Multi-region write account support isn't available.
-- Accounts using merge functionality can't also use these features (if these features are added to a merge enabled account, resources in the account will no longer be able to be merged):
+- Accounts using merge functionality can't also use these features (if these features are added to a merge enabled account, the account can't merge resources):
   - [Point-in-time restore](continuous-backup-restore-introduction.md)
   - [Customer-managed keys](how-to-setup-cmk.md)
   - [Analytical store](analytical-store-introduction.md)
@@ -230,30 +230,35 @@ To enroll in the preview, your Azure Cosmos DB account must meet all the followi
 
 ### SDK requirements (API for NoSQL only)
 
-Accounts with the merge feature enabled are supported only when you use the latest version of the .NET v3 SDK. When the feature is enabled on your account (regardless of whether you run the merge), you must only use the supported SDK using the account. Requests sent from other SDKs or earlier versions won't be accepted. As long as you're using the supported SDK, your application can continue to run while a merge is ongoing.
+Accounts with the merge feature enabled are supported only when you use the latest version of the .NET v3 SDK or Java v4 SDK. When the feature is enabled on your account (regardless of whether you run the merge), you must only use the supported SDK using the account. Requests sent from other SDKs or earlier versions aren't accepted. As long as you're using the supported SDK, your application can continue to run while a merge is ongoing.
 
 Find the latest version of the supported SDK:
 
 | SDK | Supported versions | Package manager link |
 | --- | --- | --- |
-| **.NET SDK v3** | *>= 3.27.0* | <https://www.nuget.org/packages/Microsoft.Azure.Cosmos/> |
+| **.NET SDK v3** | *>= 3.27.0* | <https://www.nuget.org/packages/Microsoft.Azure.Cosmos> |
+| **Java SDK v4** | *>= 4.42.0* | <https://mvnrepository.com/artifact/com.azure/azure-cosmos> |
 
 Support for other SDKs is planned for the future.
 
 > [!TIP]
-> You should ensure that your application has been updated to use a compatible SDK version prior to enrolling in the preview. If you're using the legacy .NET V2 SDK, follow the [.NET SDK v3 migration guide](sql/migrate-dotnet-v3.md).
+> You should ensure that your application has been updated to use a compatible SDK version prior to enrolling in the preview. If you're using a legacy SDK, follow the appropriate migration guide:
+>
+> - Legacy .NET v2 SDK: [.NET SDK v3 migration guide](nosql/migrate-dotnet-v3.md)
+> - Legacy Java v3 SDK: [Java SDK v4 migration guide](nosql/migrate-java-v4-sdk.md)
+>
 
 ### Unsupported connectors
 
-If you enroll in the preview, the following connectors will fail.
+If you enroll in the preview, the following connectors fail.
 
 - 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
+- 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 Java v4 SDK >= 4.42.0
 
 ¹ Support for these connectors is planned for the future.
 
