按分区键值 - API for NoSQL（预览版）删除项

适用范围： NoSQL

本文介绍如何使用 Azure Cosmos DB SDK 按逻辑分区键值删除所有项。

重要

按分区键值删除项功能处于公共预览阶段。此功能没有提供服务级别协议。有关详细信息，请参阅世纪互联 Azure 预览版补充使用条款。

功能概述

按分区键删除功能是一种异步后台作，可用于使用 Cosmos SDK 删除具有相同逻辑分区键值的所有文档。

由于要删除的文档数可能很大，因此该作在后台运行。尽管物理删除作在后台运行，但效果立即可用，因为要删除的文档不会出现在查询或读取作的结果中。

按分区键删除操作的目标是在最大努力原则上，最多消耗容器上可用的每秒请求单位 (RU/s) 总数的 10%。这有助于限制此后台任务使用的资源。

开始

更新 Azure Cosmos DB 帐户，以使用 Azure CLI 启用 按分区键删除 功能。

设置 shell 变量。

    $resourceGroupName = <azure_resource_group>
    $accountName = <azure_cosmos_db_account_name>
    $DeleteByPk = "DeleteAllItemsByPartitionKey"

列出帐户的现有功能。

   $cosmosdb = az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName
   $capabilities = ($cosmosdb | ConvertFrom-Json).capabilities

在功能列表中，如果尚未存在，请添加按分区键删除项的功能。

注释

功能列表必须始终一个不漏地指定要启用的所有功能。这包括已启用并希望保留的帐户的功能。
```
   $capabilities = $DeleteByPk
```

更新 Cosmos DB 帐户以启用按分区键删除项功能。

    az cosmosdb update --capabilities $capabilities \
     -n $accountName -g $resourceGroupName

示例代码

若要按分区键删除项，请使用 Azure Cosmos DB .NET SDK 版本 3.25.0 预览版或更高版本。

// Suppose our container is partitioned by tenantId, and we want to delete all the data for a particular tenant Contoso

// Get reference to the container
var container = cosmosClient.GetContainer("DatabaseName", "ContainerName");

// Delete by logical partition key
ResponseMessage deleteResponse = await container.DeleteAllItemsByPartitionKeyStreamAsync(new PartitionKey("Contoso"));

 if (deleteResponse.IsSuccessStatusCode) {
    Console.WriteLine($"Delete all documents with partition key operation has successfully started");
}

若要按分区键删除项，请使用 Azure Cosmos DB Java SDK 版本 4.19.0 或更高版本。按分区键的删除 API 被标记为 beta 版。

// Suppose our container is partitioned by tenantId, and we want to delete all the data for a particular tenant Contoso

// Delete by logical partition key
CosmosItemResponse<?> deleteResponse = container.deleteAllItemsByPartitionKey(
            new PartitionKey("Contoso"), new CosmosItemRequestOptions()).block();

若要按分区键删除项，请使用 Azure Cosmos DB Python SDK 的 beta 版本 4.4.0b1 或更高版本。按分区键的删除 API 被标记为 beta 版。

# Suppose our container is partitioned by tenantId, and we want to delete all the data for a particular tenant Contoso

# Delete by logical partition key
container.delete_all_items_by_partition_key("Contoso")

常见问题 (FAQ)

按分区键删除操作的结果是否会立即反映出来？

是的，在分区键删除操作开始后，要删除的文档不会出现在查询或读取操作的结果中。这也意味着，你可以使用与要删除的文档相同的 ID 和分区键写入新文档，而不会导致冲突。

有关例外情况，请参阅已知问题。

如果我发出一个按分区键删除操作，然后立即使用相同的分区键写入一个新文档，会发生什么情况？

当执行按分区键删除操作时，只会删除容器中与分区键值对应的文档。任何传入的新文档都不在删除范围内。

与针对容器执行的其他操作相比，按分区键删除操作的优先级如何？

默认情况下，按分区键值删除操作最多可以消耗保留的一部分资源 - RU/s 总数的 0.1，即 10%。此桶中未使用的任何请求单位 (RU) 都可用于其他非后台操作，例如读取、写入和查询。

例如，假设你在容器上预配了 1000 RU/秒。正在进行的按分区键删除操作每秒消耗 100 RU 并持续 5 秒。在这 5 秒钟内，每秒都有 900 RU 可用于非后台数据库操作。该删除操作完成后，所有 1000 RU/s 再次可用。

已知问题

在某些情况下，按分区键进行删除操作可能无法立刻确保其效果，并且在操作过程中可能会出现部分可见性。

在按分区键删除操作正在进行期间发出的、使用索引的聚合查询（例如 COUNT 查询）可能包含要删除的文档的结果。在删除作完全完成之前，可能会发生这种情况。
在按分区键进行删除操作的过程中，对分析存储发出的查询可能会包含即将删除的文档结果。在删除作完全完成之前，可能会发生这种情况。
连续备份（时间点还原）在按分区键删除操作正在进行期间触发，可能包含要在已还原集合中删除的文档的结果。如果你的方案需要连续备份，建议不要使用此预览功能。

如何提供反馈或报告问题/bug

将包含问题或反馈的电子邮件发送到 cosmosPkDeleteFeedbk@microsoft.com。

SDK 要求

查找支持此功能的最新版 SDK。

SDK	支持的版本	包管理器链接
.NET SDK v3	3.25.0 或更高版本（必须是预览版）	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/
Java SDK v4	4.19.0 或更高版本（API 标记为 beta 版）	https://mvnrepository.com/artifact/com.azure/azure-cosmos
Python SDK v4	4.4.0b1 或更高版本（必须是 beta 版本）	https://pypi.org/project/azure-cosmos/4.4.0b1/

计划未来支持其他 SDK。

后续步骤

Last updated on 2025-08-13

通过