Excluir itens por valor de chave de partição – API para NoSQL (versão prévia)

APLICA-SE A: NoSQL

Este artigo explica como usar os SDKs do Azure Cosmos DB para excluir todos os itens pelo valor da chave de partição lógica.

Visão geral do recurso

O recurso de excluir por chave de partição é uma operação assíncrona em segundo plano que permite excluir todos os documentos com o mesmo valor de chave de partição lógica usando o SDK do Cosmos.

Como o número de documentos a serem excluídos pode ser grande, a operação é executada em segundo plano. Embora a operação de exclusão física seja executada em segundo plano, os efeitos estão disponíveis imediatamente, pois os documentos a serem excluídos não aparecerão nos resultados das consultas ou operações de leitura.

A operação de exclusão por chave de partição é limitada a consumir no máximo 10% do total de RUs disponíveis no contêiner a cada segundo. Isso ajuda a limitar os recursos usados por essa tarefa em segundo plano.

Introdução

Atualize sua conta do Azure Cosmos DB para habilitar o recurso "Excluir por chave de partição" usando a CLI do Azure.

• Etapa 1: definir variáveis de shell

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

• Etapa 2: listar os recursos existentes da sua conta.

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

• Etapa 3: adicionar a funcionalidade "Excluir itens por chave de partição" na lista de recursos, caso ainda não exista.

  Observação

  A lista de recursos deve sempre especificar todos os recursos que você deseja habilitar, de forma inclusiva. Isso inclui recursos que já estão habilitados para a conta que você deseja manter.

     $capabilities += $DeleteByPk
  

• Etapa 4: atualizar a conta do Cosmos DB para habilitar o recurso "Excluir itens por chave de partição"

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

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

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

# 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")

Perguntas frequentes (FAQ)

Os resultados da exclusão por operação de chave de partição são refletidos imediatamente?

Sim, uma vez iniciada a operação de exclusão por chave de partição, os documentos a serem excluídos não aparecerão nos resultados de consultas ou operações de leitura. Isso também significa que você pode gravar um novo documento com a mesma ID e chave de partição que um documento a ser excluído sem resultar em um conflito.

Confira as exceções em Problemas conhecidos.

O que acontece se eu iniciar uma operação de exclusão por chave de partição e então gravar imediatamente um novo documento com a mesma chave de partição?

Quando a operação de exclusão por chave de partição for emitida, somente os documentos existentes no contêiner, com o valor da chave de partição, serão excluídos. Quaisquer novos documentos que entrarem não estarão no escopo da exclusão.

Como a operação de exclusão por chave de partição é priorizada entre outras operações em relação ao contêiner?

Por padrão, a operação de exclusão por chave de partição pode consumir até uma fração reservada (de 0,1 ou 10%) das RU/s gerais no recurso. Todas as Unidades de Solicitação (RUs) neste bucket que não forem usadas estarão disponíveis para outras operações não em segundo plano, como leituras, gravações e consultas.

Por exemplo, suponha que você tenha provisionado 1000 RU/s em um contêiner. Há uma operação de exclusão por chave de partição em andamento que consome 100 RUs por segundo por 5 segundos. Durante cada um desses 5 segundos, há 900 RUs disponíveis para operações de banco de dados não em segundo plano. Depois que a operação de exclusão for concluída, todas as 1000 RU/s estarão disponíveis novamente.

Problemas conhecidos

Em alguns cenários, uma operação de exclusão por chave de partição pode não garantir imediatamente seus efeitos, e a visibilidade parcial pode ocorrer durante a operação.

• Consultas agregadas que usam o índice – por exemplo, consultas COUNT que são executadas durante uma operação de exclusão por chave de partição em andamento – podem conter os resultados dos documentos a serem excluídos. Isso pode ocorrer até que a operação de exclusão seja totalmente concluída.
• Consultas executadas no repositório analítico durante uma operação de exclusão por chave de partição em andamento podem conter os resultados dos documentos a serem excluídos. Isso pode ocorrer até que a operação de exclusão seja totalmente concluída.
• Backup contínuo (restauração pontual) – uma restauração disparada durante uma operação de exclusão por chave de partição em andamento pode conter os resultados dos documentos a serem excluídos na coleção restaurada. Não é recomendável usar essa versão prévia do recurso se você tiver um cenário que exija backup contínuo.

Limitações

• Não há suporte para a exclusão de chaves de partição hierárquica. Esse recurso permite a exclusão de itens apenas com base no último nível de chaves de partição. Por exemplo, considere um cenário em que uma chave de partição consiste em três níveis hierárquicos: país, estado e cidade. Nesse contexto, a funcionalidade de excluir por chaves de partição pode ser empregada efetivamente especificando a chave de partição completa, abrangendo todos os níveis, ou seja, país/estado/cidade. A tentativa de excluir usando chaves de partição intermediárias, como país/estado ou somente país, resultará em um erro.

Como fornecer comentários ou relatar um problema/bug

• Mande um email para cosmosPkDeleteFeedbk@microsoft.com com perguntas ou comentários.

Requisitos do SDK

Localize a versão mais recente do SDK que dá suporte a essa funcionalidade.

Planeja-se dar suporte a outros SDKs futuramente.

Próximas etapas

Confira os seguintes artigos para saber mais sobre as operações do SDK no Azure Cosmos DB.

• Consulta um contêiner do Azure Cosmos DB
• Operações em lotes transacionais no Azure Cosmos DB usando o SDK do .NET