Hierarchické oddílové klíče ve službě Azure Cosmos DB

PLATÍ PRO: NoSQL

Azure Cosmos DB distribuuje vaše data mezi logické a fyzické oddíly na základě klíčů oddílů, aby podporovala horizontální škálování. Pomocí hierarchických klíčů oddílů (označovaných také jako dílčí dělení) můžete pro klíče oddílů nakonfigurovat až tříúrovňovou hierarchii, abyste mohli dále optimalizovat distribuci dat a vyšší úroveň škálování.

Pokud dnes používáte syntetické klíče, máte scénáře, ve kterých klíče oddílů můžou překročit 20 GB dat, nebo byste chtěli zajistit, aby se dokument každého tenanta mapoval na vlastní logický oddíl, může pomoct dílčí dělení. Pokud použijete tuto funkci, předpony logického klíče oddílu mohou překročit 20 GB a 10 000 jednotek žádostí za sekundu (RU/s). Dotazy podle předpony se efektivně směrují na podmnožinu oddílů, které obsahují data.

Zvolte své hierarchické klíče oddílů

Pokud máte víceklientské aplikace a aktuálně izolujete klienty podle klíče oddílu, mohou být pro vás užitečné hierarchické oddíly. Hierarchické oddíly umožňují škálovat nad rámec limitu logického klíče oddílu 20 GB a jsou dobrým řešením, pokud chcete zajistit, aby se dokumenty jednotlivých tenantů mohly škálovat neomezeně. Pokud váš aktuální klíč oddílu nebo pokud jeden klíč oddílu často dosahuje 20 GB, jsou hierarchické oddíly pro vaši úlohu skvělou volbou.

V závislosti na povaze vaší pracovní zátěže a na tom, jak zásadní je váš klíč na první úrovni, mohou však existovat určité kompromisy, které podrobně rozebíráme na stránce s hierarchickými scénáři rozdělení.

Když zvolíte každou úroveň hierarchického klíče oddílu, je důležité mít na paměti následující obecné koncepty dělení a porozumět tomu, jak každý z nich může ovlivnit vaše úlohy:

• Pro všechny kontejnery by každá úroveň úplné cesty (počínaje první úrovní) vašeho hierarchického klíče oddílů měla:

  • Mají vysokou kardinalitu. První, druhý a třetí klíč hierarchického oddílu by měl mít širokou škálu možných hodnot, pokud je to relevantní.

    • Mít nízkou kardinalitu na první úrovni hierarchického klíče partitionu omezuje vaše operace zápisu při přijímání dat na jeden fyzický oddíl, dokud tento oddíl nedosáhne 50 GB a nerozdělí se na dva fyzické oddíly. Předpokládejme například, že váš klíč první úrovně je na TenantId a máte pouze pět jedinečných tenantů. Všechny operace těchto tenantů jsou omezené jenom na jeden fyzický oddíl, což omezuje spotřebu propustnosti jenom na to, co je v daném fyzickém oddílu. Důvodem je, že hierarchické oddíly optimalizují umístění všech dokumentů se stejným klíčem první úrovně, aby byly umístěny na stejném fyzickém oddílu a předešlo se dotazům s plným rozšířením.
    • I když to může být v pořádku pro úlohy, kdy jednorázově načteme všechna data našich tenantů a následující operace jsou především orientovány na čtení, může to být nevhodné pro úlohy, kde vaše obchodní požadavky vyžadují příjem dat v rámci určitého časového okna. Například pokud máte přísné obchodní požadavky k zamezení latencí, maximální propustnost, které může vaše úloha teoreticky dosáhnout pro ingestování dat, je počet fyzických oddílů × 10 tisíc. Pokud má klíč nejvyšší úrovně nízkou kardinalitu, je pravděpodobné, že počet fyzických oddílů je 1, pokud není dostatek dat pro klíč úrovně 1 na to, aby se po rozdělení rozložil mezi více oddílů, což může trvat 4 až 6 hodin.

  • Rovnoměrně rozprostřete spotřebu RU a úložiště dat napříč všemi logickými oddíly. Toto rozložení zajišťuje rovnoměrnou spotřebu RU a distribuci úložiště napříč fyzickými oddíly.

    • Pokud zvolíte klíč první úrovně, který vypadá jako vysoká kardinalita UserId, ale v praxi vaše úloha provádí operace pouze na jednom konkrétním UserIdoddílu, pak pravděpodobně narazíte na horký oddíl, protože všechny operace jsou vymezeny pouze na jeden nebo několik fyzických oddílů.

• Úlohy náročné na čtení: Doporučujeme zvolit hierarchické klíče oddílů, které se často zobrazují v dotazech.

  • Například úloha, která často spouští dotazy, jež vyfiltrují konkrétní uživatelské relace ve víceklientských aplikacích, může těžit z hierarchických klíčů oddílů TenantId, UserId a SessionId v uvedeném pořadí. Dotazy lze efektivně směrovat pouze na relevantní fyzické oddíly zahrnutím klíče oddílu do predikátu filtru. Další informace o výběru oddílových klíčů pro úlohy náročné na čtení najdete v přehledu dělení.

• Úlohy náročné na zápis: Pro první úroveň vašeho hierarchického klíče oddílu doporučujeme použít vysokou kardinalitu. Vysoká kardinalita znamená, že klíč první úrovně (a také klíče dalších úrovní) má alespoň tisíce jedinečných hodnot a více jedinečných hodnot, než kolik je vašich fyzických oddílů.

  • Předpokládejme například, že máme úlohu, která izoluje tenanty podle klíče oddílu a má několik velkých tenantů, které jsou náročnější na zápis než jiné. Dnes Azure Cosmos DB přestane přijímat data na libovolnou hodnotu klíče oddílu, pokud překročí 20 GB dat. V tomto pracovním zatížení jsou společnosti Microsoft a Contoso velkými nájemci a předpokládáme, že porostou mnohem rychleji než naši ostatní nájemci. Aby se zabránilo riziku, že nebude možné načít data pro tyto tenanty, hierarchické klíče pro oddíly nám umožňují rozšířit tyto tenanty nad rámec limitu 20 GB. Můžeme přidat další úrovně jako UserId a SessionId pro zajištění vyšší škálovatelnosti napříč tenanty.

  • Pokud chcete zajistit, aby vaše úloha vyhovovala zápisům pro všechny dokumenty se stejným klíčem první úrovně, zvažte použití ID položky jako klíče druhé nebo třetí úrovně.

  • Pokud vaše první úroveň nemá vysokou kardinalitu a dosáhnete limitu 20 GB logického oddílu u klíče oddílu ještě dnes, doporučujeme místo hierarchického klíče oddílu použít syntetický klíč oddílu.

Příklad případu použití

Předpokládejme, že máte scénář s více tenanty, ve kterém ukládáte informace o událostech pro uživatele v každém tenantovi. Informace o akcích mohou zahrnovat věci jako přihlášení, clickstream nebo platební události.

V reálném scénáři můžou někteří tenanti růst s tisíci uživatelů, zatímco mnoho dalších tenantů je menší a má několik uživatelů. Dělení podle /TenantId může vést k překročení limitu úložiště Azure Cosmos DB 20 GB na jednom logickém oddílu. Rozdělení pomocí /UserId způsobí, že všechny dotazy na nájemci procházejí mezi oddíly. Oba přístupy mají významné nevýhody.

Použití syntetického klíče oddílu, který kombinuje TenantId a UserId, přidává aplikaci složitost. Dotazy na syntetické klíče oddílu pro tenanta jsou navíc stále rozdělené mezi oddíly, pokud nejsou všichni uživatelé známi a nezadávají se předem.

Pokud má vaše výpočetní zátěž tenanty s přibližně stejnými vzory, hierarchický klíč pro dělení může pomoci. Pomocí hierarchických klíčů oddílů můžete nejprve rozdělit oddíl na TenantIda pak na UserId. Pokud očekáváte, že TenantId a UserId kombinace vytvoří oddíly, které překračují 20 GB, můžete dokonce dále rozdělit na jinou úroveň, například na SessionId. Celková hloubka nesmí překročit tři úrovně. Když fyzický oddíl překročí 50 GB úložiště, Azure Cosmos DB automaticky rozdělí fyzický oddíl tak, aby přibližně polovina dat byla na jednom fyzickém oddílu a polovina je na druhém. V podstatě subpartitioning znamená, že jedna TenantId hodnota může překročit 20 GB dat a je možné, aby TenantId data byla rozložena přes více fyzických oddílů.

Dotazy, které specifikují buď TenantId, nebo obě TenantId a UserId, jsou efektivně směrovány pouze na tu podmnožinu fyzických oddílů, které obsahují relevantní data. Zadáním úplné nebo předponové cesty klíče podrozděleného oddílu se účinně vyhnete úplnému fan-out dotazu. Pokud by například kontejner měl 1 000 fyzických oddílů, ale konkrétní TenantId hodnota byla pouze na pěti fyzických oddílech, dotaz by se směroval na menší počet relevantních fyzických oddílů.

Použití ID položky v hierarchii

Pokud má váš kontejner vlastnost s velkým rozsahem možných hodnot, je pravděpodobně skvělou volbou jako klíč oddílu pro nejspodnější úroveň vaší hierarchie. Jedním z možných příkladů tohoto typu vlastnosti je ID položky. ID systémové vlastnosti existuje u každé položky v kontejneru. Přidání ID položky jako další úrovně zaručuje, že můžete provádět škálování nad rámec limitu klíče logické partition ve velikosti 20 GB. Můžete škálovat nad rámec tohoto limitu pro první úroveň nebo pro první a druhou úroveň klíčů.

Můžete mít například kontejner pro víceklientskou úlohu rozdělenou podle TenantId a UserId. Pokud je možné, aby jedna kombinace TenantId a UserId překročila 20 GB, doporučujeme rozčlenit pomocí tří úrovní klíčů, přičemž klíč třetí úrovně má vysokou kardinalitu. Příkladem tohoto scénáře je, když klíč třetí úrovně je GUID, který má přirozeně vysokou kardinalitu. Je nepravděpodobné, že kombinace TenantId, UserId a GUID překračuje 20 GB, takže kombinace TenantId a UserId může efektivně škálovat nad 20 GB.

Další informace o použití ID položky jako klíče oddílu najdete v přehledu particionování.

Začínáme

Důležité

Práce s kontejnery, které používají hierarchické klíče oddílů, je podporována pouze v následujících verzích sady SDK. Podporovanou sadu SDK musíte použít k vytvoření nových kontejnerů s hierarchickými klíči oddílu a k provádění operací vytváření, čtení, aktualizace a odstraňování (CRUD) nebo dotazování na data. Pokud chcete použít sadu SDK nebo konektor, který se v současné době nepodporuje, vytvořte žádost na našem komunitním fóru.

Vyhledejte nejnovější verzi Preview každé podporované sady SDK:

sada SDK	Podporované verze	Odkaz správce balíčků
.NET SDK v3	>= 3,33,0	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.33.0/
Sada Java SDK v4	>= 4,42,0	https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/cosmos/azure-cosmos/CHANGELOG.md#4420-2023-03-17/
JavaScript SDK v4	4.0.0	https://www.npmjs.com/package/@azure/cosmos/
Python SDK	>= 4.6.0	https://pypi.org/project/azure-cosmos/4.6.0/

Vytvoření kontejneru pomocí hierarchických klíčů pro oddíly

Začněte vytvořením nového kontejneru pomocí předdefinovaného seznamu klíčových cest pododdílů až do tří úrovní hloubky.

Nový kontejner můžete vytvořit pomocí jedné z těchto možností:

• Azure Portal
• sada SDK
• Šablona Azure Resource Manageru
• Emulátor služby Azure Cosmos DB

Azure Portal

Nejjednodušší způsob, jak vytvořit kontejner a zadat hierarchické klíče oddílů, je použití webu Azure Portal.

1. Přihlaste se k portálu Azure.

2. Přejděte na existující stránku účtu Azure Cosmos DB for NoSQL.

3. V nabídce vlevo vyberte Průzkumník dat.

   

4. Ve Průzkumníku dat vyberte možnost Nový kontejner.

   

5. V novém kontejneru zadejte hodnotu pro klíč oddílu, /TenantId. U zbývajících polí zadejte libovolnou hodnotu, která odpovídá vašemu scénáři.

   Poznámka:

   Jako příklad zde použijeme /TenantId . Při implementaci hierarchických klíčů oddílů do vlastních kontejnerů můžete zadat libovolný klíč pro první úroveň.

6. Dvakrát vyberte Přidat hierarchický klíč oddílu.

   

7. Pro druhou a třetí úroveň dílčího dělení zadejte /UserId a /SessionId v uvedeném pořadí.

   

8. Tlačítkem OK vytvořte kontejner.

sada SDK

Při vytváření nového kontejneru pomocí sady SDK definujte seznam cest klíčů dílčích oddílů až do tří úrovní hloubky. Seznam klíčů dílčích oddílů použijte při konfiguraci vlastností nového kontejneru.

.NET SDK v3

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

Java SDK v4

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

JavaScript SDK v4

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

Python SDK

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

Go SDK

_, err = db.CreateContainer(context.Background(), azcosmos.ContainerProperties{
	ID: "demo_container",
	PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{
		Paths:   []string{"/TenantId", "/UserId", "/SessionId"},
		Kind:    azcosmos.PartitionKeyKindMultiHash,
		Version: 2,
	},
}, nil)

Šablony Azure Resource Manageru

Šablona Azure Resource Manageru pro kontejner s dílčími oddíly je téměř identická se standardním kontejnerem. Jediným klíčovým rozdílem je hodnota properties/partitionKey cesty. Další informace o vytvoření šablony Azure Resource Manageru pro prostředek Azure Cosmos DB najdete v referenčních informacích k šabloně Azure Resource Manageru pro službu Azure Cosmos DB.

partitionKey Nakonfigurujte objekt pomocí hodnot v následující tabulce a vytvořte tak kontejner s dílčími oddíly:

Cesta	Hodnota
paths	Seznam hierarchických klíčů oddílů (maximálně tři úrovně)
kind	MultiHash
version	2

Příklad definice klíče oddílu

Předpokládejme například, že máte hierarchický klíč oddílu, který se skládá z TenantId>UserId>SessionId. Objekt partitionKey by byl nakonfigurován tak, aby zahrnoval všechny tři hodnoty ve paths vlastnosti, kind hodnotu MultiHasha version hodnotu 2.

Biceps

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

JSON

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

Další informace o objektu partitionKey naleznete ve specifikaci ContainerPartitionKey.

Emulátor služby Azure Cosmos DB

Funkci dílčího dělení můžete otestovat pomocí nejnovější verze místního emulátoru služby Azure Cosmos DB. Pokud chcete povolit podparticionování v emulátoru, spusťte emulátor z instalačního adresáře s příznakem /EnablePreview.

.\CosmosDB.Emulator.exe /EnablePreview

Varování

Emulátor v současné době nepodporuje všechny funkce hierarchického klíče oddílu, jako portál. Emulátor v současné době nepodporuje:

• Použití nástroje Data Explorer k vytvoření kontejnerů s hierarchickými klíči pro rozdělení dat
• Použití Průzkumníka dat k přechodu na položky a interakci s nimi pomocí hierarchických klíčů oddílů

Další informace najdete v tématu Emulátor služby Azure Cosmos DB.

Použijte SDK k práci s kontejnery, které mají hierarchické klíče oddílů

Pokud máte kontejner s hierarchickými klíči oddílů, použijte dříve zadané verze sad .NET nebo Java SDK k provedení operací a spuštění dotazů na tomto kontejneru.

Přidání položky do kontejneru

Existují dvě možnosti přidání nové položky do kontejneru s povolenými hierarchickými klíči oddílů:

• Automatická extrakce
• Ruční zadání cesty

Automatická extrakce

Pokud předáte objekt se sadou hodnot klíče oddílu, sada SDK může automaticky extrahovat úplnou cestu klíče oddílu.

.NET SDK v3

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

Java SDK v4

// Create a new item
UserSession item = new UserSession();
item.setId("f7da01b0-090b-41d2-8416-dacae09fbb4a");
item.setTenantId("Microsoft");
item.setUserId("00aa00aa-bb11-cc22-dd33-44ee44ee44ee");
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);

JavaScript SDK v4

 // Create a new item
const item: 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
const { resource: document } = await = container.items.create(item);

Python SDK

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

Go SDK

Automatic extraction is not supported in the Go SDK.

Ruční zadání cesty

Třída PartitionKeyBuilder v sadě SDK může vytvořit hodnotu pro dříve definovanou hierarchickou cestu klíče oddílu. Tuto třídu použijte, když přidáte novou položku do kontejneru, který má povolenou dílčí dělení.

Návod

Ve velkém měřítku může být výkon zlepšen tím, že zadáte úplnou cestu klíče oddílu, i když SDK může cestu extrahovat z objektu.

.NET SDK v3

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

Java SDK v4

// Create a new item object
UserSession item = new UserSession();
item.setTenantId("Microsoft");
item.setUserId("00aa00aa-bb11-cc22-dd33-44ee44ee44ee");
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);

JavaScript SDK v4

const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
    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);

Python SDK

V Pythonu se ujistěte, že v definici položky jsou zadány hodnoty pro všechna pole v cestě klíče oddílu.

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

Go SDK

NewPartitionKey zveřejňuje rozhraní API podobné tvůrci pro vytvoření hodnoty klíče oddílu. Hodnota je PartitionKey objekt, který lze použít k vytvoření položek v kontejneru.

tenantId := "Microsoft"
userId := "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
sessionId := "0000-11-0000-1111"

pk := azcosmos.NewPartitionKeyString(tenantId).AppendString(userId).AppendString(sessionId)

data := map[string]any{
	"id":        uuid.NewString(),
	"TenantId":  tenantId,
	"UserId":    userId,
	"SessionId": sessionId,
}

container, _ := c.NewContainer(dbName, containerName)

item, _ := json.Marshal(data)
container.CreateItem(context.Background(), pk, item, nil)

Vyhledání položky pomocí klíče/hodnoty (přímé čtení)

Vyhledávání klíč/hodnota (čtení bodů) se provádí způsobem, který se podobá kontejneru, který není součástí oddílu. Předpokládejme například, že máte hierarchický klíč oddílu, který se skládá z TenantId>UserId>SessionId. Jedinečný identifikátor položky je identifikátor GUID. Představuje se jako řetězec, který slouží jako jedinečný identifikátor transakce dokumentu. Chcete-li provést čtení bodu u jedné položky, předejte id vlastnost položky a úplnou hodnotu klíče oddílu, včetně všech tří součástí cesty.

.NET SDK v3

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

Java SDK v4

// 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
Mono<CosmosItemResponse<UserSession>> readResponse = container.readItem(id, partitionKey, UserSession.class);

JavaScript SDK v4

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

Python SDK

item_id = "f7da01b0-090b-41d2-8416-dacae09fbb4a"
pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "0000-11-0000-1111"]
container.read_item(item=item_id, partition_key=pk)

Go SDK

itemId := "some item id"
tenantId := "Microsoft"
userId := "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
sessionId := "0000-11-0000-1111"

// Build the full partition key path
pk := azcosmos.NewPartitionKeyString(tenantId).AppendString(userId).AppendString(sessionId)

// Perform a point read
item, err := container.ReadItem(context.Background(), pk, itemId, nil)

var result map[string]any
json.Unmarshal(item.Value, &result)

Spuštění dotazu

SDK kód, který používáte ke spuštění dotazu v kontejneru s pododdíly, je stejný jako při spuštění dotazu v kontejneru bez pododdílů.

Když dotaz určuje všechny hodnoty klíčů oddílů ve WHERE filtru nebo v předponě hierarchie klíčů, sada SDK automaticky směruje dotaz do odpovídajících fyzických oddílů. Dotazy, které poskytují pouze "prostřední" část hierarchie, jsou dotazy, které operují napříč oddíly.

Představte si například hierarchický klíč oddílu, který se skládá z TenantId>UserId>SessionId. Komponenty filtru dotazu určují, zda se jedná o dotaz v rámci jednoho oddílu, cílený dotaz napříč oddíly nebo dotaz rozšířený na více oddílů.

Dotaz	Směrování
SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' AND c.SessionId = '0000-11-0000-1111'	Směrováno do jednoho logického a fyzického oddílu, který obsahuje data pro zadané hodnoty , TenantIdUserIda SessionId.
SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'	Směrováno pouze na cílovou podmnožinu logických a fyzických oddílů , které obsahují data pro zadané hodnoty TenantId a UserId. Tento dotaz je cílený dotaz napříč oddíly, který vrací data pro konkrétního uživatele v nájemci.
SELECT * FROM c WHERE c.TenantId = 'Microsoft'	Směrováno pouze na cílenou podmnožinu logických a fyzických oddílů, které obsahují data pro zadanou hodnotu TenantId. Tento dotaz je cílový dotaz napříč oddíly, který vrací data pro všechny uživatele v tenantovi.
SELECT * FROM c WHERE c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'	Směrováno na všechny fyzické oddíly, což vede k rozšířenému dotazu přes oddíly.
SELECT * FROM c WHERE c.SessionId = '0000-11-0000-1111'	Směrováno na všechny fyzické oddíly, což vede k rozšířenému dotazu přes oddíly.

Dotaz na jeden oddíl v podrozděleném kontejneru

Tady je příklad spuštění dotazu, který zahrnuje všechny úrovně dílčích oddílů, čímž se dotaz efektivně vytvoří jako dotaz s jedním oddílem.

.NET SDK v3

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

Java SDK v4

// 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",
    "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "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();

JavaScript SDK v4

// 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 = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' 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
}

Python SDK

pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "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]}
    ]
))

Go SDK

tenantId := "Microsoft"
userId := "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
sessionId := "0000-11-0000-1111"

// Build the full partition key path
pk := azcosmos.NewPartitionKeyString(tenantId).AppendString(userId).AppendString(sessionId)

query := "SELECT * FROM r WHERE r.TenantId=@tenant_id and r.UserId=@user_id and r.SessionId=@session_id"

pager := container.NewQueryItemsPager(query, pk, &azcosmos.QueryOptions{
	QueryParameters: []azcosmos.QueryParameter{
		{
			Name:  "@tenant_id",
			Value: tenantId,
		},
		{
			Name:  "@user_id",
			Value: userId,
		},
		{
			Name:  "@session_id",
			Value: sessionId,
		},
	},
})

for pager.More() {
    // Read the next page of results
}

Cílený dotaz na více oddílů v kontejneru s pododdíly

Tady je příklad dotazu, který obsahuje podmnožinu úrovní dílčího oddílení, účinně činí tento dotaz cíleným víceparciovým dotazem.

.NET SDK v3

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

Java SDK v4

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

JavaScript SDK v4

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

Python SDK

pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "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
))

Go SDK

tenantId := "Microsoft"
userId := "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"

emptyPartitionKey := azcosmos.NewPartitionKey()

query := "SELECT * FROM r WHERE r.TenantId=@tenant_id and r.UserId=@user_id"

pager := container.NewQueryItemsPager(query, emptyPartitionKey, &azcosmos.QueryOptions{
	QueryParameters: []azcosmos.QueryParameter{
		{
			Name:  "@tenant_id",
			Value: tenantId,
		},
		{
			Name:  "@user_id",
			Value: userId,
		},
	},
})

for pager.More() {
    // Read the next page of results
}

Omezení a známé problémy

• Práce s kontejnery, které používají hierarchické klíče oddílů, se podporuje pouze v sadě .NET v3 SDK, v sadě Java SDK v4, v sadě Python SDK a ve verzi Preview sady JavaScript SDK. K vytvoření nových kontejnerů s hierarchickými klíči oddílů a provádění operací CRUD nebo dotazování na data musíte použít podporovanou sadu SDK. Podpora jiných sad SDK, včetně Pythonu, není momentálně dostupná.
• Existují omezení různých konektorů služby Azure Cosmos DB (například u služby Azure Data Factory).
• Hierarchické klíče oddílů můžete zadat pouze až do tří úrovní hloubky.
• Hierarchické klíče oddílů je v současné době možné povolit jenom u nových kontejnerů. Cesty ke klíči oddílu musíte nastavit při vytváření kontejneru a později je nemůžete změnit. Pokud chcete pro existující kontejnery používat hierarchické oddíly, vytvořte nový kontejner s nastavenými hierarchickými klíči oddílu a přesuňte data pomocí úloh kopírování kontejneru.
• Hierarchické klíče oddílů jsou v současné době podporovány pouze pro účty API pro NoSQL. Rozhraní API pro MongoDB a Cassandra nejsou v současné době podporována.
• U uživatelů a oprávnění se v současné době nepodporují hierarchické klíče oddílů. Nemůžete přiřadit oprávnění k částečné předponě hierarchického klíče oddílu. Oprávnění je možné přiřadit pouze k celé logické cestě klíče oddílu. Pokud jste například rozdělili oddíly TenantId podle – >UserId, nemůžete přiřadit oprávnění, která je určena pro určitou hodnotu TenantId. Můžete však přiřadit oprávnění pro klíč oddílu, pokud zadáte hodnotu pro TenantId i UserId.

Další kroky

• Nejčastější dotazy k hierarchickým klíčům oddílů ve službě Azure Cosmos DB
• Dělení a horizontální škálování ve službě Azure Cosmos DB
• Šablony Azure Resource Manager s databázovými účty Microsoft.DocumentDB