Udostępnij za pośrednictwem

Hierarchiczne klucze partycji w usłudze Azure Cosmos DB

DOTYCZY: NoSQL

Usługa Azure Cosmos DB dystrybuuje dane między partycjami logicznymi i fizycznymi na podstawie kluczy partycji, aby obsługiwać skalowanie w poziomie. Korzystając z hierarchicznych kluczy partycji (nazywanych również podpartiowaniem), można skonfigurować maksymalnie trzypoziomową hierarchię kluczy partycji w celu dalszej optymalizacji dystrybucji danych i wyższego poziomu skalowania.

Jeśli obecnie używasz kluczy syntetycznych, masz scenariusze, w których klucze partycji mogą przekraczać 20 GB danych, lub chciałbyś zapewnić, że dokument każdej dzierżawy mapuje się na własną partycję logiczną, partycjonowanie podrzędne może pomóc. Jeśli używasz tej funkcji, prefiksy kluczy partycji logicznej mogą przekraczać 20 GB i 10 000 jednostek żądania na sekundę (RU/s). Zapytania według prefiksu są efektywnie kierowane do podzestawu partycji, które przechowują dane.

Wybieranie hierarchicznych kluczy partycji

Jeśli masz aplikacje wielodostępne i obecnie izolujesz najemców za pomocą klucza partycji, partycje hierarchiczne mogą być dla ciebie korzystne. Partycje hierarchiczne umożliwiają skalowanie poza limit 20 GB dla klucza partycji logicznej i są dobrym rozwiązaniem, jeśli chcesz mieć pewność, że dokumenty poszczególnych dzierżawców mogą być skalowane w nieskończoność. Jeśli bieżący klucz partycji lub pojedynczy klucz partycji często osiąga 20 GB, partycje hierarchiczne są doskonałym wyborem dla Twojego obciążenia roboczego.

Jednak w zależności od charakteru obciążenia i kardynalnej wartości klucza pierwszego poziomu może istnieć pewne kompromisy, które szczegółowo omówimy na naszej stronie scenariuszy partycji hierarchicznych.

Podczas wybierania każdego poziomu klucza partycji hierarchicznej należy pamiętać o następujących ogólnych pojęciach dotyczących partycjonowania i zrozumieć, jak każdy z nich może mieć wpływ na obciążenie:

  • Dla wszystkich kontenerów każdy poziom pełnej ścieżki (począwszy od pierwszego poziomu) klucza partycji hierarchicznej powinien:

    • Mają wysoką kardynalność. Pierwsze, drugie i trzecie (jeśli dotyczy) klucze partycji hierarchicznej powinny mieć szeroki zakres możliwych wartości.

      • Posiadanie niskiej liczby wartości na pierwszym poziomie hierarchicznego klucza partycji ogranicza wszystkie operacje zapisu podczas pobierania danych do jednej fizycznej partycji, dopóki nie osiągnie ona 50 GB i nie podzieli się na dwie fizyczne partycje. Załóżmy na przykład, że klucz pierwszego poziomu odnosi się do TenantId i masz tylko pięciu unikalnych najemców. Każdy z tych dzierżawców ma operacje ograniczone do tylko jednej partycji fizycznej, co ogranicza użycie przepustowości tylko do tej jednej partycji fizycznej. Dzieje się tak dlatego, że partycje hierarchiczne optymalizują wszystkie dokumenty z tym samym kluczem pierwszego poziomu, które mają być sortowane na tej samej partycji fizycznej, aby uniknąć zapytań o pełne fanout.
      • Choć może to być w porządku w przypadku obciążeń, w których jednorazowo pozyskujemy wszystkie dane najemców, a następujące operacje są przede wszystkim nastawione na odczyt, może to być niekorzystne w przypadku obciążeń, w których wymagania biznesowe obejmują pozyskiwanie danych w określonym czasie. Jeśli na przykład masz ścisłe wymagania biznesowe, aby uniknąć opóźnień, to maksymalna przepustowość, którą teoretycznie może osiągnąć twoje obciążenie przy pozyskiwaniu danych, wynosi liczba partycji fizycznych * 10 tys. Jeśli klucz najwyższego poziomu ma niską kardynalność, liczba partycji fizycznych prawdopodobnie wynosi 1, chyba że istnieje wystarczająca ilość danych dla klucza poziomu 1, aby można je było rozłożyć na wiele partycji po podziałach, co może potrwać od 4 do 6 godzin.

    • Równomierne rozłożenie użycia jednostek RU i przechowywania danych we wszystkich partycjach logicznych. Ten podział zapewnia równomierne zużycie RU i rozmieszczenie zasobów wśród twoich fizycznych partycji.

      • Jeśli wybierzesz klucz pierwszego poziomu, który wydaje się mieć wysoką kardynalność, na przykład UserId, ale w praktyce obciążenie wykonuje operacje tylko na jednym konkretnym UserId, prawdopodobnie napotkasz gorącą partycję, ponieważ wszystkie operacje są wykonywane tylko na jednej lub kilku partycjach fizycznych.

  • Obciążenia intensywnie odczytowe: zalecamy wybranie hierarchicznych kluczy partycji, które często pojawiają się w zapytaniach.

    • Na przykład obciążenie, które często uruchamia zapytania w celu odfiltrowania określonych sesji użytkownika w aplikacji wielodostępnej, korzysta z hierarchicznych kluczy partycji TenantId, UserId i SessionId, w tej kolejności. Zapytania mogą być efektywnie kierowane tylko do odpowiednich partycji fizycznych, uwzględniając klucz partycji w predykacie filtru. Aby uzyskać więcej informacji na temat wybierania kluczy partycji dla obciążeń wymagających odczytu, zobacz omówienie partycjonowania.

  • Obciążenia z dużym obciążeniem zapisu: Zalecamy użycie wysokiej wartości kardynalnej dla pierwszego poziomu klucza partycji hierarchicznej. Wysoka kardynalność oznacza, że klucz pierwszego poziomu (a także kolejne poziomy) ma co najmniej tysiące unikatowych wartości i więcej unikatowych wartości niż liczba partycji fizycznych.

    • Załóżmy na przykład, że mamy obciążenie, które izoluje dzierżawców według klucza partycji i ma kilku dużych dzierżawców, którzy generują więcej zapisów niż inni. Obecnie usługa Azure Cosmos DB zatrzymuje przyjmowanie danych na dowolnej wartości klucza partycji, jeśli przekracza ona 20 GB danych. W tym obciążeniu Microsoft i Contoso są dużymi najemcami, i przewidujemy, że będą się rozwijać znacznie szybciej niż nasi inni najemcy. Aby uniknąć ryzyka braku możliwości pozyskiwania danych dla tych dzierżaw, hierarchiczne klucze partycji umożliwiają skalowanie tych dzierżaw poza limit 20 GB. Możemy dodać więcej poziomów, takich jak UserId i SessionId, aby zapewnić większą skalowalność wśród tenantów.

    • Aby upewnić się, że obciążenie może pomieścić zapisy dla wszystkich dokumentów z tym samym kluczem pierwszego poziomu, rozważ użycie identyfikatora elementu jako klucza drugiego lub trzeciego poziomu.

    • Jeśli pierwszy poziom nie ma wysokiej kardynalności i obecnie osiągasz limit partycji logicznej 20 GB dla klucza partycji, sugerujemy użycie syntetycznego klucza partycji zamiast klucza partycji hierarchicznej.

Przykładowy przypadek użycia

Załóżmy, że masz scenariusz multitenantowy, w którym przechowujesz informacje o zdarzeniach dla użytkowników w każdej dzierżawie. Informacje o zdarzeniu mogą zawierać wystąpienia zdarzeń, takich jak logowanie, strumień kliknięć lub zdarzenia płatności.

W rzeczywistym scenariuszu niektóre dzierżawy mogą rozrastać się do dużych rozmiarów, z tysiącami użytkowników, natomiast pozostałe dzierżawy są mniejsze i mają tylko kilku użytkowników. Partycjonowanie przez /TenantId może prowadzić do przekroczenia limitu przechowywania 20 GB usługi Azure Cosmos DB na pojedynczej partycji logicznej. Partycjonowanie według /UserId powoduje, że wszystkie zapytania dotyczące dzierżawcy obejmują wiele partycji. Oba podejścia mają znaczące wady.

Użycie syntetycznego klucza partycji, który łączy TenantId i UserId zwiększa złożoność aplikacji. Ponadto syntetyczne zapytania dotyczące klucza partycji dla dzierżawy są nadal między partycjami, chyba że wszyscy użytkownicy są znani i określeni z wyprzedzeniem.

Jeśli obciążenie ma dzierżawców z mniej więcej tymi samymi wzorcami obciążeń, hierarchiczny klucz partycji może pomóc. Za pomocą hierarchicznych kluczy partycji można najpierw podzielić partycje na TenantId, a następnie na UserId. Jeśli oczekujesz, że kombinacja TenantId i UserId wytworzy partycje przekraczające 20 GB, możesz podzielić je dalej na kolejne poziomy, takie jak na SessionId. Ogólna głębokość nie może przekraczać trzech poziomów. Gdy partycja fizyczna przekracza 50 GB magazynu, usługa Azure Cosmos DB automatycznie dzieli partycję fizyczną, tak aby około połowa danych była na jednej partycji fizycznej, a połowa jest na drugiej. W praktyce podział oznacza, że pojedyncza TenantId wartość może przekroczyć 20 GB danych i możliwe jest, że dane TenantId obejmują wiele partycji fizycznych.

Zapytania określające albo TenantId, albo zarówno TenantId i UserId, są efektywnie kierowane tylko do podzbioru partycji fizycznych zawierających odpowiednie dane. Efektywne określanie pełnej lub prefiksowej ścieżki klucza partycji podrzędnej pozwala uniknąć pełnego zapytania fan-out. Jeśli na przykład kontener miał 1000 partycji fizycznych, ale określona TenantId wartość była tylko na pięciu partycjach fizycznych, zapytanie zostanie przekierowane do mniejszej liczby odpowiednich partycji fizycznych.

Używanie identyfikatora elementu w hierarchii

Jeśli kontener ma właściwość, która ma duży zakres możliwych wartości, właściwość prawdopodobnie jest doskonałym wyborem klucza partycji dla ostatniego poziomu hierarchii. Jednym z możliwych przykładów tej właściwości jest identyfikator elementu. Identyfikator elementu właściwości systemu znajduje się w każdym elemencie w Twoim kontenerze. Dodanie identyfikatora elementu jako kolejnego poziomu gwarantuje, że można skalować poza limit klucza partycji logicznej wynoszący 20 GB. Można skalować poza ten limit dla pierwszego poziomu lub dla pierwszego i drugiego poziomu kluczy.

Na przykład może istnieć kontener dla obciążenia wielodostępnego podzielonego na partycje według TenantId i UserId. Jeśli prawdopodobne jest, że pojedyncza kombinacja TenantId i UserId przekroczy 20 GB, zalecamy partycjonowanie przy użyciu trzech poziomów kluczy, gdzie klucz trzeciego poziomu cechuje się wysoką kardynalnością. Przykładem tego scenariusza jest sytuacja, gdy klucz trzeciego poziomu jest identyfikatorem GUID, który ma naturalnie wysoką kardynalność. Jest mało prawdopodobne, że kombinacja TenantId, UserId i identyfikatora GUID przekracza 20 GB, więc kombinacja TenantId i UserId może skutecznie rozbudować się ponad 20 GB.

Aby uzyskać więcej informacji na temat używania identyfikatora elementu jako klucza partycji, zobacz omówienie partycjonowania.

Wprowadzenie

Ważne

Praca z kontenerami korzystającymi z hierarchicznych kluczy partycji jest obsługiwana tylko w następujących wersjach zestawu SDK. Należy użyć obsługiwanego zestawu SDK, aby utworzyć nowe kontenery z hierarchicznymi kluczami partycji oraz wykonać operacje tworzenia, odczytu, aktualizowania i usuwania (CRUD) lub wykonywania zapytań na danych. Jeśli chcesz użyć zestawu SDK lub łącznika, który nie jest obecnie obsługiwany, zgłoś żądanie na naszym forum społeczności.

Znajdź najnowszą wersję zapoznawcza każdego obsługiwanego zestawu SDK:

SDK Obsługiwane wersje Link menedżera pakietów
Zestaw .NET SDK w wersji 3 >= 3.33.0 https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.33.0/
Java SDK 4 >= 4.42.0 https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/cosmos/azure-cosmos/CHANGELOG.md#4420-2023-03-17/
Zestaw JavaScript SDK w wersji 4 4.0.0 https://www.npmjs.com/package/@azure/cosmos/
Zestaw SDK dla języka Python >= 4.6.0 https://pypi.org/project/azure-cosmos/4.6.0/

Tworzenie kontenera przy użyciu hierarchicznych kluczy partycji

Aby rozpocząć, utwórz nowy kontener, korzystając z wstępnie zdefiniowanej listy ścieżek kluczy do podziału do trzech poziomów głębokości.

Nowy kontener można utworzyć przy użyciu jednej z następujących opcji:

  • Azure Portal
  • SDK
  • Szablon usługi Azure Resource Manager
  • Emulator usługi Azure Cosmos DB

Azure Portal

Najprostszym sposobem utworzenia kontenera i określenia hierarchicznych kluczy partycji jest użycie witryny Azure Portal.

  1. Zaloguj się w witrynie Azure Portal.

  2. Przejdź do istniejącej strony konta usługi Azure Cosmos DB for NoSQL.

  3. W menu po lewej stronie wybierz pozycję Eksplorator danych.

    Zrzut ekranu przedstawiający stronę nowego konta usługi Azure Cosmos DB for NoSQL z wyróżnioną opcją menu Eksplorator danych.

  4. W Eksploratorze danych wybierz opcję Nowy kontener .

    Zrzut ekranu przedstawiający opcję Nowy kontener w Eksploratorze danych.

  5. W polu Nowy kontener w polu Klucz partycji wprowadź wartość /TenantId. W pozostałych polach wprowadź dowolną wartość zgodną ze scenariuszem.

    Uwaga

    Tutaj używamy /TenantId jako przykład. Podczas implementowania hierarchicznych kluczy partycji we własnych kontenerach można określić dowolny klucz pierwszego poziomu.

  6. Wybierz dwukrotnie pozycję Dodaj hierarchiczny klucz partycji.

    Zrzut ekranu przedstawiający przycisk dodawania nowego hierarchicznego klucza partycji.

  7. W przypadku drugiej i trzeciej warstwy partycjonowania wprowadź odpowiednio wartości /UserId i /SessionId .

    Zrzut ekranu przedstawiający listę trzech hierarchicznych kluczy partycji.

  8. Wybierz przycisk OK, aby utworzyć kontener.

SDK

Podczas tworzenia nowego kontenera przy użyciu zestawu SDK zdefiniuj listę ścieżek kluczy subpartycji o maksymalnie trzech poziomach głębokości. Podczas konfigurowania właściwości nowego kontenera użyj listy kluczy części podrzędnych.

// List of partition keys, in hierarchical order. You can have up to three levels of keys.
List<string> subpartitionKeyPaths = new List<string> { 
    "/TenantId",
    "/UserId",
    "/SessionId"
};

// Create a container properties object
ContainerProperties containerProperties = new ContainerProperties(
    id: "<container-name>",
    partitionKeyPaths: subpartitionKeyPaths
);

// Create a container that's subpartitioned by TenantId > UserId > SessionId
Container container = await database.CreateContainerIfNotExistsAsync(containerProperties, throughput: 400);

Szablony usługi Azure Resource Manager

Szablon usługi Azure Resource Manager dla kontenera podzielonego na podpartycje jest niemal identyczny ze standardowym kontenerem. Jedyną kluczową różnicą jest wartość ścieżki properties/partitionKey . Aby uzyskać więcej informacji na temat tworzenia szablonu usługi Azure Resource Manager dla zasobu usługi Azure Cosmos DB, zobacz dokumentację szablonu usługi Azure Resource Manager dla usługi Azure Cosmos DB.

partitionKey Skonfiguruj obiekt przy użyciu wartości w poniższej tabeli, aby utworzyć kontener z podziałem na części:

Ścieżka Wartość
paths Lista hierarchicznych kluczy partycji (maksymalnie trzy poziomy głębokości)
kind MultiHash
version 2

Przykładowa definicja klucza partycji

Załóżmy na przykład, że masz hierarchiczny klucz partycji składający się z TenantId>UserId>SessionId. Obiekt partitionKey zostanie skonfigurowany tak, aby zawierał wszystkie trzy wartości we właściwości paths, wartość kindMultiHash oraz wartość version2.

partitionKey: {
  paths: [
    '/TenantId'
    '/UserId'
    '/SessionId'
  ]
  kind: 'MultiHash'
  version: 2
}

Aby uzyskać więcej informacji na temat partitionKey obiektu, zobacz specyfikację ContainerPartitionKey.

Emulator usługi Azure Cosmos DB

Funkcję partycjonowania można przetestować przy użyciu najnowszej wersji lokalnego emulatora usługi Azure Cosmos DB. Aby włączyć podział na partycje w emulatorze, uruchom emulator z katalogu instalacyjnego z flagą /EnablePreview:

.\CosmosDB.Emulator.exe /EnablePreview

Ostrzeżenie

Emulator nie obsługuje obecnie wszystkich funkcji klucza partycji hierarchicznej tak jak portal. Emulator obecnie nie obsługuje następujących funkcji:

  • Tworzenie kontenerów z hierarchicznymi kluczami partycji za pomocą Eksploratora danych
  • Przechodzenie do elementów za pomocą eksploratora danych i interakcja z nimi przy użyciu hierarchicznych kluczy partycji

Aby uzyskać więcej informacji, zobacz Emulator usługi Azure Cosmos DB.

Używanie zestawów SDK do pracy z kontenerami z hierarchicznymi kluczami partycji

Jeśli masz kontener z hierarchicznymi kluczami partycji, użyj wcześniej określonych wersji zestawów SDK platformy .NET lub Java do wykonywania operacji i wykonywania zapytań w tym kontenerze.

Dodawanie elementu do kontenera

Istnieją dwie opcje dodawania nowego elementu do kontenera z włączonymi hierarchicznymi kluczami partycji:

  • Automatyczne wyodrębnianie
  • Ręczne określanie ścieżki

Automatyczne wyodrębnianie

Jeśli przekażesz obiekt z ustawioną wartością klucza partycji, zestaw SDK będzie mógł automatycznie wyodrębnić pełną ścieżkę klucza partycji.

// Create a new item
UserSession item = new UserSession()
{
    id = "f7da01b0-090b-41d2-8416-dacae09fbb4a",
    TenantId = "Microsoft",
    UserId = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    SessionId = "0000-11-0000-1111"
};

// Pass in the object, and the SDK automatically extracts the full partition key path
ItemResponse<UserSession> createResponse = await container.CreateItemAsync(item);

Ręczne określanie ścieżki

Klasa PartitionKeyBuilder w zestawie SDK może utworzyć wartość dla wcześniej zdefiniowanej hierarchicznej ścieżki klucza partycji. Ta klasa jest używana podczas dodawania nowego elementu do kontenera z włączoną podpartycją.

Napiwek

W przypadku dużej skali wydajność może zostać poprawiona, jeśli określisz pełną ścieżkę klucza partycji, nawet jeżeli pakiet SDK może wyodrębnić ścieżkę z obiektu.

// Create a new item object
PaymentEvent item = new PaymentEvent()
{
    id = Guid.NewGuid().ToString(),
    TenantId = "Microsoft",
    UserId = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    SessionId = "0000-11-0000-1111"
};

// Specify the full partition key path when creating the item
PartitionKey partitionKey = new PartitionKeyBuilder()
            .Add(item.TenantId)
            .Add(item.UserId)
            .Add(item.SessionId)
            .Build();

// Create the item in the container
ItemResponse<PaymentEvent> createResponse = await container.CreateItemAsync(item, partitionKey);

Przeprowadzić wyszukiwanie klucza/wartości (odczyt punktowy) przedmiotu

Wyszukiwania klucz/wartość (odczyty punktowe) są wykonywane w sposób podobny do pojemnika bez podziału na podpartycje. Na przykład załóżmy, że masz hierarchiczny klucz partycji składający się z TenantId>UserId>SessionId. Unikatowy identyfikator elementu to identyfikator GUID. Jest reprezentowana jako ciąg, który służy jako unikatowy identyfikator transakcji dokumentu. Aby wykonać odczyt punktu dla pojedynczego elementu, przekaż id właściwość elementu i pełną wartość klucza partycji, w tym wszystkie trzy składniki ścieżki.

// Store the unique identifier
string id = "f7da01b0-090b-41d2-8416-dacae09fbb4a";

// Build the full partition key path
PartitionKey partitionKey = new PartitionKeyBuilder()
    .Add("Microsoft") //TenantId
    .Add("00aa00aa-bb11-cc22-dd33-44ee44ee44ee") //UserId
    .Add("0000-11-0000-1111") //SessionId
    .Build();

// Perform a point read
ItemResponse<UserSession> readResponse = await container.ReadItemAsync<UserSession>(
    id,
    partitionKey
);

Uruchamianie zapytania

Kod zestawu SDK używany do uruchamiania zapytania w kontenerze z podpartycją jest identyczny z uruchamianiem zapytania w kontenerze niepartycyjnym.

Gdy zapytanie określa wszystkie wartości kluczy partycji w filtrze WHERE lub w prefiksie hierarchii kluczy, zestaw SDK automatycznie kieruje zapytanie do odpowiednich partycji fizycznych. Zapytania, które obejmują tylko "środek" hierarchii, to zapytania obejmujące wiele partycji.

Rozważmy na przykład hierarchiczny klucz partycji składający się z TenantId>UserId>SessionId. Elementy filtra zapytania określają, czy zapytanie jest zapytaniem jednopartycyjnym, ukierunkowanym między partycjami, czy zapytaniem typu fan-out.

Zapytanie Trasowanie
SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' AND c.SessionId = '0000-11-0000-1111' Kierowany do pojedynczej partycji logicznej
SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' Kierowany do tylko docelowego podzestawu partycji logicznych i fizycznych, które zawierają dane dla określonych wartości TenantId i UserId. To zapytanie jest ukierunkowanym zapytaniem między partycjami, które zwraca dane dla określonego użytkownika w ramach dzierżawy.
SELECT * FROM c WHERE c.TenantId = 'Microsoft' Kierowany do tylko docelowego podzestawu partycji logicznych i fizycznych, które zawierają dane dla określonej wartości TenantId. To zapytanie jest docelowym zapytaniem między partycjami, które zwraca dane dla wszystkich użytkowników w dzierżawie.
SELECT * FROM c WHERE c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' Kierowany do wszystkich partycji fizycznych, co powoduje utworzenie zapytania obejmującego wiele partycji.
SELECT * FROM c WHERE c.SessionId = '0000-11-0000-1111' Kierowany do wszystkich partycji fizycznych, co powoduje utworzenie zapytania obejmującego wiele partycji.

Zapytanie dotyczące pojedynczej partycji w kontenerze z podpartycjonowaniem

Oto przykład uruchamiania zapytania zawierającego wszystkie poziomy partycjonowania, co skutecznie czyni zapytanie zapytaniem z jedną partycją.

// Define a single-partition query that specifies the full partition key path
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM c WHERE c.TenantId = @tenant-id AND c.UserId = @user-id AND c.SessionId = @session-id")
    .WithParameter("@tenant-id", "Microsoft")
    .WithParameter("@user-id", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee")
    .WithParameter("@session-id", "0000-11-0000-1111");

// Retrieve an iterator for the result set
using FeedIterator<PaymentEvent> results = container.GetItemQueryIterator<PaymentEvent>(query);

while (results.HasMoreResults)
{
    FeedResponse<UserSession> resultsPage = await resultSet.ReadNextAsync();
    foreach(UserSession result in resultsPage)
    {
        // Process result
    }
}

Ukierunkowane zapytanie obejmujące wiele partycji w podpartycjonowanym kontenerze

Oto przykład zapytania, które zawiera podzbiór poziomów subpartycjonowania, skutecznie czyniąc to zapytanie docelowym zapytaniem dotyczących wielu partycji.

// Define a targeted cross-partition query specifying prefix path[s]
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM c WHERE c.TenantId = @tenant-id")
    .WithParameter("@tenant-id", "Microsoft")

// Retrieve an iterator for the result set
using FeedIterator<PaymentEvent> results = container.GetItemQueryIterator<PaymentEvent>(query);

while (results.HasMoreResults)
{
    FeedResponse<UserSession> resultsPage = await resultSet.ReadNextAsync();
    foreach(UserSession result in resultsPage)
    {
        // Process result
    }
}

Ograniczenia i znane problemy

  • Praca z kontenerami korzystającymi z hierarchicznych kluczy partycji jest obsługiwana tylko w zestawie SDK platformy .NET w wersji 3, w zestawie SDK języka Java w wersji 4, w zestawie SDK języka Python i w wersji zapoznawczej zestawu SDK języka JavaScript. Należy użyć obsługiwanego zestawu SDK, aby utworzyć nowe kontenery z hierarchicznymi kluczami partycji oraz wykonać operacje CRUD lub wykonywania zapytań na danych. Obsługa innych zestawów SDK, w tym języka Python, nie jest obecnie dostępna.
  • Istnieją ograniczenia dotyczące różnych łączników usługi Azure Cosmos DB (na przykład w usłudze Azure Data Factory).
  • Można określić hierarchiczne klucze partycji tylko do trzech warstw.
  • Hierarchiczne klucze partycji można obecnie włączać tylko w nowych kontenerach. Należy ustawić ścieżki klucza partycji w momencie tworzenia kontenera i nie można ich później zmienić. Aby używać partycji hierarchicznych w istniejących kontenerach, utwórz nowy kontener z ustawionymi hierarchicznymi kluczami partycji i przenieś dane przy użyciu zadań kopiowania kontenera.
  • Hierarchiczne klucze partycji są obecnie obsługiwane tylko dla interfejsu API dla kont NoSQL. Interfejsy API dla baz danych MongoDB i Cassandra nie są obecnie obsługiwane.
  • Hierarchiczne klucze partycji nie są obecnie obsługiwane przez funkcję użytkowników i uprawnień. Nie można przypisać uprawnienia do częściowego prefiksu ścieżki klucza partycji hierarchicznej. Uprawnienia można przypisać tylko do całej ścieżki klucza partycji logicznej. Na przykład, jeśli partycjonowałeś według TenantId — >UserId, nie możesz przypisać uprawnienia dla określonej wartości TenantId. Można jednak przypisać uprawnienie dla klucza partycji, jeśli określisz zarówno wartość dla TenantId , jak i UserId.

Następne kroki