Odstranění položek podle hodnoty klíče oddílu – rozhraní API pro NoSQL (Preview)

Článek
08/15/2024

PLATÍ PRO: NoSQL

Tento článek vysvětluje, jak pomocí sad SDK služby Azure Cosmos DB odstranit všechny položky podle hodnoty klíče logického oddílu.

Důležité

Odstranění položek podle hodnoty klíče oddílu je ve verzi Public Preview. Tato funkce je poskytována bez smlouvy o úrovni služeb. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Přehled funkcí

Funkce odstranění pomocí klíče oddílu je asynchronní operace na pozadí, která umožňuje odstranit všechny dokumenty se stejnou hodnotou klíče logického oddílu pomocí sady Cosmos SDK.

Vzhledem k tomu, že počet dokumentů, které se mají odstranit, může být velký, operace se spustí na pozadí. I když se operace fyzického odstranění spouští na pozadí, efekty jsou k dispozici okamžitě, protože dokumenty, které se mají odstranit, nezobrazí ve výsledcích dotazů ani operací čtení.

Odstranění operací klíče oddílu má za cíl spotřebovat maximálně 10 % celkového dostupného POČTU RU/s v kontejneru za každou sekundu na základě maximálního úsilí . To pomáhá omezit prostředky používané touto úlohou na pozadí.

Začínáme

Aktualizujte účet služby Azure Cosmos DB tak, aby pomocí Azure CLI povolil funkci Odstranit podle klíče oddílu.

Krok 1: Nastavení proměnných prostředí

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

Krok 2: Zobrazení seznamu existujících funkcí vašeho účtu

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

Krok 3: Přidejte do seznamu funkcí možnost Odstranit položky podle klíče oddílu, pokud ještě neexistuje.

Poznámka:

Seznam funkcí musí vždy určovat všechny možnosti, které chcete povolit ( včetně). To zahrnuje funkce, které už jsou povolené pro účet, který chcete zachovat.
```
   $capabilities = $DeleteByPk
```
Krok 4: Aktualizace účtu služby Cosmos DB za účelem povolení funkce Odstranit položky podle klíče oddílu
```
    az cosmosdb update --capabilities $capabilities \
     -n $accountName -g $resourceGroupName
```

Ukázkový kód

K odstranění položek podle klíče oddílu použijte verzi 3.25.0-preview (nebo novější verzi Preview) sady .NET SDK služby Azure Cosmos DB.

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

Pomocí verze 4.19.0 (nebo vyšší verze) sady Java SDK služby Azure Cosmos DB odstraňte položky podle klíče oddílu. Odstranění pomocí rozhraní API klíče oddílu se označí jako 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();

K odstranění položek podle klíče oddílu použijte beta verzi ( >= 4.4.0b1) sady Python SDK služby Azure Cosmos DB. Odstranění pomocí rozhraní API klíče oddílu se označí jako 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")

Nejčastější dotazy

Projeví se výsledky operace odstranění pomocí klíče oddílu okamžitě?

Ano, po spuštění operace odstranění klíčem oddílu se dokumenty, které se mají odstranit, nezobrazí ve výsledcích dotazů nebo operací čtení. To také znamená, že můžete napsat nový dokument se stejným ID a klíčem oddílu jako dokument, který se má odstranit, aniž by došlo ke konfliktu.

Podívejte se na známé problémy s výjimkami.

Co se stane, když vydám odstranění operací klíče oddílu a pak okamžitě zapíšem nový dokument se stejným klíčem oddílu?

Při vydání operace odstranění pomocí klíče oddílu budou odstraněny pouze dokumenty, které existují v kontejneru, s hodnotou klíče oddílu. Všechny nové dokumenty, které přicházejí, nebudou v rozsahu odstranění.

Jak je odstranění operací klíče oddílu upřednostněno mezi jinými operacemi proti kontejneru?

Ve výchozím nastavení může operace odstranění podle hodnoty klíče oddílu spotřebovat až rezervovaný zlomek – 0,1 nebo 10 % celkového počtu RU/s prostředku. Všechny jednotky žádostí (RU) v tomto kontejneru, které se nepoužívají, budou k dispozici pro jiné operace mimo prostředí, jako jsou čtení, zápisy a dotazy.

Předpokládejme například, že jste v kontejneru zřídili 1000 RU/s. Operace klíče oddílu průběžně odstraňuje 100 RU za sekundu po dobu 5 sekund. Během každé z těchto 5 sekund je k dispozici 900 RU pro databázové operace, které nejsou v popředí. Po dokončení operace odstranění je teď všech 1 000 RU/s opět k dispozici.

Známé problémy

V některých scénářích nemusí operace odstranění pomocí klíče oddílu okamžitě zaručit jeho účinky a během operace může dojít k částečné viditelnosti.

Agregované dotazy, které používají index – například dotazy COUNT – vydané během probíhající operace odstranění klíčem oddílu můžou obsahovat výsledky dokumentů, které se mají odstranit. K tomu může dojít, dokud nebude operace odstranění úplně dokončena.
Dotazy vydané v analytickém úložišti během probíhající operace odstranění klíčem oddílu můžou obsahovat výsledky dokumentů, které se mají odstranit. K tomu může dojít, dokud nebude operace odstranění úplně dokončena.
Průběžné zálohování (obnovení k určitému bodu v čase) – obnovení aktivované během probíhající operace odstranění klíčem oddílu může obsahovat výsledky dokumentů, které se mají odstranit v obnovené kolekci. Pokud máte scénář, který vyžaduje průběžné zálohování, nedoporučujeme tuto funkci Preview používat.

Omezení

Odstranění hierarchických klíčů oddílů se nepodporuje. Tato funkce umožňuje odstranění položek výhradně na základě poslední úrovně klíčů oddílů. Představte si například scénář, ve kterém se klíč oddílu skládá ze tří hierarchických úrovní: země, stát a město. V tomto kontextu je možné efektivně využít funkci odstranění pomocí klíčů oddílů zadáním kompletního klíče oddílu, který zahrnuje všechny úrovně, konkrétně země/stát/město. Při pokusu o odstranění pomocí zprostředkujících klíčů oddílů, jako je země nebo stát nebo výhradně země, dojde k chybě.

Jak poskytnout zpětnou vazbu nebo nahlásit problém nebo chybu

Pošlete e-mail cosmosPkDeleteFeedbk@microsoft.com s dotazy nebo zpětnou vazbou.

Požadavky sady SDK

Vyhledejte nejnovější verzi sady SDK, která tuto funkci podporuje.

Sada SDK	Podporované verze	Odkaz správce balíčků
.NET SDK v3	>= 3.25.0-preview (musí být verze Preview)	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/
Java SDK v4	>= 4.19.0 (rozhraní API je označeno jako beta verze)	https://mvnrepository.com/artifact/com.azure/azure-cosmos
Python SDK v4	>= 4..4.0b1 (musí být beta verze)	https://pypi.org/project/azure-cosmos/4.4.0b1/

Podpora dalších sad SDK se plánuje v budoucnu.

Další kroky

Další informace o operacích se sadou SDK ve službě Azure Cosmos DB najdete v následujících článcích.

Sdílet prostřednictvím