Excluir itens por valor de chave de partição - API para NoSQL (visualização)

Artigo
08/15/2024

APLICA-SE A: NoSQL

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

Importante

Excluir itens por valor de chave de partição está em visualização pública. Este recurso é fornecido sem um contrato de nível de serviço. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Descrição geral das funcionalidades

O recurso 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 de consultas ou operações de leitura.

A operação de exclusão por chave de partição visa consumir no máximo 10% do total de RU/s disponíveis no contêiner a cada segundo com base no melhor esforço . 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 do shell

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

Etapa 2: liste os recursos existentes da sua conta.

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

Passo 3: Adicione a capacidade "Excluir itens por chave de partição" na lista de recursos, se ela ainda não existir.

Nota

A lista de recursos deve sempre especificar todos os recursos que você deseja habilitar, inclusive. Isso inclui recursos que já estão habilitados para a conta que você deseja manter.
```
   $capabilities = $DeleteByPk
```

Etapa 4: Atualize a conta do Cosmos DB para ativar 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 visualização superior) do Azure Cosmos DB .NET SDK 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 API de exclusão por 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 Python do Azure Cosmos DB para excluir itens por chave de partição. A API de exclusão por 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 mais frequentes (FAQ)

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

Sim, assim que a operação de exclusão por chave de partição for iniciada, 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 escrever um novo documento com a mesma ID e chave de partição de um documento a ser excluído sem resultar em um conflito.

Consulte Problemas conhecidos para exceções.

O que acontece se eu emitir uma operação de exclusão por chave de partição e, em seguida, escrever imediatamente um novo documento com a mesma chave de partição?

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

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

Por padrão, a operação de exclusão por valor de chave de partição pode consumir até uma fração reservada - 0,1 ou 10% - do total de RU/s no recurso. Quaisquer 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ê provisionou 1000 RU/s em um contêiner. Há uma operação contínua de exclusão por chave de partição que consome 100 RUs a cada segundo por 5 segundos. Durante cada um desses 5 segundos, há 900 RUs disponíveis para operações de banco de dados sem segundo plano. Quando a operação de exclusão estiver concluída, todos os 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 visibilidade parcial pode ocorrer durante a operação.

As consultas agregadas que usam o índice - por exemplo, consultas COUNT - que são emitidas durante uma operação de exclusão contínua por chave de partição 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.
As consultas emitidas no repositório analítico durante uma operação contínua de exclusão por chave de partição 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 point-in-time) - uma restauração que é acionada durante uma operação de exclusão contínua por chave de partição pode conter os resultados dos documentos a serem excluídos na coleção restaurada. Não é recomendável usar esse recurso de visualização 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árquicas. Este 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. Neste contexto, a funcionalidade delete by partition keys pode ser empregada de forma eficaz, especificando a chave de partição completa, abrangendo todos os níveis, ou seja, país/estado/cidade. Tentar excluir usando chaves de partição intermediárias, como país/estado ou apenas país, resultará em um erro.

Como dar feedback ou relatar um problema/bug

E-mail cosmosPkDeleteFeedbk@microsoft.com com perguntas ou comentários.

Requisitos do SDK

Encontre a versão mais recente do SDK que suporta esse recurso.

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

O suporte para outros SDKs está planejado para o futuro.

Próximos passos

Consulte os artigos a seguir para saber mais sobre as operações do SDK no Azure Cosmos DB.

Partilhar via