パーティション キー値によって項目を削除する - NoSQL 用 API (プレビュー)

適用対象: NoSQL

この記事では、Azure Cosmos DB SDK を使用して、論理パーティション キー値によってすべての項目を削除する方法について説明します。

重要

パーティション キー値による項目の削除は、パブリック プレビュー段階です。 この機能は、サービス レベル アグリーメントなしに提供されます。 詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

機能の概要

パーティション キーによる削除機能は、Cosmos SDK を使用して同じ論理パーティション キー値を持つすべてのドキュメントを削除できるようにする、非同期のバックグラウンド操作です。

削除対象のドキュメントの数が多くなることが考えられるため、この操作はバックグラウンドで実行されます。 物理的な削除操作はバックグラウンドで実行されますが、削除対象のドキュメントがクエリや読み取り操作の結果に表示されなくなるため、その効果はすぐに表れます。

パーティション キー 操作による削除は、毎秒コンテナーで使用可能な RU/秒の合計の最大 10% までしか消費できないように制限されています。 これは、このバックグラウンド タスクで使用されるリソースを制限するのに役立ちます。

作業の開始

Azure CLI を使って "パーティション キーによる削除" 機能を有効にするように Azure Cosmos DB アカウントを更新します。

• 手順 1: シェル変数を設定する

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

• 手順 2: アカウントの既存の機能を一覧表示する。

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

• 手順 3: "パーティション キーによる項目の削除" 機能がまだ存在しない場合は、機能の一覧に追加する。

  Note

  機能の一覧では、有効にする必要がある "すべて" の機能を常に包括的に指定する必要があります。 これには、アカウントに対して既に有効になっている保持する機能が含まれます。

     $capabilities += $DeleteByPk
  

• 手順 4: "パーティション キーによる項目の削除" 機能を有効にするように Cosmos DB アカウントを更新する

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

.NET

サンプル コード

パーティション キーによって項目を削除するには、Azure Cosmos DB .NET SDK のバージョン 3.25.0-preview (またはそれ以降のプレビュー バージョン) を使用します。

// 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");
}

Java

パーティション キーによって項目を削除するには、Azure Cosmos DB Java SDK のバージョン 4.19.0 (またはそれ以降のバージョン) を使用します。 パーティション キーによる削除 API はベータ版となります。

// 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();

Python

パーティション キーで項目を削除するには、Azure Cosmos DB Python SDK のベータ版 ( >= 4.4.0b1) を使用します。 パーティション キーによる削除 API はベータ版となります。

# 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/秒全体のうち、予約された割合 (0.1 または 10%) まで消費できます。 このバケット内の未使用の要求ユニット (RU) は、読み取り、書き込み、クエリなど、バックグラウンドでない他の操作で使用できます。

たとえば、コンテナーに 1000 RU/秒をプロビジョニングしたとします。 パーティション キーによる削除操作が進行中であり、5 秒の間、毎秒 100 RU を消費しています。 これらの 5 秒の各秒では、バックグラウンド以外のデータベース操作に 900 の RU を使用できます。 削除操作が完了すると、1,000 RU/秒のすべてがもう一度使用できるようになります。

既知の問題

一部のシナリオでは、パーティション キーによる削除操作の効果がすぐに保証されず、操作中に部分的に表示される可能性があります。

• 進行中のパーティション キーによる削除操作中に発行された、インデックスを使用する集計クエリ (COUNT クエリなど) に、削除対象のドキュメントの結果が含まれる場合があります。 これは、削除操作がすべて完了するまで発生し続ける可能性があります。
• 進行中のパーティション キーによる削除操作中に分析ストアに対して発行されたクエリに、削除対象のドキュメントの結果が含まれる場合があります。 これは、削除操作がすべて完了するまで発生し続ける可能性があります。
• 継続的バックアップ (ポイントインタイム リストア) - 進行中のパーティション キーによる削除操作中にトリガーされた復元では、復元されたコレクション内に削除対象のドキュメントの結果が含まれる場合があります。 お使いのシナリオで継続的バックアップが必要な場合は、このプレビュー機能は使用しないことをお勧めします。

制限事項

• 階層パーティション キーの削除はサポートされていません。 この機能では、最後のレベルのパーティション キーのみに基づいた項目の削除を許可します。 たとえば、パーティション キーが国、州、市区町村の 3 つの階層レベルで構成されているシナリオを考えてみましょう。 このコンテキストでは、すべてのレベル (すなわち国/州/市区町村) を含む完全なパーティション キーを指定すると、パーティション キーによる削除機能を効果的に使用できます。 国/州や国のみなどの中間のパーティション キーを使用して削除を試みると、エラーが発生します。

フィードバックの送信または問題/バグの報告を行う方法

• 質問やフィードバックを記入したメールを cosmosPkDeleteFeedbk@microsoft.com に送信してください。

SDK の要件

この機能をサポートする SDK の最新バージョンを見つけます。

SDK	サポートされているバージョン	パッケージ マネージャーのリンク
.NET SDK v3	">= 3.25.0-preview (プレビュー バージョンが必須です)"	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/
Java SDK v4	">= 4.19.0 (API はベータ版となります)"	https://mvnrepository.com/artifact/com.azure/azure-cosmos
Python SDK v4	>= 4.4.0b1 (ベータ版である必要があります)	https://pypi.org/project/azure-cosmos/4.4.0b1/

今後、他の SDK のサポートが予定されています。

次のステップ

Azure Cosmos DB での SDK 操作の詳細については、次の記事を参照してください。

• Azure Cosmos DB コンテナーにクエリを実行する
• .NET SDK を使用した Azure Cosmos DB でのトランザクション バッチ操作