Hierarchikus partíciókulcsok az Azure Cosmos DB-ben

A KÖVETKEZŐRE VONATKOZIK: NoSQL

Az Azure Cosmos DB a partíciókulcsok alapján osztja el az adatokat a logikai és fizikai partíciók között a horizontális skálázás támogatásához. Hierarchikus partíciókulcsok (más néven alpartitonizáció) használatával akár háromszintű hierarchiát is konfigurálhat a partíciókulcsokhoz az adateloszlás további optimalizálása és a magasabb szintű skálázás érdekében.

Ha ma szintetikus kulcsokat használ, vagy olyan forgatókönyvek vannak, amelyekben a partíciókulcsok mérete meghaladhatja a 20 GB-ot, az alrészezés segíthet. Ha ezt a funkciót használja, a logikai partíciókulcs-előtagok másodpercenként 20 GB-ot és 10 000 kérelemegységet (RU/s) is meghaladhatnak. Az előtag szerinti lekérdezések hatékonyan lesznek átirányítva az adatokat tartalmazó partíciók részhalmazára.

A hierarchikus partíciókulcsok kiválasztása

Ha több-bérlős alkalmazásokkal rendelkezik, javasoljuk, hogy hierarchikus partíciókulcsokat használjon. A hierarchikus partíciók lehetővé teszik a 20 GB-os logikai partíciókulcs-korláton túli skálázást. Ha az aktuális partíciókulcs vagy egy partíciókulcs gyakran eléri a 20 GB-ot, a hierarchikus partíciók nagyszerű választásnak számítanak a számítási feladathoz.

A hierarchikus partíciókulcsok kiválasztásakor fontos szem előtt tartani a következő általános particionálási fogalmakat:

• Minden tároló esetében a hierarchikus partíciókulcs teljes elérési útjának minden szintjén (az első szinttől kezdve) a következőnek kell lennie:

  • Magas számosságú. A hierarchikus partíció első, második és harmadik (ha van) kulcsának számos lehetséges értékkel kell rendelkeznie.
  • A kérelemegység (RU) használata és az adattárolás egyenlően oszlik el az összes logikai partíción. Ez a felosztás még a fizikai partíciók ru-használatát és tárolási elosztását is biztosítja.

• Nagy, olvasási terhelésű számítási feladatok esetén javasoljuk, hogy olyan hierarchikus partíciókulcsokat válasszon, amelyek gyakran jelennek meg a lekérdezésekben. Például egy olyan számítási feladat, amely gyakran futtat lekérdezéseket egy több-bérlős alkalmazás adott felhasználói munkameneteinek szűréséhez, kihasználhatja a hierarchikus partíciókulcsokat TenantIdaz adott SessionIdUserIdsorrendben. A lekérdezések hatékonyan irányíthatók csak a megfelelő fizikai partíciókra a partíciókulcs szűrő predikátumba való belefogadásával. A partíciókulcsok írásvédett számítási feladatokhoz való kiválasztásáról további információt a particionálás áttekintésében talál.

Példa használati esetre

Tegyük fel, hogy van egy több-bérlős forgatókönyve, amelyben minden bérlőben tárol eseményadatokat a felhasználók számára. Az eseményinformációk eseményeseményeket tartalmazhatnak, beleértve a bejelentkezést, a kattintásstreamet vagy a fizetési eseményeket is.

Valós forgatókönyvek esetén egyes bérlők nagy méretűek lehetnek, több ezer felhasználóval, míg a többi bérlő kisebb és néhány felhasználóval rendelkezik. A particionálással /TenantId túllépheti az Azure Cosmos DB 20 GB-os tárolási korlátját egyetlen logikai partíción. Particionálás a bérlői keresztpartíció összes lekérdezésének használatával /UserId . Mindkét megközelítésnek jelentős hátrányai vannak.

Szintetikus partíciókulcs használata, amely egyesíti TenantId és UserId összetettebbé teszi az alkalmazást. Emellett a bérlő szintetikus partíciókulcs-lekérdezései továbbra is keresztpartíciósak, kivéve, ha az összes felhasználót előre ismerik és meg vannak adva.

A hierarchikus partíciókulcsokkal először TenantIda be- és UserIda be. Ha arra számít, hogy a TenantIdUserId kombináció 20 GB-nál nagyobb partíciókat hoz létre, akár egy másik szintre is particionálhat, például a következőre SessionId. A teljes mélység nem haladhatja meg a három szintet. Ha egy fizikai partíció meghaladja az 50 GB-ot, az Azure Cosmos DB automatikusan felosztja a fizikai partíciót úgy, hogy az adatok nagyjából fele az egyik fizikai partíción, a fele pedig a másikon legyen. Az alrészezés gyakorlatilag azt jelenti, hogy egyetlen TenantId érték meghaladhatja a 20 GB-ot, és az adatok több fizikai partícióra TenantId is kiterjedhetnek.

Azokat TenantIda lekérdezéseket, amelyek vagy mindkettőt vagy mindkettőt TenantIdUserIdmegadják, hatékonyan átirányítják csak a releváns adatokat tartalmazó fizikai partíciók részhalmazára. A teljes vagy előtagú részpartíciós partíciókulcs elérési útjának megadása hatékonyan elkerüli a teljes kisugárzó lekérdezést. Ha például a tároló 1000 fizikai partícióval rendelkezik, de egy adott TenantId érték csak 5 fizikai partíción található, a lekérdezés a megfelelő fizikai partíciók kisebb számához lesz irányítva.

Elemazonosító használata a hierarchiában

Ha a tároló olyan tulajdonságot tartalmaz, amely számos lehetséges értékkel rendelkezik, a tulajdonság valószínűleg nagyszerű partíciókulcs-választás a hierarchia utolsó szintjén. Erre a tulajdonságtípusra az egyik lehetséges példa az elemazonosító. A rendszertulajdonság-elem azonosítója a tároló minden elemében megtalálható. Az elemazonosító hozzáadása egy másik szintként garantálja, hogy a 20 GB-os logikai partíciókulcs-korláton túl is méretezhető. Az első vagy az első és a második kulcsszint esetében túllépheti ezt a korlátot.

Előfordulhat például, hogy rendelkezik egy tárolóval egy több-bérlős számítási feladathoz, amely particionálta és UserIdparticionáltaTenantId. Ha lehetséges a 20 GB-ot meghaladó kombináció TenantIdUserId , akkor javasoljuk, hogy három kulcsszinttel particionáljon, és amelyben a harmadik szintű kulcs számossága magas. Erre a forgatókönyvre példa, ha a harmadik szintű kulcs egy GUID, amely természetesen magas számossággal rendelkezik. Nem valószínű, hogy az , UserIdés a GUID együttes értéke TenantIdmeghaladja a 20 GB-ot, így a 20 GB-nál nagyobb skálázás hatékonyan és együttesen TenantIdUserId is skálázható.

Az elemazonosító partíciókulcsként való használatával kapcsolatos további információkért tekintse meg a particionálás áttekintését.

Első lépések

Fontos

A hierarchikus partíciókulcsokat használó tárolók használata csak a következő SDK-verziókban támogatott. Egy támogatott SDK-val új tárolókat kell létrehoznia hierarchikus partíciókulcsokkal, valamint létrehozási, olvasási, frissítési és törlési (CRUD) vagy lekérdezési műveleteket kell végrehajtania az adatokon. Ha olyan SDK-t vagy összekötőt szeretne használni, amely jelenleg nem támogatott, küldjön egy kérelmet a közösségi fórumunkra.

Keresse meg az egyes támogatott SDK-k legújabb előzetes verzióját:

SDK	Támogatott verziók	Csomagkezelő hivatkozás
.NET SDK v3	>= 3.33.0	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.33.0/
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/

Tároló létrehozása hierarchikus partíciókulcsokkal

Első lépésként hozzon létre egy új tárolót az alrészelési kulcs elérési útjainak előre definiált listájával három mélységig.

Az alábbi lehetőségek egyikével hozhat létre új tárolót:

• Azure Portal
• SDK
• Azure Resource Manager-sablon
• Azure Cosmos DB-emulátor

Azure Portal

A tárolók létrehozásának és a hierarchikus partíciókulcsok megadásának legegyszerűbb módja az Azure Portal használata.

1. Jelentkezzen be az Azure Portalra.

2. Nyissa meg a meglévő Azure Cosmos DB for NoSQL-fióklapot.

3. A bal oldali menüben válassza az Adatkezelő lehetőséget.

   

4. Az Adatkezelőben válassza az Új tároló lehetőséget.

   

5. Az Új tárolóban a partíciókulcshoz adja meg a következőt/TenantId: A fennmaradó mezőkbe írja be a forgatókönyvnek megfelelő értékeket.

   Feljegyzés

   Itt példaként használjuk /TenantId . Az első szinthez bármilyen kulcsot megadhat, ha hierarchikus partíciókulcsokat implementál a saját tárolóiban.

6. Válassza kétszer a Hierarchikus partíciókulcs hozzáadása lehetőséget.

   

7. Az alrészezés második és harmadik szintjeihez adja meg és /SessionId adja meg /UserId azokat.

   

8. A tároló létrehozásához kattintson az OK gombra.

SDK

Amikor új tárolót hoz létre az SDK használatával, adja meg az alrészelési kulcs elérési útjainak listáját három mélységi szintig. Az új tároló tulajdonságainak konfigurálásakor használja az alrészkulcsok listáját.

.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

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

Azure Resource Manager-sablonok

Az alpartíciós tárolók Azure Resource Manager-sablonja szinte teljesen megegyezik egy standard tárolóval. Az egyetlen kulcskülönbség az elérési út értéke properties/partitionKey . Az Azure Cosmos DB-erőforrásokHoz készült Azure Resource Manager-sablon létrehozásáról az Azure Cosmos DB Azure Resource Manager-sablonreferenciája nyújt további információt.

Konfigurálja az partitionKey objektumot az alábbi táblázatban szereplő értékekkel egy részpartíciós tároló létrehozásához:

Elérési út	Érték
paths	Hierarchikus partíciókulcsok listája (legfeljebb három mélységi szint)
kind	MultiHash
version	2

Példa partíciókulcs-definícióra

Tegyük fel például, hogy van egy hierarchikus partíciókulcsa, amely a következőből állTenantId>>UserIdSessionId: . Az partitionKey objektum úgy lett konfigurálva, hogy mind a három értéket tartalmazza a paths tulajdonságban, egy kind értéket MultiHashés egy version értéket 2.

Bicep

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

JSON

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

Az objektummal kapcsolatos további információkért partitionKey tekintse meg a ContainerPartitionKey specifikációját.

Azure Cosmos DB-emulátor

Az alpartíciós funkciót az Azure Cosmos DB helyi emulátorának legújabb verziójával tesztelheti. Ha engedélyezni szeretné az emulátoron az alparálást, indítsa el az emulátort a telepítési könyvtárból a /EnablePreview következő jelölővel:

.\CosmosDB.Emulator.exe /EnablePreview

Figyelmeztetés

Az emulátor jelenleg nem támogatja az összes hiearchikus partíciókulcs-funkciót portálként. Az emulátor jelenleg nem támogatja a következőt:

• Tárolók létrehozása hierarchikus partíciókulcsokkal az Adatkezelő használatával
• Az Adatkezelő használata az elemekre való navigáláshoz és az elemek kezeléséhez hierarchikus partíciókulcsokkal

További információ: Azure Cosmos DB emulator.

Az SDK-k használata hierarchikus partíciókulcsokkal rendelkező tárolók használatához

Ha hierarchikus partíciókulcsokkal rendelkező tárolóval rendelkezik, a .NET- vagy Java SDK-k korábban megadott verzióival hajthat végre műveleteket, és lekérdezéseket hajthat végre a tárolón.

Elem hozzáadása tárolóhoz

Két lehetőség van új elem hozzáadására egy olyan tárolóhoz, amelyen engedélyezve vannak a hierarchikus partíciókulcsok:

• Automatikus kinyerés
• Az elérési út manuális megadása

Automatikus kinyerés

Ha olyan objektumot ad át, amelynek a partíciókulcs értéke meg van adva, az SDK automatikusan kinyerheti a teljes partíciókulcs elérési útját.

.NET SDK v3

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

Java SDK v4

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

JavaScript SDK v4

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

Python

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

Az elérési út manuális megadása

Az PartitionKeyBuilder SDK osztálya létrehozhat egy értéket egy korábban definiált hierarchikus partíciókulcs-elérési úthoz. Ezt az osztályt akkor használja, ha új elemet ad hozzá egy olyan tárolóhoz, amelyben engedélyezve van az alrészezés.

Tipp.

Nagy léptékben a teljes partíciókulcs elérési útjának megadása esetén a teljesítmény javulhat, még akkor is, ha az SDK ki tudja nyerni az elérési utat az objektumból.

.NET SDK v3

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

Java SDK v4

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

JavaScript SDK v4

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

Python

Python esetén csak győződjön meg arról, hogy a partíciókulcs elérési útjának összes mezőjének értékei meg vannak adva az elemdefinícióban.

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

Elem kulcs/érték keresésének (pontolvasásának) végrehajtása

A kulcs-/értékkeresések (pontolvasások) a nem részrészes tárolókhoz hasonló módon hajthatók végre. Tegyük fel például, hogy van egy hierarchikus partíciókulcsa, amely a TenantId>>UserIdSessionIdkövetkezőből áll: . Az elem egyedi azonosítója egy GUID. Ez egy sztring, amely egyedi dokumentumtranzakció-azonosítóként szolgál. Ha egyetlen elemen szeretne pontolvasást végezni, adja meg az id elem tulajdonságát és a partíciókulcs teljes értékét, beleértve az elérési út mindhárom összetevőjét.

.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("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
);

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

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

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)

Lekérdezés futtatása

A lekérdezés alrészes tárolón való futtatásához használt SDK-kód megegyezik a lekérdezés nem részrészes tárolón való futtatásával.

Amikor a lekérdezés megadja a partíciókulcsok összes értékét a WHERE szűrőben vagy a kulcshierarchia előtagjában, az SDK automatikusan átirányítja a lekérdezést a megfelelő fizikai partíciókhoz. Azok a lekérdezések, amelyek csak a hierarchia "középső" részét adják meg, partícióközi lekérdezések.

Vegyük például egy hierarchikus partíciókulcsot, amely a következőből állTenantId>>UserIdSessionId: . A lekérdezés szűrőjének összetevői határozzák meg, hogy a lekérdezés egypartíciós lekérdezés, egy célzott keresztpartíciós lekérdezés vagy egy fan-out lekérdezés.

Lekérdezés	Útválasztás
SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b' AND c.SessionId = '0000-11-0000-1111'	Az egyetlen logikai és fizikai partícióra irányítva, amely a megadott értékek TenantIdadatait tartalmazza: , UserIdés SessionId.
SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b'	Csak a logikai és fizikai partíció(k) megcélzott részhalmazára van irányítva, amely a megadott értékekhez TenantId és UserId. Ez a lekérdezés egy célzott keresztpartíciós lekérdezés, amely a bérlő egy adott felhasználójának adatait adja vissza.
SELECT * FROM c WHERE c.TenantId = 'Microsoft'	Csak a logikai és fizikai partíció(k) célként megadott részhalmazára van irányítva, amely a megadott értékhez TenantIdtartozó adatokat tartalmazza. Ez a lekérdezés egy célzott keresztpartíciós lekérdezés, amely egy bérlő összes felhasználójának adatait adja vissza.
SELECT * FROM c WHERE c.UserId = '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b'	Az összes fizikai partícióhoz irányítva, amely egy kiválasztó keresztpartíciós lekérdezést eredményez.
SELECT * FROM c WHERE c.SessionId = '0000-11-0000-1111'	Az összes fizikai partícióhoz irányítva, amely egy kiválasztó keresztpartíciós lekérdezést eredményez.

Egypartíciós lekérdezés egy részpartíciós tárolón

Íme egy példa egy olyan lekérdezés futtatására, amely tartalmazza az alrészezés összes szintjét, így a lekérdezés egypartíciós lekérdezéssé válik.

.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", "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
    }
}

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",
    "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();

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 = '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
}

Python

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]}
    ]
))

Célzott többpartíciós lekérdezés egy részpartíciós tárolón

Íme egy példa egy olyan lekérdezésre, amely az alrészelési szintek egy részhalmazát tartalmazza, így a lekérdezés célzott többpartíciós lekérdezéssé válik.

.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

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

Korlátozások és ismert problémák

• A hierarchikus partíciókulcsokat használó tárolók használata csak a .NET v3 SDK-ban, a Java v4 SDK-ban és a JavaScript SDK előzetes verziójában támogatott. Egy támogatott SDK-val olyan új tárolókat kell létrehoznia, amelyek hierarchikus partíciókulcsokkal rendelkeznek, és CRUD- vagy lekérdezési műveleteket hajtanak végre az adatokon. Más SDK-k, köztük a Python támogatása jelenleg nem érhető el.
• A különböző Azure Cosmos DB-összekötőkre (például az Azure Data Factoryre) korlátozások vonatkoznak.
• A hierarchikus partíciókulcsokat legfeljebb három réteg mélységében adhatja meg.
• A hierarchikus partíciókulcsok jelenleg csak új tárolókon engedélyezhetők. A partíciókulcs elérési útjait a tároló létrehozásakor kell beállítania, és később nem módosíthatja őket. Ha hierarchikus partíciókat szeretne használni a meglévő tárolókon, hozzon létre egy új tárolót a hierarchikus partíciókulcsokkal, és helyezze át az adatokat tárolómásolási feladatok használatával.
• A hierarchikus partíciókulcsok jelenleg csak a NoSQL-fiókok API-ja esetében támogatottak. A MongoDB és a Cassandra API-k jelenleg nem támogatottak.
• A hierarchikus partíciókulcsok jelenleg nem támogatottak az Engedélyek funkcióval. A hierarchikus partíciókulcs elérési útjának részleges előtagjára nem rendelhet engedélyt. Engedélyek csak a teljes logikai partíciókulcs elérési útjára rendelhetők. Ha például particionálta TenantId a - >UserIdértéket, akkor nem rendelhet hozzá egy adott értékhez TenantIdtartozó engedélyt. A partíciókulcshoz azonban engedélyt is hozzárendelhet, ha a "UserId" és a "UserId" értéket TenantId is megadja.

Következő lépések

• Tekintse meg a hierarchikus partíciókulcsokkal kapcsolatos gyakori kérdéseket.
• További információ a particionálásról az Azure Cosmos DB-ben.
• További információ az Azure Resource Manager-sablonok Azure Cosmos DB-vel való használatáról.