Condividi tramite

Eliminare elementi in base al valore della chiave di partizione - API per NoSQL (anteprima)

  • Articolo

SI APPLICA A: NoSQL

Questo articolo illustra come usare gli SDK di Azure Cosmos DB per eliminare tutti gli elementi in base al valore della chiave di partizione logica.

Importante

L'eliminazione di elementi in base al valore della chiave di partizione è disponibile in anteprima pubblica. Questa funzionalità viene fornita senza un contratto di servizio. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

Panoramica delle funzionalità

La funzionalità di eliminazione in base alla chiave di partizione è un'operazione in background asincrona che consente di eliminare tutti i documenti con lo stesso valore della chiave di partizione logica usando Cosmos SDK.

Poiché il numero di documenti da eliminare potrebbe essere elevato, l'operazione viene eseguita in background. Sebbene l'operazione di eliminazione fisica venga eseguita in background, i suoi effetti sono immediatamente disponibili poiché i documenti da eliminare non verranno visualizzati nei risultati delle query o nelle operazioni di lettura.

L'operazione di eliminazione per chiave di partizione è vincolata a consumare al massimo il 10% delle UR/sec totali disponibili nel contenitore ogni secondo. Ciò consente di limitare le risorse usate da questa attività in background.

Introduzione

Aggiornare l'account Azure Cosmos DB per abilitare la funzionalità "Elimina per chiave di partizione" usando l'interfaccia della riga di comando di Azure.

  • Passaggio 1: impostare le variabili della shell.

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

  • Passaggio 2: elencare le funzionalità esistenti dell'account.

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

  • Passaggio 3: aggiungere la funzionalità "Elimina elementi per chiave di partizione" nell'elenco delle funzionalità, se non è già presente.

    Nota

    L'elenco delle funzionalità deve sempre specificare tutte le funzionalità che si desidera abilitare. Sono incluse le funzionalità già abilitate per l'account che si desidera mantenere.

       $capabilities += $DeleteByPk

  • Passaggio 4: aggiornare l'account Cosmos DB per abilitare la funzionalità "Elimina elementi per chiave di partizione".

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

Codice di esempio

Usare la versione 3.25.0-preview (o versione di anteprima successiva) di Azure Cosmos DB .NET SDK per eliminare elementi in base alla chiave di partizione.

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

Domande frequenti

I risultati dell'operazione di eliminazione tramite chiave di partizione vengono riflessi immediatamente?

Sì, dopo l'avvio dell'operazione di eliminazione in basa alle chiave di partizione, i documenti da eliminare non verranno visualizzati nei risultati delle query o nelle operazioni di lettura. Ciò significa anche che è possibile scrivere un nuovo documento con lo stesso ID e la stessa chiave di partizione di un documento da eliminare senza causare un conflitto.

Per le eccezioni, consultare la sezione Problemi noti.

Cosa accade se si esegue un'operazione di eliminazione in base alla chiave di partizione e subito dopo si scrive un nuovo documento con la stessa chiave di partizione?

Quando viene eseguita l'operazione di eliminazione in base alla chiave di partizione, verranno eliminati solo i documenti presenti nel contenitore con il valore della chiave di partizione. Eventuali nuovi documenti ricevuti non rientreranno nell'ambito dell'eliminazione.

In che modo l'operazione di eliminazione in base alla chiave di partizione ha la priorità tra le altre operazioni sul contenitore?

Per impostazione predefinita, l'operazione di eliminazione in base al valore della chiave di partizione può utilizzare fino a una frazione riservata, ovvero 0,1 o 10%, delle UR/sec complessive nella risorsa. Tutte le Unità richiesta (UR) in questo bucket inutilizzate saranno disponibili per altre operazioni non in background, ad esempio letture, scritture e query.

Si supponga, ad esempio, di aver effettuato il provisioning di 1000 UR/sec in un contenitore. È in corso un'operazione di eliminazione in base alla chiave di partizione che utilizza 100 UR ogni secondo per 5 secondi. Durante ognuno di questi 5 secondi, sono disponibili 900 UR per le operazioni di database non in background. Una volta completata l'operazione di eliminazione, tutti le 1000 UR/sec sono nuovamente disponibili.

Problemi noti

In alcuni scenari, un'operazione di eliminazione in base alla chiave di partizione potrebbe non garantire immediatamente i suoi effetti e durante l'eliminazione si potrebbe riscontrare una visibilità parziale.

  • Le query di aggregazione che usano l'indice, ad esempio le query COUNT, eseguite durante un'operazione in corso di eliminazione in base alla chiave di partizione potrebbero contenere i risultati dei documenti da eliminare. Ciò potrebbe verificarsi fino al completamento dell'operazione di eliminazione.
  • Le query eseguite sull'archivio analitico durante un'operazione in corso di eliminazione in base alla chiave di partizione potrebbero contenere i risultati dei documenti da eliminare. Ciò potrebbe verificarsi fino al completamento dell'operazione di eliminazione.
  • Backup continuo (ripristino temporizzato): un ripristino attivato durante un'operazione in corso di eliminazione in base alla chiave di partizione può contenere i risultati dei documenti da eliminare nella raccolta ripristinata. Non è consigliabile usare questa funzionalità di anteprima se si dispone di uno scenario che richiede il backup continuo.

Limiti

  • L'eliminazione dellechiavi di partizione gerarchiche non è supportata. Questa funzionalità consente l'eliminazione degli elementi esclusivamente in base all'ultimo livello delle chiavi di partizione. Si consideri, ad esempio, uno scenario in cui una chiave di partizione è costituita da tre livelli gerarchici: Paese, stato e città. In questo contesto, la funzionalità di eliminazione in base alla chiave di partizione può essere usata in modo efficace specificando la chiave di partizione completa, che comprende tutti i livelli, ovvero Paese/stato/città. Il tentativo di eliminare elementi usando chiavi di partizione intermedie, ad esempio Paese/stato o solo Paese, genererà un errore.

Come inviare un feedback o segnalare un problema o un bug

  • Per inviare domande o feedback, scrivere all'indirizzo e-mail cosmosPkDeleteFeedbk@microsoft.com.

Requisiti SDK

Trovare la versione più recente dell'SDK che supporta questa funzionalità.

SDK Versioni supportate Collegamento di Gestione pacchetti
.NET SDK v3 >= 3.25.0-preview (deve essere in versione di anteprima) https://www.nuget.org/packages/Microsoft.Azure.Cosmos/
Java SDK v4 >= 4.19.0 (l'API è contrassegnata come versione beta) https://mvnrepository.com/artifact/com.azure/azure-cosmos
Python SDK v4 >= 4..4.0b1 (deve essere in versione beta) https://pypi.org/project/azure-cosmos/4.4.0b1/

In futuro si prevede di implementare il supporto per altri SDK.

Passaggi successivi

Vedere gli articoli seguenti per ottenere maggiori informazioni sulle operazioni SDK in Azure Cosmos DB: