Hierarchische Partitionsschlüssel in Azure Cosmos DB

GILT FÜR: NoSQL

Azure Cosmos DB verteilt Ihre Daten basierend auf Ihren Partitionsschlüsseln auf logische und physische Partitionen, um die horizontale Skalierung zu ermöglichen. Mit hierarchischen Partitionsschlüsseln (auch als Unterpartitionierung bekannt) können Sie jetzt eine Hierarchie mit bis zu drei Ebenen für Ihre Partitionsschlüssel konfigurieren, um die Datenverteilung weiter zu optimieren und ein höheres Maß an Skalierung zu ermöglichen.

Wenn Sie bereits synthetische Schlüssel verwenden, Szenarios mit Partitionsschlüsseln haben, die mehr als 20 GB an Daten aufweisen können, oder sicherstellen möchten, dass das Dokument jedes Mandanten der eigenen logischen Partition zugeordnet ist, kann die Subpartitionierung helfen. Wenn Sie diese Funktion verwenden, können Präfixe für logische Partitionsschlüssel 20 GB und 10.000 Anforderungseinheiten pro Sekunde (RU/Sek.) überschreiten. Abfragen nach Präfix werden effizient an die Teilmenge der Partitionen weitergeleitet, die die Daten enthalten.

Auswählen der hierarchischen Partitionsschlüssel

Wenn Sie über mehrinstanzenfähige Anwendungen verfügen und Mandanten derzeit nach Partitionsschlüssel isolieren, können Ihnen hierarchische Partitionen Vorteile bieten. Hierarchische Partitionen ermöglichen es Ihnen, über den 20-GB-Grenzwert des logischen Partitionsschlüssels hinaus zu skalieren, und sind eine gute Lösung, wenn Sie sicherstellen möchten, dass die Dokumente aller Ihrer Mandanten unendlich skaliert werden können. Wenn Ihr aktueller Partitionsschlüssel oder ein einzelner Partitionsschlüssel häufig 20 GB erreicht, sind hierarchische Partitionen eine gute Wahl für Ihre Workload.

Je nach Workload und der Kardinalität Ihres Schlüssels der ersten Ebene können jedoch auch Nachteile entstehen, die auf der Seite der hierarchischen Partitionsszenarios ausführlich behandelt werden.

Beim Auswählen der einzelnen Ebenen Ihres hierarchischen Partitionsschlüssels ist es wichtig, die folgenden allgemeinen Partitionierungskonzepte zu berücksichtigen und zu verstehen, wie sich diese auf Ihre Workload auswirken können:

• Für alle Container sollte jede Ebene des vollständigen Pfads (beginnend mit der ersten Ebene) Ihres hierarchischen Partitionsschlüssels:

  • eine hohe Kardinalität aufweisen. Der erste, zweite und dritte Schlüssel (falls zutreffend) der hierarchischen Partition sollten alle einen großen Bereich möglicher Werte aufweisen.

    • Bei einer niedrigen Kardinalität auf der ersten Ebene des hierarchischen Partitionsschlüssels werden alle Schreibvorgänge zum Aufnahmezeitpunkt auf nur eine physische Partition beschränkt, bis 50 GB erreicht werden und die Partition in zwei physische Partitionen aufgeteilt wird. Angenommen, Ihr Schlüssel der ersten Ebene ist TenantId und Sie haben nur fünf eindeutige Mandanten. Jeder dieser Mandantenvorgänge wird auf nur eine physische Partition beschränkt, wodurch der Durchsatzverbrauch auf genau das beschränkt wird, was sich auf dieser physischen Partition befindet. Dies liegt daran, dass hierarchische Partitionen so optimiert sind, dass für alle Dokumente mit demselben Schlüssel der ersten Ebene auf derselben physischen Partition angeordnet werden, um Abfragen mit vollständigem Fanout zu vermeiden.
    • Dies kann sich für Workloads eignen, bei denen alle Mandantendaten einmal erfasst werden und die nachfolgenden Vorgänge hauptsächlich leseintensiv sind. Für Workloads, bei denen Daten aufgrund von geschäftlichen Anforderungen innerhalb eines bestimmten Zeitraums erfasst werden müssen, ist dies jedoch nicht immer ideal. Wenn Sie beispielsweise aufgrund strenger geschäftlicher Anforderungen Wartezeiten vermeiden müssen, errechnet sich der maximale Durchsatz, den Ihre Workload theoretisch bei der Datenerfassung erreichen kann, aus der Anzahl der physischen Partitionen × 10.000. Wenn Ihr Schlüssel der ersten Ebene eine geringe Kardinalität aufweist, beträgt die Anzahl der physischen Partitionen wahrscheinlich 1, es sei denn, die Datenmenge für den Schlüssel der ersten Ebene ist so groß, dass sie nach Aufteilung auf mehrere Partitionen verteilt werden kann, was vier bis sechs Stunden dauern kann.

  • die zu verbrauchenden Anforderungseinheiten (Request Units, RUs) und die Datenspeicherung gleichmäßig auf alle logischen Partitionen verteilen. Durch diese Verteilung wird ein gleichmäßiger RU-Verbrauch und eine gleichmäßige Speicherverteilung auf Ihren physischen Partitionen sichergestellt.

    • Wenn Sie einen Schlüssel der ersten Ebene wie UserId auswählen, der scheinbar eine hohe Kardinalität hat, Ihre Workload Vorgänge in der Praxis jedoch nur für eine bestimmte Benutzer-ID (UserId) ausführt, wird die Partition wahrscheinlich heiß laufen, weil alle Vorgänge auf nur einer oder wenigen physischen Partitionen ausgeführt werden.

• Leseintensive Workloads: Es wird empfohlen, hierarchische Partitionsschlüssel auszuwählen, die in Ihren Abfragen häufig vorkommen.

  • Beispielsweise kann eine Workload, die häufig Abfragen ausführt, um bestimmte Benutzersitzungen in einer mehrmandantenfähigen Anwendung herauszufiltern, von den hierarchischen Partitionsschlüsseln TenantId, UserId und SessionId (in dieser Reihenfolge) profitieren. Abfragen können effizient nur an die relevanten physischen Partitionen weitergeleitet werden, indem der Partitionsschlüssel in das Filterprädikat eingeschlossen wird. Weitere Informationen zu Partitionsschlüsseln für Workloads mit hohem Lesezugriff finden Sie in der Übersicht über die Partitionierung.

• Schreibintensive Workloads: Es wird empfohlen, eine hohe Kardinalität für die erste Ebene des hierarchischen Partitionsschlüssels zu verwenden. Eine hohe Kardinalität bedeutet, dass der Schlüssel der ersten Ebene (sowie der nachfolgenden Ebenen) mindestens Tausende eindeutige Werte und mehr eindeutige Werte als die Anzahl Ihrer physischen Partitionen aufweist.

  • Angenommen, eine Workload isoliert Mandanten nach Partitionsschlüssel und verfügt über einige große Mandanten, die schreibintensiver sind als andere. Aktuell wird die Datenerfassung von Azure Cosmos DB für jeden Partitionsschlüsselwert beendet, der 20 GB an Daten überschreitet. In dieser Workload sind Microsoft und Contoso große Mandanten, und wir erwarten, dass sie viel schneller wachsen als andere Mandanten. Um zu verhindern, dass diese Mandanten keine Daten erfassen können, können wir diese Mandanten mit hierarchischen Partitionsschlüsseln über den Grenzwert von 20 GB hinaus skalieren. Wir können weitere Ebenen wie UserId und SessionId hinzufügen, um mandantenübergreifend eine höhere Skalierbarkeit sicherzustellen.

  • Um sicherzustellen, dass Ihre Workload Schreibvorgänge für alle Dokumente mit demselben Schlüssel der ersten Ebene unterbringen kann, sollten Sie die Element-ID als Schlüssel der zweiten oder dritten Ebene verwenden.

  • Wenn Ihre erste Ebene keine hohe Kardinalität aufweist und Sie den Grenzwert der logischen Partition von 20 GB für Ihren Partitionsschlüssel erreichen, wird empfohlen, einen synthetischen anstelle eines hierarchischen Partitionsschlüssels zu verwenden.

Beispiel eines Anwendungsfalls

Angenommen, Sie haben ein Szenario mit mehreren Mandanten, in dem Sie Ereignisinformationen für Benutzende in jedem Mandanten speichern. Diese Ereignisinformationen können Ereignisvorkommen wie u. a. Anmelde-, Clickstream- oder Zahlungsereignisse umfassen.

In einem realen Szenario können einige Mandanten groß werden und Tausende von Benutzenden enthalten, während die meisten anderen Mandanten kleiner sind und nur wenige Benutzende umfassen. Die Partitionierung nach /TenantId kann dazu führen, dass der Speichergrenzwert von Azure Cosmos DB von 20 GB für eine einzelne logische Partition überschritten wird. Die Partitionierung nach /UserId führt dazu, dass alle Abfragen auf einem Mandanten partitionsübergreifend durchgeführt werden. Beide Ansätze haben erhebliche Nachteile.

Die Verwendung eines synthetischen Partitionsschlüssels, der TenantId und UserId kombiniert, macht die Anwendung komplexer. Darüber hinaus sind Abfragen mit einem synthetischen Partitionsschlüssel für einen Mandanten weiterhin partitionsübergreifend – außer wenn alle Benutzer im Voraus bekannt sind und angegeben werden.

Wenn Ihre Workload über Mandanten mit ungefähr den gleichen Workloadmustern verfügt, kann ein hierarchischer Partitionsschlüssel helfen. Bei hierarchischen Partitionsschlüsseln können Sie zuerst nach TenantId und dann nach UserId partitionieren. Wenn Sie erwarten, dass durch die Kombination von TenantId und UserId Partitionen mit mehr als 20 GB erzeugt werden, können Sie sogar weiter herunter auf einer anderen Ebene partitionieren, z. B. nach SessionId (Sitzungs-ID). Die Gesamttiefe darf nicht größer als drei Ebenen sein. Wenn eine physische Partition 50 GB Speicher überschreitet, wird sie von Azure Cosmos DB automatisch so aufgeteilt, dass ungefähr die Hälfte der Daten in der einen physischen Partition gespeichert wird und die andere Hälfte in der anderen Partition. Im Grunde bedeutet die Unterpartitionierung, dass eine einzelne TenantId 20 GB Daten überschreiten kann und sich die Daten einer TenantId über mehrere physische Partitionen erstrecken können.

Abfragen, in denen entweder die TenantId oder sowohl die TenantId als auch die UserId angegeben sind, werden effizient nur an die Teilmenge von physischen Partitionen weitergeleitet, in denen die relevanten Daten enthalten sind. Durch Angabe des vollständigen Pfads oder Präfixpfads des unterpartitionierten Partitionsschlüssels wird eine vollständige Auffächerungsabfrage effektiv vermieden. Wenn der Container beispielsweise 1,000 physische Partitionen enthält, der Wert einer bestimmten TenantId aber nur in fünf dieser Partitionen vorkommt, würde die Abfrage nur an die kleinere Anzahl von relevanten physischen Partitionen weitergeleitet.

Verwenden der Element-ID in der Hierarchie

Wenn Ihr Container eine Eigenschaft mit einer Vielzahl von möglichen Werten hat, ist dies wahrscheinlich eine gute Wahl für den Partitionsschlüssel für die letzte Ebene Ihrer Hierarchie. Ein mögliches Beispiel für einen solchen Eigenschaftstyp ist die Element-ID. Die Systemeigenschaft Element-ID ist in jedem in Ihrem Container enthaltenen Element vorhanden. Das Hinzufügen der Element-ID als eine weitere Ebene garantiert, dass Sie über den Grenzwert für logische Partitionsschlüssel von 20 GB hinaus skalieren können. Sie können für die erste oder erste und zweite Schlüsselebene über diesen Grenzwert hinaus skalieren.

Beispielsweise können Sie über einen Container für eine mehrmandantenfähige Workload verfügen, die nach TenantId und UserIdpartitioniert ist. Wenn es möglich ist, dass eine einzelne Kombination aus TenantId und UserId 20 GB überschreitet, wird die Partitionierung mit drei Schlüsselebenen empfohlen, bei denen der Schlüssel der dritten Ebene eine hohe Kardinalität hat. Ein Beispiel für dieses Szenario ist, wenn der Schlüssel der dritten Ebene eine GUID mit natürlich hoher Kardinalität ist. Da es unwahrscheinlich ist, dass die Kombination aus TenantId, UserId und einer GUID 20 GB überschreitet, kann die Kombination aus TenantId und UserId effektiv über 20 GB hinaus skaliert werden.

Weitere Informationen zur Verwendung der Element-ID als Partitionsschlüssel finden Sie in der Übersicht über die Partitionierung.

Erste Schritte

Hier finden Sie die aktuelle Vorschauversion der unterstützten SDKs:

Erstellen eines Containers unter Verwendung von hierarchischen Partitionsschlüsseln

Erstellen Sie zuerst einen neuen Container anhand einer vordefinierten Liste der Unterpartitionsschlüsselpfade mit einer Tiefe von bis zu drei Ebenen.

Sie können einen neuen Container erstellen, indem Sie eine der folgenden Optionen verwenden:

• Azure-Portal
• SDK
• Azure Resource Manager-Vorlage
• Azure Cosmos DB-Emulator

Azure-Portal

Die einfachste Möglichkeit zum Erstellen eines Containers und Angeben von hierarchischen Partitionsschlüsseln ist das Verwenden des Azure-Portals.

1. Melden Sie sich beim Azure-Portal an.

2. Navigieren Sie zur Seite des vorhandenen „Azure Cosmos DB for NoSQL“-Kontos.

3. Wählen Sie im Menü auf der linken Seite die Option Daten-Explorer aus.

   

4. Wählen Sie im Daten-Explorer die Option Neuer Container aus.

   

5. Geben Sie unter Neuer Container unter Partitionsschlüssel/TenantId ein. Geben Sie bei den verbleibenden Feldern einen beliebigen Wert ein, der Ihrem Szenario entspricht.

   Hinweis

   Wir verwenden hier /TenantId als Beispiel. Sie können für die erste Ebene einen beliebigen Schlüssel angeben, wenn Sie hierarchische Partitionsschlüssel für Ihre eigenen Container implementieren.

6. Wählen Sie Hierarchischen Partitionsschlüssel hinzufügen zweimal aus.

   

7. Geben Sie für die zweite und dritte Ebene der Unterpartitionierung /UserId bzw. /SessionId ein.

   

8. Wählen Sie OK aus, um den Container zu erstellen.

SDK

Definieren Sie beim Erstellen eines neuen Containers mithilfe des SDK eine Liste der Unterpartitionsschlüsselpfade mit einer Tiefe von bis zu drei Ebenen. Verwenden Sie beim Konfigurieren der Eigenschaften des neuen Containers die Liste der Unterpartitionsschlüssel.

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

// List of partition keys, in hierarchical order. You can have up to three levels of keys.
List<String> subpartitionKeyPaths = new ArrayList<String>();
subpartitionKeyPaths.add("/TenantId");
subpartitionKeyPaths.add("/UserId");
subpartitionKeyPaths.add("/SessionId");

//Create a partition key definition object with Kind ("MultiHash") and Version V2
PartitionKeyDefinition subpartitionKeyDefinition = new PartitionKeyDefinition();
subpartitionKeyDefinition.setPaths(subpartitionKeyPaths);
subpartitionKeyDefinition.setKind(PartitionKind.MULTI_HASH);
subpartitionKeyDefinition.setVersion(PartitionKeyDefinitionVersion.V2);

// Create a container properties object
CosmosContainerProperties containerProperties = new CosmosContainerProperties("<container-name>", subpartitionKeyDefinition);

// Create a throughput properties object
ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

// Create a container that's subpartitioned by TenantId > UserId > SessionId
Mono<CosmosContainerResponse> container = database.createContainerIfNotExists(containerProperties, throughputProperties);

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);

container = database.create_container(
        id=container_name, partition_key=PartitionKey(path=["/tenantId", "/userId", "/sessionId"], kind="MultiHash")
    )

Azure-Ressourcen-Manager-Vorlagen

Die Azure Resource Manager-Vorlage für einen unterpartitionierten Container ist fast identisch mit einem Standardcontainer. Der einzige wichtige Unterschied ist der Wert des Pfads properties/partitionKey. Weitere Informationen zum Erstellen einer Azure Resource Manager-Vorlage für eine Azure Cosmos DB-Ressource finden Sie in der Referenz zu Azure Resource Manager-Vorlagen für Azure Cosmos DB.

Konfigurieren Sie das Objekt partitionKey mithilfe der Werte in der folgenden Tabelle, um einen unterpartitionierten Container zu erstellen:

Beispiel für die Partitionsschlüsseldefinition

Angenommen, Sie verfügen über einen hierarchischen Partitionsschlüssel, der aus TenantId>UserId>SessionId besteht. Dann würde das Objekt partitionKey so konfiguriert, dass es alle drei Werte in der paths-Eigenschaft, den kind-Wert MultiHash und den version-Wert 2 enthält.

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

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

Weitere Informationen zum Objekt partitionKey finden Sie im Artikel ContainerPartitionKey-Spezifikation.

Azure Cosmos DB-Emulator

Sie können die Unterpartitionierungsfunktion mit der aktuellen Version des lokalen Emulators für Azure Cosmos DB testen. Starten Sie den Emulator im Installationsverzeichnis mit dem /EnablePreview-Flag, um die Unterpartitionierung im Emulator zu aktivieren:

.\CosmosDB.Emulator.exe /EnablePreview

Weitere Informationen finden Sie unter Azure Cosmos DB-Emulator.

Verwenden der SDKs zum Arbeiten mit Containern mit hierarchischen Partitionsschlüsseln

Wenn Sie einen Container mit hierarchischen Partitionsschlüsseln haben, verwenden Sie die zuvor angegebenen Versionen der .NET- oder Java-SDKs zum Durchführen von Vorgängen und Ausführen von Abfragen für diesen Container.

Hinzufügen eines Elements zu einem Container

Zum Hinzufügen eines neuen Elements zu einem Container, für den hierarchische Partitionsschlüssel aktiviert sind, stehen Ihnen zwei Optionen zur Auswahl:

• Automatische Extraktion
• Manuelle Angabe des Pfads

Automatische Extraktion

Wenn Sie ein Objekt mit festgelegtem Partitionsschlüsselwert übergeben, kann das SDK automatisch den vollständigen Partitionsschlüsselpfad extrahieren.

// Create a new item
UserSession item = new UserSession()
{
    id = "f7da01b0-090b-41d2-8416-dacae09fbb4a",
    TenantId = "Microsoft",
    UserId = "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b",
    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);

// Create a new item
UserSession item = new UserSession();
item.setId("f7da01b0-090b-41d2-8416-dacae09fbb4a");
item.setTenantId("Microsoft");
item.setUserId("8411f20f-be3e-416a-a3e7-dcd5a3c1f28b");
item.setSessionId("0000-11-0000-1111");
   
// Pass in the object, and the SDK automatically extracts the full partition key path
Mono<CosmosItemResponse<UserSession>> createResponse = container.createItem(item);

 // Create a new item
const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b',
    SessionId: '0000-11-0000-1111'
}

// Pass in the object, and the SDK automatically extracts the full partition key path
const { resource: document } = await = container.items.create(item);

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

Manuelle Angabe des Pfads

Die PartitionKeyBuilder-Klasse im SDK kann einen Wert für einen zuvor definierten hierarchischen Partitionsschlüsselpfad erstellen. Verwenden Sie diese Klasse, wenn Sie einem Container mit aktivierter Unterpartitionierung ein neues Element hinzufügen.

// Create a new item object
PaymentEvent item = new PaymentEvent()
{
    id = Guid.NewGuid().ToString(),
    TenantId = "Microsoft",
    UserId = "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b",
    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);

// Create a new item object
UserSession item = new UserSession();
item.setTenantId("Microsoft");
item.setUserId("8411f20f-be3e-416a-a3e7-dcd5a3c1f28b");
item.setSessionId("0000-11-0000-1111");
item.setId(UUID.randomUUID().toString());

// Specify the full partition key path when creating the item
PartitionKey partitionKey = new PartitionKeyBuilder()
            .add(item.getTenantId())
            .add(item.getUserId())
            .add(item.getSessionId())
            .build();
       
// Create the item in the container     
Mono<CosmosItemResponse<UserSession>> createResponse = container.createItem(item, partitionKey);

const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b',
    SessionId: '0000-11-0000-1111'
}

// Specify the full partition key path when creating the item
const partitionKey: PartitionKey = new PartitionKeyBuilder()
    .addValue(item.TenantId)
    .addValue(item.UserId)
    .addValue(item.SessionId)
    .build();

// Create the item in the container
const { resource: document } = await container.items.create(item, partitionKey);

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

Ausführen einer Schlüssel-Wert-Suche (Punktlesevorgang) für ein Element

Schlüssel-Wert-Suchen (Punktlesevorgänge) werden ähnlich wie bei einem nicht unterpartitionierten Container ausgeführt. Nehmen wir beispielsweise an, Sie verfügen über einen hierarchischen Partitionsschlüssel, der aus TenantId>UserId>SessionId besteht. Der eindeutige Bezeichner für das Element ist eine GUID. Er ist eine als Zeichenfolge dargestellte GUID, die als eindeutiger Dokumenttransaktionsbezeichner dient. Wenn Sie einen Punktlesevorgang für ein einzelnes Element durchführen möchten, übergeben Sie die id-Eigenschaft des Elements und den vollständigen Wert für den Partitionsschlüssel, einschließlich aller drei Komponenten des Pfads.

// 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("8411f20f-be3e-416a-a3e7-dcd5a3c1f28b") //UserId
    .Add("0000-11-0000-1111") //SessionId
    .Build();

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

// 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("8411f20f-be3e-416a-a3e7-dcd5a3c1f28b") //UserId
    .add("0000-11-0000-1111") //SessionId
    .build();
    
// Perform a point read
Mono<CosmosItemResponse<UserSession>> readResponse = container.readItem(id, partitionKey, UserSession.class);

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

// Build the full partition key path
const partitionKey: PartitionKey = new PartitionKeyBuilder()
    .addValue(item.TenantId)
    .addValue(item.UserId)
    .addValue(item.SessionId)
    .build();

// Perform a point read
const { resource: document } = await container.item(id, partitionKey).read();

item_id = "f7da01b0-090b-41d2-8416-dacae09fbb4a"
pk = ["Microsoft", "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b", "0000-11-0000-1111"]
container.read_item(item=item_id, partition_key=pk)

Ausführen einer Abfrage

Der SDK-Code, der zum Ausführen einer Abfrage für einen unterpartitionierten Container verwendet wird, ist identisch mit dem Code einer Abfrage für einen nicht unterpartitionierten Container.

Wenn in der Abfrage alle Werte der Partitionsschlüssel im WHERE-Filter oder ein Präfix der Schlüsselhierarchie angegeben sind, leitet das SDK die Abfrage automatisch an die entsprechenden physischen Partitionen weiter. Abfragen, die nur die „Mitte“ der Hierarchie angeben, sind partitionsübergreifende Abfragen.

Betrachten Sie beispielsweise einen hierarchischen Partitionsschlüssel, der aus TenantId>UserId>SessionId besteht. Die Komponenten des Abfragefilters bestimmen, ob es sich bei der Abfrage um eine Abfrage für eine einzelne Partition, eine partitionsübergreifende Zielabfrage oder eine Auffächerungsabfrage handelt.

Abfrage für eine einzelne Partition für einen unterpartitionierten Container

Hier ist ein Beispiel für die Ausführung einer Abfrage, die alle Unterpartitionierungsebenen enthält, wodurch sie effektiv zu einer Abfrage für eine einzelne Partition wird.

// 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", "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b")
    .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
    }
}

// Define a single-partition query that specifies the full partition key path
String query = String.format(
    "SELECT * FROM c WHERE c.TenantId = '%s' AND c.UserId = '%s' AND c.SessionId = '%s'",
    "Microsoft",
    "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b",
    "0000-11-0000-1111"
);

// Retrieve an iterator for the result set
CosmosPagedFlux<UserSession> pagedResponse = container.queryItems(
    query, options, UserSession.class);

pagedResponse.byPage().flatMap(fluxResponse -> {
    for (UserSession result : page.getResults()) {
        // Process result
    }
    return Flux.empty();
}).blockLast();

// Define a single-partition query that specifies the full partition key path
const query: string = "SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b' AND c.SessionId = '0000-11-0000-1111'";

// Retrieve an iterator for the result set
const queryIterator = container.items.query(query);

while (queryIterator.hasMoreResults()) {
    const { resources: results } = await queryIterator.fetchNext();
    // Process result
}

pk = ["Microsoft", "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b", "0000-11-0000-1111"]
items = list(container.query_items(
    query="SELECT * FROM r WHERE r.tenantId=@tenant_id and r.userId=@user_id and r.sessionId=@session_id",
    parameters=[
        {"name": "@tenant_id", "value": pk[0]},
        {"name": "@user_id", "value": pk[1]},
        {"name": "@session_id", "value": pk[2]}
    ]
))

Gezielte Abfrage für mehrere Partitionen für einen unterpartitionierten Container

Hier ist ein Beispiel für eine Abfrage, die eine Teilmenge der Unterpartitionierungsebenen enthält, wodurch diese Abfrage effektiv zu einer Zielabfrage für mehrere Partitionen wird.

// 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
    }
}

// Define a targeted cross-partition query specifying prefix path[s]
String query = String.format(
    "SELECT * FROM c WHERE c.TenantId = '%s'",
    "Microsoft"
);

// Retrieve an iterator for the result set
CosmosPagedFlux<UserSession> pagedResponse = container.queryItems(
    query, options, UserSession.class);

pagedResponse.byPage().flatMap(fluxResponse -> {
    for (UserSession result : page.getResults()) {
        // Process result
    }
    return Flux.empty();
}).blockLast();

// Define a targeted cross-partition query specifying prefix path[s]
const query: string = "SELECT * FROM c WHERE c.TenantId = 'Microsoft'";

// Retrieve an iterator for the result set
const queryIterator = container.items.query(query);

while (queryIterator.hasMoreResults()) {
    const { resources: results } = await queryIterator.fetchNext();
    // Process result
}

pk = ["Microsoft", "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b", "0000-11-0000-1111"]
# enable_cross_partition_query should be set to True as the container is partitioned
items = list(container.query_items(
    query="SELECT * FROM r WHERE r.tenantId=@tenant_id and r.userId=@user_id",
    parameters=[
        {"name": "@tenant_id", "value": pk[0]},
        {"name": "@user_id", "value": pk[1]}
    ],
    enable_cross_partition_query=True
))

Einschränkungen und bekannte Probleme

• Container mit hierarchischen Partitionsschlüsseln werden nur für das .NET-v3-SDK, das Java-v4-SDK, das Python-SDK und die Vorschau des JavaScript-SDK unterstützt. Sie müssen ein unterstütztes SDK verwenden, um neue Container mit hierarchischen Partitionsschlüsseln zu erstellen und CRUD- bzw. Abfragevorgänge für die Daten auszuführen. Unterstützung für andere SDKs, einschließlich Python, ist derzeit nicht verfügbar.
• Bei verschiedenen Azure Cosmos DB-Connectoren (z. B. Azure Data Factory) gibt es Einschränkungen.
• Sie können hierarchische Partitionsschlüssel nur mit einer Tiefe von bis zu drei Ebenen angeben.
• Hierarchische Partitionsschlüssel können derzeit nur für neue Container aktiviert werden. Sie müssen Partitionsschlüsselpfade zum Zeitpunkt der Containererstellung festlegen, und Sie können sie später nicht mehr ändern. Um hierarchische Partitionen in vorhandenen Containern zu verwenden, erstellen Sie einen neuen Container mit den hierarchischen Partitionsschlüsseln und verschieben die Daten mithilfe von Containerkopieraufträgen.
• Hierarchische Partitionsschlüssel werden derzeit nur für die „API for NoSQL“-Konten unterstützt. Die APIs für MongoDB und Cassandra werden derzeit nicht unterstützt.
• Hierarchische Partitionsschlüssel werden derzeit nicht mit der Berechtigungsfunktion unterstützt. Sie können einem Teilpräfix des hierarchischen Partitionsschlüsselpfads keine Berechtigung zuweisen. Berechtigungen können nur dem gesamten logischen Partitionsschlüsselpfad zugewiesen werden. Wenn Sie beispielsweise nach TenantId - >UserId partitioniert haben, können Sie keine Berechtigung zuweisen, die für einen bestimmten Wert von TenantId gilt. Sie können jedoch eine Berechtigung für einen Partitionsschlüssel zuweisen, wenn Sie sowohl den Wert für TenantId als auch den Wert für „UserId“ angeben.

Nächste Schritte

• Lesen Sie die häufig gestellten Fragen zu hierarchischen Partitionsschlüsseln.
• Erfahren Sie mehr über die Partitionierung in Azure Cosmos DB.
• Erfahren Sie mehr über die Verwendung von Azure Resource Manager-Vorlagen mit Azure Cosmos DB.