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

Artigo
08/15/2024

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.

Importante

A exclusão de itens pelo valor de chave de partição está na visualização pública. O recurso é fornecido sem um Contrato de Nível de Serviço. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

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
```

Código de exemplo

Use a versão 3.25.0-preview (ou uma versão de superior em versão prévia) do SDK do .NET do Azure Cosmos DB para excluir itens por chave de partição.

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

Use a versão 4.19.0 (ou uma versão superior) do SDK Java do Azure Cosmos DB para excluir itens por chave de partição. A exclusão pela API de chave de partição será marcada como 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();

Use a versão beta ( >= 4.4.0b1) do SDK do Python do Azure Cosmos DB para excluir itens por chave de partição. A exclusão pela API de chave de partição será marcada como 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")

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.

.	Versões com suporte	Link do gerenciador de pacotes
SDK v3 do .NET	>= 3.25.0-preview (deve ser versão prévia)	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/
SDK do Java v4	>= 4.19.0 (a API está marcada como beta)	https://mvnrepository.com/artifact/com.azure/azure-cosmos
SDK v4 do Python	>= 4..4.0b1 (deve ser a versão beta)	https://pypi.org/project/azure-cosmos/4.4.0b1/

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.

Compartilhar via