Usuwanie elementów według wartości klucza partycji — interfejs API dla noSQL (wersja zapoznawcza)

Artykuł
12/27/2023

DOTYCZY: NoSQL

W tym artykule wyjaśniono, jak za pomocą zestawów SDK usługi Azure Cosmos DB usunąć wszystkie elementy według wartości klucza partycji logicznej.

Ważne

Usuwanie elementów według wartości klucza partycji jest dostępne w publicznej wersji zapoznawczej. Ta funkcja jest udostępniana bez umowy dotyczącej poziomu usług. Aby uzyskać więcej informacji, zobacz Uzupełniające warunki korzystania z wersji zapoznawczych platformy Microsoft Azure.

Omówienie funkcji

Funkcja usuwania według klucza partycji jest asynchroniczną operacją w tle, która umożliwia usunięcie wszystkich dokumentów z tą samą wartością klucza partycji logicznej przy użyciu zestawu Cosmos SDK.

Ponieważ liczba dokumentów do usunięcia może być duża, operacja jest uruchamiana w tle. Chociaż operacja fizycznego usuwania jest uruchamiana w tle, efekty są dostępne natychmiast, ponieważ dokumenty do usunięcia nie będą wyświetlane w wynikach zapytań ani operacji odczytu.

Operacja usuwania według klucza partycji jest ograniczona do korzystania z co najwyżej 10% całkowitej dostępnej liczby jednostek RU/s w kontenerze na sekundę. Pomaga to ograniczyć zasoby używane przez to zadanie w tle.

Wprowadzenie

Zaktualizuj konto usługi Azure Cosmos DB, aby włączyć funkcję "Usuń według klucza partycji" przy użyciu interfejsu wiersza polecenia platformy Azure.

Krok 1. Ustawianie zmiennych powłoki

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

Krok 2. Wyświetlanie listy istniejących możliwości twojego konta.

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

Krok 3. Dodawanie funkcji "Usuń elementy według klucza partycji" na liście możliwości, jeśli jeszcze nie istnieje.

Uwaga

Lista możliwości musi zawsze określać wszystkie możliwości, które chcesz włączyć, włącznie. Obejmuje to możliwości, które są już włączone dla konta, które chcesz zachować.
```
   $capabilities += $DeleteByPk
```
Krok 4. Aktualizowanie konta usługi Cosmos DB w celu włączenia funkcji "Usuwanie elementów według klucza partycji"
```
    az cosmosdb update --capabilities $capabilities \
     -n $accountName -g $resourceGroupName
```

Przykładowy kod

Użyj wersji 3.25.0-preview (lub nowszej wersji zapoznawczej) zestawu .NET SDK usługi Azure Cosmos DB, aby usunąć elementy według klucza partycji.

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

Użyj wersji 4.19.0 (lub nowszej) zestawu JAVA SDK usługi Azure Cosmos DB, aby usunąć elementy według klucza partycji. Usunięcie przy użyciu interfejsu API klucza partycji zostanie oznaczone 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();

Użyj wersji beta ( >= 4.4.0b1) zestawu SDK języka Python usługi Azure Cosmos DB, aby usunąć elementy według klucza partycji. Usunięcie przy użyciu interfejsu API klucza partycji zostanie oznaczone 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")

Często zadawane pytania

Czy wyniki operacji usuwania według klucza partycji są natychmiast odzwierciedlane?

Tak, po rozpoczęciu operacji usuwania według klucza partycji dokumenty do usunięcia nie będą wyświetlane w wynikach zapytań ani operacji odczytu. Oznacza to również, że można napisać nowy dokument o tym samym identyfikatorze i kluczu partycji co dokument do usunięcia bez konfliktu.

Zobacz Znane problemy dotyczące wyjątków.

Co się stanie, jeśli wydam operację usuwania według klucza partycji, a następnie natychmiast napiszę nowy dokument z tym samym kluczem partycji?

Po wydaniu operacji usuwania według klucza partycji zostaną usunięte tylko dokumenty, które istnieją w kontenerze, a następnie z wartością klucza partycji. Wszystkie nowe dokumenty, które są dostępne, nie będą objęte zakresem usunięcia.

W jaki sposób operacja usuwania według klucza partycji jest priorytetowa między innymi operacjami względem kontenera?

Domyślnie operacja usuwania według wartości klucza partycji może zużywać maksymalnie część zarezerwowaną — 0,1 lub 10% — ogólnej wartości RU/s w zasobie. Wszystkie jednostki żądań (RU) w tym zasobniku, które są nieużywane, będą dostępne dla innych operacji nieobsługiwanych, takich jak odczyty, zapisy i zapytania.

Załóżmy na przykład, że aprowizowaliśmy 1000 RU/s w kontenerze. Trwa usuwanie przez operację klucza partycji, która zużywa 100 jednostek RU na sekundę przez 5 sekund. W każdej z tych 5 sekund dostępnych jest 900 jednostek RU dla operacji bazy danych nienależących do planu zwrotnego. Po zakończeniu operacji usuwania wszystkie 1000 RU/s są teraz ponownie dostępne.

Znane problemy

W niektórych scenariuszach operacja usuwania według klucza partycji może nie natychmiast zagwarantować jej skutków, a podczas operacji może wystąpić częściowa widoczność.

Zagregowane zapytania korzystające z indeksu — na przykład zapytania COUNT — które są wystawiane podczas trwającej operacji usuwania przez klucz partycji, mogą zawierać wyniki dokumentów do usunięcia. Może się to zdarzyć, dopóki operacja usuwania nie zostanie w pełni ukończona.
Zapytania wystawione względem magazynu analitycznego podczas trwającej operacji usuwania przez klucz partycji mogą zawierać wyniki usunięcia dokumentów. Może się to zdarzyć, dopóki operacja usuwania nie zostanie w pełni ukończona.
Ciągła kopia zapasowa (przywracanie do punktu w czasie) — przywracanie wyzwalane podczas trwającej operacji usuwania przez klucz partycji może zawierać wyniki dokumentów do usunięcia w przywróconej kolekcji. Nie zaleca się używania tej funkcji w wersji zapoznawczej, jeśli masz scenariusz wymagający ciągłej kopii zapasowej.

Ograniczenia

Usuwanie hierarchicznych kluczy partycji nie jest obsługiwane. Ta funkcja umożliwia usunięcie elementów wyłącznie na podstawie ostatniego poziomu kluczy partycji. Rozważmy na przykład scenariusz, w którym klucz partycji składa się z trzech poziomów hierarchicznych: kraju, stanu i miasta. W tym kontekście można efektywnie stosować funkcję usuwania według kluczy partycji, określając pełny klucz partycji, obejmujący wszystkie poziomy, czyli kraj/stan/miasto. Próba usunięcia przy użyciu kluczy partycji pośrednich, takich jak kraj/stan lub wyłącznie kraj, spowoduje błąd.

Jak przekazać opinię lub zgłosić problem/usterkę

Wyślij wiadomość e-mail cosmosPkDeleteFeedbk@microsoft.com z pytaniami lub opiniami.

Wymagania dotyczące zestawu SDK

Znajdź najnowszą wersję zestawu SDK, która obsługuje tę funkcję.

SDK	Obsługiwane wersje	Link menedżera pakietów
Zestaw .NET SDK w wersji 3	>= 3.25.0-preview (musi być w wersji zapoznawczej)	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/
Zestaw Java SDK w wersji 4	>= 4.19.0 (interfejs API jest oznaczony jako beta)	https://mvnrepository.com/artifact/com.azure/azure-cosmos
Zestaw Python SDK w wersji 4	>= 4..4.0b1 (musi być wersją beta)	https://pypi.org/project/azure-cosmos/4.4.0b1/

Obsługa innych zestawów SDK jest planowana na przyszłość.

Następne kroki

Zobacz następujące artykuły, aby dowiedzieć się więcej o operacjach zestawu SDK w usłudze Azure Cosmos DB.