Azure Cosmos DB 中的合并分区功能（预览版）

项目
12/20/2024

适用对象： NoSQL MongoDB

使用 Azure Cosmos DB 中的合并分区功能（预览版），你可以减少原地用于容器的物理分区数。通过合并，具有碎片化吞吐量（每个分区的 RU/秒值较低）或碎片化存储（每个分区的存储较少）的容器可以重做其物理分区。如果容器的吞吐量已纵向扩展且需要缩减回去，合并可以帮助解决吞吐量碎片化问题。对于相同数量的预配 RU/秒，具有较少的物理分区意味着每个物理分区可以获得更多的总体 RU/秒。如果从容器中删除大量数据，分区数量最小化可以降低速率受限的可能性，并且每个分区的 RU/秒也会较低。合并可以帮助清除未使用的分区或空分区，从而有效地解决存储碎片化问题。

入门

若要开始使用分区合并，请导航到你的 Azure Cosmos DB 帐户中的“功能”页。选择并启用“分区合并（预览版）”功能。

在启用该功能之前，请验证你的 Azure Cosmos DB 帐户是否满足所有预览版资格条件。启用该功能后，需要经过 15-20 分钟才会生效。

注意

在帐户上启用合并后，无论是否正在进行合并，该帐户都将仅允许来自 .NET SDK 版本 >=3.27.0、Java SDK >= 4.42.0 或 Azure Cosmos DB Spark 连接器 >=4.18.0 的请求。来自其他 SDK（旧版 .NET SDK、旧版 Java SDK、任何 JavaScript SDK、任何 Python SDK、任何 Go SDK）或不受支持的连接器（Azure 数据工厂、Azure 搜索、Azure Functions、Azure 流分析等）的请求将被阻止并失败。在启用该功能之前，请确保已升级到受支持的 SDK 版本。启用或禁用该功能后，可能需要经过 15-20 分钟它才能完全传播到帐户。如果你打算在使用完该功能后将其禁用，可能需要等待 15-20 分钟，然后才会允许来自不支持合并的 SDK 和连接器的请求。

“功能”窗格和“分区合并”功能的屏幕截图。

若要检查 Azure Cosmos DB 帐户是否符合预览版的条件，可以使用Azure 门户中的内置资格检查器。在 Azure 门户的 Azure Cosmos DB 帐户概述页中，导航到“诊断并解决问题”->“吞吐量和缩放”->分区合并。运行“检查分区合并预览版的资格”诊断。

屏幕截图显示了“诊断并解决问题”页中的“吞吐量和缩放”内容。

如何标识要合并的容器

满足以下两个条件的容器可能受益于分区合并：

条件 1：每个物理分区的当前 RU/秒 <3000 RU/秒
条件 2：每个物理分区的当前平均存储 (GB) <20 GB

如果以前纵向扩展了 RU/秒（通常是为了进行数据引入），而现在希望以稳定状态进行纵向缩减，则通常会出现条件 1。如果删除/TTL 大量数据，留下未使用的分区，通常会出现条件 2。

条件 1

若要确定每个物理分区的当前 RU/秒，请从 Cosmos 帐户导航到“指标”。选择“物理分区吞吐量”指标，并筛选到数据库和容器。按 PhysicalPartitionId 应用拆分。

对于使用自动缩放的容器，此指标会显示当前在每个物理分区上预配的最大 RU/秒。对于使用手动吞吐量的容器，此指标会显示每个物理分区上的手动 RU/秒。

在下面的示例中，我们预配了 5000 RU/秒的自动缩放容器（在 500 - 5000 RU/秒之间缩放）。它有 5 个物理分区，每个物理分区为 1000 RU/秒。

屏幕截图显示 Azure 门户中的 Azure Monitor 指标“物理分区吞吐量”。

条件 2

若要确定每个物理分区的当前平均存储，请先找到容器的总体存储（数据 + 索引）。

导航至“Insights”>“存储”>“数据和索引使用情况”。总存储是数据和索引使用情况的总和。在以下示例中，容器总共有 74 GB 的存储。

屏幕截图显示 Azure 门户中用于容器的 Azure Monitor 指标“存储(数据 + 索引)”。

接下来，查找物理分区的总数。此指标是在条件 1 中看到的 PhysicalPartitionThroughput 图表中的非重复 PhysicalPartitionId 数。在我们的示例中，我们有 5 个物理分区。

最后计算：总存储（以 GB 为单位）/物理分区数。在我们的示例中，平均值为 (74 GB/5 个物理分区) = 每个物理分区 14.8 GB。

根据条件 1 和条件 2，我们的容器可能会受益于分区合并。

合并物理分区

在 PowerShell 中，传入标志 -WhatIf 时，Azure Cosmos DB 会运行模拟并返回合并的预期结果。尽管合并本身未运行，此结果仍会返回。如果未传入标志，合并会针对资源执行。完成后，该命令会在合并后以 KB 为单位输出每个物理分区的当前存储量。

提示

在运行合并之前，建议将你的预配 RU/秒（手动 RU/秒或自动缩放最大 RU/秒）设置为尽可能接近你在合并后所需的稳定态 RU/秒，以帮助确保系统计算出高效的分区布局。

PowerShell
Azure CLI

使用 Install-Module 安装启用了预发行功能的 Az.CosmosDB 模块。

$parameters = @{
    Name = "Az.CosmosDB"
    AllowPrerelease = $true
    Force = $true
}
Install-Module @parameters

使用 az extension add 安装 cosmosdb-preview Azure CLI 扩展。

az extension add \
    --name cosmosdb-preview

将 Invoke-AzCosmosDBSqlContainerMerge 与 -WhatIf 参数一起使用可以预览合并而不实际执行操作。

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<cosmos-account-name>"
    DatabaseName = "<cosmos-database-name>"
    Name = "<cosmos-container-name>"
    WhatIf = $true
}
Invoke-AzCosmosDBSqlContainerMerge @parameters

在不使用 -WhatIf 参数的情况下运行同一命令可以启动合并。

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<cosmos-account-name>"
    DatabaseName = "<cosmos-database-name>"
    Name = "<cosmos-container-name>"
}
Invoke-AzCosmosDBSqlContainerMerge @parameters

可以使用 az cosmosdb sql container merge 启动合并。

az cosmosdb sql container merge \
    --resource-group '<resource-group-name>' \
    --account-name '<cosmos-account-name>' \
    --database-name '<cosmos-database-name>' \
    --name '<cosmos-container-name>'

将 Invoke-AzCosmosDBMongoDBCollectionMerge 与 -WhatIf 参数一起使用可以预览合并而不实际执行操作。

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<cosmos-account-name>"
    DatabaseName = "<cosmos-database-name>"
    Name = "<cosmos-container-name>"
    WhatIf = $true
}
Invoke-AzCosmosDBMongoDBCollectionMerge @parameters

在不使用 -WhatIf 参数的情况下运行同一命令可以启动合并。

$parameters = @{
    ResourceGroupName = "<resource-group-name>"
    AccountName = "<cosmos-account-name>"
    DatabaseName = "<cosmos-database-name>"
    Name = "<cosmos-container-name>"
}
Invoke-AzCosmosDBMongoDBCollectionMerge @parameters

可以使用 az cosmosdb mongodb collection merge 启动合并。

az cosmosdb mongodb collection merge \
    --resource-group '<resource-group-name>' \
    --account-name '<cosmos-account-name>' \
    --database-name '<cosmos-database-name>' \
    --name '<cosmos-collection-name>'

监视合并操作

分区合并是一项长期运行的操作，没有关于完成该操作所需时间的 SLA。这一时间取决于容器中的数据量和物理分区的数量。建议至少留出 5-6 小时来完成合并。

在容器上运行分区合并时，无法更改吞吐量或任何容器设置（TTL、索引策略、唯一键等）。请等待合并操作完成，然后再更改容器设置。

可通过查看“活动日志”或筛选“合并 MongoDB 集合的物理分区”或“合并 SQL 容器的物理分区”事件来跟踪合并是否仍在进行中。

限制

下面是合并功能目前存在的限制。

预览版资格条件

若要注册预览版，Azure Cosmos DB 帐户必须满足以下所有条件：

Azure Cosmos DB 帐户使用 >=3.6 版本的 API for NoSQL 或 MongoDB。
Azure Cosmos DB 帐户使用预配的吞吐量（手动或自动缩放）。合并不适用于无服务器帐户。
- 目前，共享吞吐量数据库不支持合并。你可以注册一个同时具有共享吞吐量数据库和具有专用吞吐量（手动或自动缩放）的容器的帐户。
- 但是，只有具有专用吞吐量的容器才能合并。
Azure Cosmos DB 帐户是单写入区域帐户（多区域写入帐户目前不支持合并）。
Azure Cosmos DB 帐户不使用以下任何功能：
Azure Cosmos DB 帐户使用有限过期、会话、一致前缀或最终一致性（强一致性目前不支持合并）。
如果使用 API for NoSQL，应用程序必须使用 Azure Cosmos DB .NET v3 SDK（3.27.0 或更高版本）或 Java v4 SDK（4.42.0 或更高版本）。在帐户上启用合并预览后，该帐户不接受从非 .NET/Java SDK 或较旧的 .NET/Java SDK 版本发送的请求。
- 在适用于 MongoDB 的 API 中使用该功能时，没有 SDK 或驱动程序要求。
Azure Cosmos DB 帐户未使用任何当前不受支持的连接器：
- Azure 数据工厂
- Azure 流分析
- 逻辑应用
- Azure Functions
- Azure 搜索
- Azure Cosmos DB Spark 连接器
- 任何在 Azure Cosmos DB SDK 上具有非 .NET V3 SDK >= v3.27.0 或 Java v4 SDK >= 4.42.0 的依赖项的第三方库或工具

帐户资源和配置

合并仅适用于 API for NoSQL 和 MongoDB 帐户。对于适用于 MongoDB 的 API 帐户，MongoDB 帐户版本必须为 3.6 或更高版本。
合并仅适用于单区域写入帐户。不支持多区域写入帐户。
使用合并功能的帐户也不能使用这些功能（如果将这些功能添加到已启用合并的帐户，则该帐户无法合并资源）：
使用合并功能的容器必须在容器级别预配其吞吐量。不支持数据库共享吞吐量。
合并仅适用于使用有限过期、会话、一致前缀或最终一致性的帐户。强一致性目前不支持该功能。
合并容器后，将无法读取带有开始时间的更改源。计划在未来支持此功能。

SDK 要求（仅限 API for NoSQL）

仅当使用最新版本的 .NET v3 SDK 或 Java v4 SDK 时，才支持启用了合并功能的帐户。在你的帐户上启用了此功能时（无论是否运行合并），在使用该帐户时你必须仅使用受支持的 SDK。不接受从其他 SDK 或更早版本发送的请求。只要使用的是受支持的 SDK，应用程序就可以在合并期间继续运行。

查找支持的 SDK 的最新版本：

SDK	支持的版本	包管理器链接
.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

计划未来支持其他 SDK。

提示

注册预览版之前，应确保应用程序已更新，可以使用兼容的 SDK 版本。如果使用旧版 SDK，请遵循相应的迁移指南：

旧版 .NET v2 SDK：.NET SDK v3 迁移指南
旧版 Java v3 SDK：Java SDK v4 迁移指南

不支持的连接器

如果注册预览版，以下连接器会失败。

Azure 数据工厂 ¹
Azure 流分析 ¹
逻辑应用 ¹
Azure Functions ¹
Azure 搜索 ¹
Azure Cosmos DB Spark 连接器 ¹
任何在 Azure Cosmos DB SDK 上具有非 .NET V3 SDK >= v3.27.0 或 Java v4 SDK >= 4.42.0 的依赖项的第三方库或工具

¹ 计划在将来支持这些连接器。

后续步骤

详细了解如何将 Azure CLI 与 Azure Cosmos DB 配合使用。
详细了解如何将 Azure PowerShell 与 Azure Cosmos DB 配合使用。
详细了解 Azure Cosmos DB 中的分区。

通过