Azure Cosmos DB'de hiyerarşik bölüm anahtarları

Makale
08/15/2024

UYGULANANLAR: NoSQL

Azure Cosmos DB, yatay ölçeklendirmeyi desteklemek için bölüm anahtarlarınızı temel alarak verilerinizi mantıksal ve fiziksel bölümler arasında dağıtır. Hiyerarşik bölüm anahtarlarını (alt bölümleme olarak da adlandırılır) kullanarak, veri dağıtımını daha iyi hale getirmek ve daha yüksek bir ölçeklendirme düzeyi için bölüm anahtarlarınız için en fazla üç düzeyli bir hiyerarşi yapılandırabilirsiniz.

Bugün yapay anahtarlar kullanıyorsanız, bölüm anahtarlarının 20 GB veriyi aşabileceği veya her kiracının belgesinin kendi mantıksal bölümüyle eşlenmiş olduğundan emin olmak istediğiniz senaryolar varsa, alt bölümleme yardımcı olabilir. Bu özelliği kullanırsanız, mantıksal bölüm anahtarı ön ekleri saniyede 20 GB ve 10.000 istek birimini (RU/sn) aşabilir. Ön eke göre sorgular, verileri barındıran bölümlerin alt kümesine verimli bir şekilde yönlendirilir.

Hiyerarşik bölüm anahtarlarınızı seçme

Çok kiracılı uygulamalarınız varsa ve şu anda kiracıları bölüm anahtarıyla yalıtıyorsanız hiyerarşik bölümler size yararlı olabilir. Hiyerarşik bölümler, 20 GB'lık mantıksal bölüm anahtarı sınırının ötesine ölçeklendirmenize olanak sağlar ve kiracılarınızın belgelerinin her birinin sonsuz ölçeklenebilmesini sağlamak istiyorsanız iyi bir çözüm olur. Geçerli bölüm anahtarınız veya tek bir bölüm anahtarı sık sık 20 GB'a ulaşıyorsa hiyerarşik bölümler iş yükünüz için harika bir seçimdir.

Ancak, iş yükünüzün doğasına ve ilk düzey anahtarınızın ne kadar kardinal olduğuna bağlı olarak, hiyerarşik bölüm senaryoları sayfamızda ayrıntılı olarak ele aldığımız bazı dengeler olabilir.

Hiyerarşik bölüm anahtarınızın her düzeyini seçtiğinizde, aşağıdaki genel bölümleme kavramlarını göz önünde bulundurmanız ve her birinin iş yükünüzü nasıl etkileyebileceğini anlamanız önemlidir:

Tüm kapsayıcılar için, hiyerarşik bölüm anahtarınızın tam yolunun her düzeyi (ilk düzeyden başlayarak) şunları yapmalıdır:
- Yüksek kardinaliteye sahip olun. Hiyerarşik bölümün birinci, ikinci ve üçüncü (varsa) anahtarlarının tümü çok çeşitli olası değerlere sahip olmalıdır.
  - Hiyerarşik bölüm anahtarının ilk düzeyinde düşük kardinaliteye sahip olmak, alma sırasındaki tüm yazma işlemlerinizi 50 GB'a ulaşana ve iki fiziksel bölüme bölünene kadar yalnızca bir fiziksel bölümle sınırlandıracaktır. Örneğin, ilk düzey anahtarınızın açık TenantId olduğunu ve yalnızca 5 benzersiz kiracıya sahip olduğunu varsayalım. Bu kiracıların işlemlerinin her biri yalnızca bir fiziksel bölümle sınırlandırılır ve aktarım hızı tüketiminizi yalnızca bu fiziksel bölümdeki işlemlerle sınırlandırır. Bunun nedeni hiyerarşik bölümlerin, tam kapsamlı sorgulardan kaçınmak için aynı ilk düzey anahtara sahip tüm belgelerin aynı fiziksel bölümde birlikte bulunması için iyileştirilmesidir.
  - Tüm kiracılarımızın verilerini tek seferlik aldığımız ve aşağıdaki işlemlerin daha sonra ağırlıklı olarak okunduğu iş yükleri için bu sorun olmasa da, iş gereksinimlerinizin belirli bir süre içinde veri alımını içerdiği iş yükleri için bu sorun olabilir. Örneğin, gecikme sürelerini önlemek için katı iş gereksinimleriniz varsa, iş yükünüzün teorik olarak veri almak için ulaşabileceği en yüksek aktarım hızı fiziksel bölüm sayısı * 10k'dır. En üst düzey anahtarınız düşük kardinaliteye sahipse, düzey 1 anahtarı için 4-6 saat arasında süren bölmelerden sonra birden çok bölüme yayılması için yeterli veri olmadığı sürece fiziksel bölüm sayısı büyük olasılıkla 1 olur.
- İstek birimi (RU) tüketimini ve veri depolamayı tüm mantıksal bölümlere eşit olarak yayma. Bu yayma, fiziksel bölümlerinizde RU tüketimi ve depolama dağıtımının bile olmasını sağlar.
  - gibi UserIdyüksek kardinaliteye sahip gibi görünen ilk düzey bir anahtar seçerseniz ancak pratikte iş yükünüz yalnızca belirli UserIdbir üzerinde işlem gerçekleştirirse, tüm işlemlerinizin kapsamı yalnızca bir veya birkaç fiziksel bölüm olarak belirlenmiş olduğundan sık erişimli bir bölümle karşılaşabilirsiniz.
Yoğun okumalı iş yükleri: Sorgularınızda sık görünen hiyerarşik bölüm anahtarlarını seçmenizi öneririz.
- Örneğin, çok kiracılı bir uygulamada belirli kullanıcı oturumlarını filtrelemek için sık sık sorgular çalıştıran bir iş yükü, UserId, ve SessionIdhiyerarşik bölüm anahtarlarından TenantIdbu sırayla yararlanabilir. Sorgular, filtre koşuluna bölüm anahtarı dahil edilerek yalnızca ilgili fiziksel bölümlere verimli bir şekilde yönlendirilebilir. Yoğun okumalı iş yükleri için bölüm anahtarlarını seçme hakkında daha fazla bilgi için bölümlemeye genel bakış bölümüne bakın.
Yoğun yazma iş yükleri: Hiyerarşik bölüm anahtarınızın ilk düzeyi için yüksek bir kardinal değeri kullanmanızı öneririz. Yüksek kardinalite, birinci düzey anahtarın (ve sonraki düzeylerin de) en az binlerce benzersiz değere ve fiziksel bölümlerinizin sayısından daha benzersiz değerlere sahip olduğu anlamına gelir.
- Örneğin, kiracıları bölüm anahtarına göre yalıtan bir iş yüküne sahip olduğumuzu ve yazma açısından diğerlerinden daha ağır olan birkaç büyük kiracımız olduğunu varsayalım. Bugün Azure Cosmos DB, 20 GB'ı aşan herhangi bir bölüm anahtarı değerinde veri alımını durduracaktır. Bu iş yükünde Microsoft ve Contoso büyük kiracılardır ve diğer kiracılarımızdan çok daha hızlı büyüydüğünü tahmin ediyoruz. Bu kiracıların verilerini alamama riskini önlemek için hiyerarşik bölüm anahtarları, bu kiracıları 20 GB sınırının ötesinde ölçeklendirmemize olanak tanır. Kiracılar arasında daha yüksek ölçeklenebilirlik sağlamak için UserId ve SessionId gibi daha fazla düzey ekleyebiliriz.
- İş yükünüzün aynı birinci düzey anahtara sahip tüm belgeler için yazma işlemlerine uygun olmasını sağlamak için, öğe kimliğini ikinci veya üçüncü düzey anahtar olarak kullanmayı göz önünde bulundurun.
- İlk düzeyinizin kardinalitesi yüksek değilse ve bugün bölüm anahtarınızda 20 GB mantıksal bölüm sınırına ulaştıysanız, hiyerarşik bölüm anahtarı yerine yapay bölüm anahtarı kullanmanızı öneririz.

Örnek kullanım örneği

Her kiracıdaki kullanıcılar için olay bilgilerini depoladığınız çok kiracılı bir senaryonuz olduğunu varsayalım. Olay bilgileri oturum açma, tıklama akışı veya ödeme olayları dahil ancak bunlarla sınırlı olmamak üzere olay oluşumlarına sahip olabilir.

Gerçek dünya senaryosunda, bazı kiracılar binlerce kullanıcıyla büyüyebilirken, diğer kiracıların çoğu daha küçüktür ve birkaç kullanıcıya sahiptir. ile bölümleme /TenantId , tek bir mantıksal bölümde Azure Cosmos DB 20 GB depolama sınırının aşılmasıyla sonuçlanabilir. ile /UserId bölümleme, kiracıdaki tüm sorguların bölümler arası olmasını sağlar. Her iki yaklaşımın da önemli dezavantajları vardır.

Uygulamayı birleştiren TenantId ve UserId karmaşıklık katan yapay bir bölüm anahtarı kullanma. Ayrıca, kiracı için yapay bölüm anahtarı sorguları, tüm kullanıcılar önceden bilinmediği ve belirtilmediği sürece bölümler arasıdır.

İş yükünüz kabaca aynı iş yükü desenlerine sahip kiracılara sahipse hiyerarşik bölüm anahtarı yardımcı olabilir. Hiyerarşik bölüm anahtarlarıyla, önce üzerinde TenantIdve sonra üzerinde UserIdbölümleyebilirsiniz. ve UserId bileşiminin TenantId 20 GB'ı aşan bölümler üretmesini bekliyorsanız, üzerinde olduğu gibi SessionIdbaşka bir düzeye kadar bölümleyebilirsiniz. Genel derinlik üç düzeyi aşamaz. Fiziksel bölüm 50 GB depolama alanını aştığında, Azure Cosmos DB fiziksel bölümü otomatik olarak böler; böylece verilerin kabaca yarısı bir fiziksel bölümde, yarısı da diğerinde olur. Alt bölümleme, tek TenantId bir değerin 20 GB veriyi aşabileceği ve TenantId verilerin birden çok fiziksel bölüme yayılabildiği anlamına gelir.

, veya hem hem de TenantIdTenantId UserIddeğerlerini belirten sorgular, yalnızca ilgili verileri içeren fiziksel bölümlerin alt kümesine verimli bir şekilde yönlendirilir. Tam veya ön ek alt bölümlenmiş bölüm anahtarı yolunun belirtilmesi, tam kapsamlı bir sorguyu etkili bir şekilde önler. Örneğin, kapsayıcıda 1.000 fiziksel bölüm varsa ancak belirli TenantId bir değer yalnızca 5 fiziksel bölümdeyse, sorgu daha az sayıda ilgili fiziksel bölüme yönlendirilir.

Hiyerarşide öğe kimliğini kullanma

Kapsayıcınızda çok çeşitli olası değerlere sahip bir özellik varsa, özellik hiyerarşinizin son düzeyi için büyük olasılıkla harika bir bölüm anahtarı seçimidir. Bu özellik türünün olası bir örneği öğe kimliğidir. Sistem özellik öğesi kimliği kapsayıcınızdaki her öğede bulunur. Öğe kimliğini başka bir düzey olarak eklemek, mantıksal bölüm anahtarı sınırı olan 20 GB'ın ötesinde ölçeklendirebileceğinizi garanti eder. İlk düzey veya anahtarların birinci ve ikinci düzeyleri için bu sınırın ötesine ölçeklendikleyebilirsiniz.

Örneğin, ve UserIdile TenantId bölümlenmiş çok kiracılı bir iş yükü için kapsayıcınız olabilir. tek bir ve birleşiminin 20 GB'ı aşması TenantId UserId mümkünse, üç anahtar düzeyi kullanarak ve üçüncü düzey anahtarın yüksek kardinaliteye sahip olduğu bölümlemenizi öneririz. Bu senaryoya örnek olarak, üçüncü düzey anahtarın doğal olarak yüksek kardinaliteye sahip bir GUID olması gerekir. , UserIdve GUID birleşiminin TenantId20 GB'ı aşması pek olası olmadığından ve UserId birleşimi TenantId 20 GB'ın üzerine etkili bir şekilde ölçeklendirilebilir.

Bölüm anahtarı olarak öğe kimliğini kullanma hakkında daha fazla bilgi için bölümlemeye genel bakış bölümüne bakın.

Kullanmaya başlayın

Önemli

Hiyerarşik bölüm anahtarları kullanan kapsayıcılarla çalışmak yalnızca aşağıdaki SDK sürümlerinde desteklenir. Hiyerarşik bölüm anahtarlarıyla yeni kapsayıcılar oluşturmak ve veriler üzerinde oluşturma, okuma, güncelleştirme ve silme (CRUD) veya sorgu işlemleri gerçekleştirmek için desteklenen bir SDK kullanmalısınız. Şu anda desteklenmeyen bir SDK veya bağlayıcı kullanmak istiyorsanız lütfen topluluk forumumuza bir istek gönderin.

Desteklenen her SDK'nın en son önizleme sürümünü bulun:

SDK	Desteklenen sürümler	Paket yöneticisi bağlantısı
.NET SDK v3	>= 3.33.0	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.33.0/
Java SDK’sı 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'sı	>= 4.6.0	https://pypi.org/project/azure-cosmos/4.6.0/

Hiyerarşik bölüm anahtarlarını kullanarak kapsayıcı oluşturma

Başlamak için, üç düzeye kadar derinlik düzeyine kadar alt bölümleme anahtar yollarının önceden tanımlanmış bir listesini kullanarak yeni bir kapsayıcı oluşturun.

Şu seçeneklerden birini kullanarak yeni bir kapsayıcı oluşturabilirsiniz:

Azure portal
SDK
Azure Resource Manager şablonu
Azure Cosmos DB öykünücüsü

Azure portal

Kapsayıcı oluşturmanın ve hiyerarşik bölüm anahtarlarını belirtmenin en basit yolu Azure portalını kullanmaktır.

Azure Portal’ında oturum açın.
Mevcut NoSQL için Azure Cosmos DB hesabı sayfasına gidin.
Soldaki menüden Veri Gezgini'ı seçin.
Veri Gezgini Yeni Kapsayıcı seçeneğini belirleyin.
Yeni Kapsayıcı'da Bölüm anahtarı için girin/TenantId. Kalan alanlar için senaryonuzla eşleşen herhangi bir değer girin.

Not

Burada örnek olarak kullanırız /TenantId . Kendi kapsayıcılarınıza hiyerarşik bölüm anahtarları uygularken ilk düzey için herhangi bir anahtar belirtebilirsiniz.
Hiyerarşik bölüm anahtarı ekle'yi iki kez seçin.
Alt bölümlemenin ikinci ve üçüncü katmanları için sırasıyla ve /SessionId girin/UserId.
Konteyneri oluşturmak için Tamam'ı seçin.

SDK

SDK'yı kullanarak yeni bir kapsayıcı oluşturduğunuzda, en fazla üç derinlik düzeyine kadar alt bölümleme anahtar yollarının listesini tanımlayın. Yeni kapsayıcının özelliklerini yapılandırırken alt bölüm anahtarları listesini kullanın.

// 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 Resource Manager şablonları

Alt bölümlenmiş bir kapsayıcı için Azure Resource Manager şablonu, standart bir kapsayıcıyla neredeyse aynıdır. Tek önemli fark, yolun değeridir properties/partitionKey . Azure Cosmos DB kaynağı için Azure Resource Manager şablonu oluşturma hakkında daha fazla bilgi için bkz . Azure Cosmos DB için Azure Resource Manager şablon başvurusu.

partitionKey Alt bölümlenmiş kapsayıcı oluşturmak için aşağıdaki tabloda yer alan değerleri kullanarak nesnesini yapılandırın:

Yol	Değer
`paths`	Hiyerarşik bölüm anahtarları listesi (en fazla üç derinlik düzeyi)
`kind`	`MultiHash`
`version`	`2`

Örnek bölüm anahtarı tanımı

Örneğin, 'nin oluşturduğu TenantId>>UserIdSessionIdhiyerarşik bir bölüm anahtarınız olduğunu varsayalım. partitionKey nesnesi özelliğindeki paths üç değerin tümünü, değerini kind MultiHashve version değerini 2içerecek şekilde yapılandırılır.

Bicep
JSON

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

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

Nesnesi hakkında partitionKey daha fazla bilgi için bkz . ContainerPartitionKey belirtimi.

Azure Cosmos DB öykünücüsü

Azure Cosmos DB için yerel öykünücünün en son sürümünü kullanarak alt bölümleme özelliğini test edebilirsiniz. Öykünücüde alt bölümlendiriciyi etkinleştirmek için öykünücüyü yükleme dizininden şu bayrakla /EnablePreview başlatın:

.\CosmosDB.Emulator.exe /EnablePreview

Uyarı

Öykünücü şu anda portal olarak tüm hiyerarşik bölüm anahtarı özelliklerini desteklemez. Öykünücü şu anda aşağıdakileri desteklemiyor:

Hiyerarşik bölüm anahtarlarıyla kapsayıcılar oluşturmak için Veri Gezgini kullanma
Hiyerarşik bölüm anahtarlarını kullanarak öğelere gitmek ve öğelerle etkileşime geçmek için Veri Gezgini kullanma

Daha fazla bilgi için bkz . Azure Cosmos DB öykünücüsü.

Hiyerarşik bölüm anahtarları olan kapsayıcılarla çalışmak için SDK'ları kullanma

Hiyerarşik bölüm anahtarları içeren bir kapsayıcınız varsa, işlemleri gerçekleştirmek ve bu kapsayıcıda sorgu yürütmek için daha önce belirtilen .NET veya Java SDK sürümlerini kullanın.

Kapsayıcıya öğe ekleme

Hiyerarşik bölüm anahtarları etkin bir kapsayıcıya yeni öğe eklemek için iki seçenek vardır:

Otomatik ayıklama
Yolu el ile belirtin

Otomatik ayıklama

Bölüm anahtarı değeri ayarlanmış bir nesneyi geçirirseniz, SDK tam bölüm anahtarı yolunu otomatik olarak ayıklayabilir.

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

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

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

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

Yolu el ile belirtin

PartitionKeyBuilder SDK'daki sınıf, önceden tanımlanmış hiyerarşik bölüm anahtarı yolu için bir değer oluşturabilir. Alt bölümlemenin etkinleştirildiği bir kapsayıcıya yeni bir öğe eklerken bu sınıfı kullanın.

İpucu

Sdk, yolu nesneden ayıklasa bile tam bölüm anahtarı yolunu belirtirseniz, büyük ölçekte performans geliştirilebilir.

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

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

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 için, bölüm anahtarı yolundaki tüm alanların değerlerinin öğe tanımında belirtildiğinden emin olun.

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

Öğenin anahtar/değer aramasını (nokta okuma) gerçekleştirme

Anahtar/değer aramaları (nokta okumaları), alt bölümlenmemiş bir kapsayıcıya benzer şekilde gerçekleştirilir. Örneğin, içeren TenantId>>UserIdSessionIdhiyerarşik bir bölüm anahtarınız olduğunu varsayalım. Öğenin benzersiz tanımlayıcısı bir GUID'dir. Benzersiz bir belge işlem tanımlayıcısı işlevi görecek bir dize olarak temsil edilir. Tek bir öğede okuma noktası gerçekleştirmek için öğenin özelliğini ve yolun üç bileşeni de dahil olmak üzere bölüm anahtarının tam değerini geçirin id .

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

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

// 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", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "0000-11-0000-1111"]
container.read_item(item=item_id, partition_key=pk)

Sorgu çalıştırma

Alt bölümlenmiş bir kapsayıcıda sorgu çalıştırmak için kullandığınız SDK kodu, alt bölümlenmemiş bir kapsayıcıda sorgu çalıştırmayla aynıdır.

Sorgu, filtredeki veya anahtar hiyerarşisinin ön ekindeki WHERE bölüm anahtarlarının tüm değerlerini belirttiğinde, SDK sorguyu otomatik olarak ilgili fiziksel bölümlere yönlendirir. Hiyerarşinin yalnızca "ortasını" sağlayan sorgular bölümler arası sorgulardır.

Örneğin, 'nin oluşturduğu TenantId>>UserIdSessionIdhiyerarşik bölüm anahtarını göz önünde bulundurun. Sorgu filtresinin bileşenleri, sorgunun tek bölümlü bir sorgu mu, hedeflenen bölümler arası sorgu mu yoksa bir fan-out sorgusu mu olduğunu belirler.

Sorgu	Yönlendirme
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' AND c.SessionId = '0000-11-0000-1111'`	, ve değerlerinin belirtilen değerlerini `TenantIdUserId`içeren tek bir mantıksal ve `SessionId`fiziksel bölüme yönlendirilir.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'`	yalnızca ve `UserId`değerlerinin verilerini içeren mantıksal ve fiziksel bölümlerin hedeflenen alt kümesine `TenantId` yönlendirilir. Bu sorgu, kiracıdaki belirli bir kullanıcının verilerini döndüren hedeflenen bir bölümler arası sorgudur.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft'`	Yalnızca belirtilen değeri için veri içeren mantıksal ve fiziksel bölümlerin hedeflenen alt kümesine `TenantId`yönlendirilir. Bu sorgu, bir kiracıdaki tüm kullanıcılar için veri döndüren hedeflenen bir bölümler arası sorgudur.
`SELECT * FROM c WHERE c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'`	Tüm fiziksel bölümlere yönlendirildi, bu da bir çapraz bölüm sorgusuna neden oldu.
`SELECT * FROM c WHERE c.SessionId = '0000-11-0000-1111'`	Tüm fiziksel bölümlere yönlendirildi, bu da bir çapraz bölüm sorgusuna neden oldu.

Alt bölümlenmiş kapsayıcıda tek bölümlü sorgu

Aşağıda, tüm alt bölümleme düzeylerini içeren ve sorguyu tek bölümlü bir sorgu haline getiren bir sorgu çalıştırma örneği verilmiştir.

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

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

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

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

Alt bölümlenmiş kapsayıcıda hedeflenen çok bölümlü sorgu

Aşağıda, alt bölümleme düzeylerinin bir alt kümesini içeren ve bu sorguyu hedeflenen çok bölümlü bir sorgu haline getiren bir sorgu örneği verilmiştir.

// 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", "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
))

Sınırlamalar ve bilinen sorunlar

Hiyerarşik bölüm anahtarları kullanan kapsayıcılarla çalışma yalnızca .NET v3 SDK'sında, Java v4 SDK'sında, Python SDK'sında ve JavaScript SDK'sının önizleme sürümünde desteklenir. Hiyerarşik bölüm anahtarları olan yeni kapsayıcılar oluşturmak ve veriler üzerinde CRUD veya sorgu işlemleri gerçekleştirmek için desteklenen bir SDK kullanmalısınız. Python da dahil olmak üzere diğer SDK'lar için şu anda destek sunulmamaktadır.
Çeşitli Azure Cosmos DB bağlayıcılarıyla ilgili sınırlamalar vardır (örneğin, Azure Data Factory ile).
Hiyerarşik bölüm anahtarlarını en fazla üç katmanda ayrıntılı olarak belirtebilirsiniz.
Hiyerarşik bölüm anahtarları şu anda yalnızca yeni kapsayıcılarda etkinleştirilebilir. Kapsayıcı oluşturma sırasında bölüm anahtarı yollarını ayarlamanız gerekir ve bunları daha sonra değiştiremezsiniz. Mevcut kapsayıcılarda hiyerarşik bölümleri kullanmak için, hiyerarşik bölüm anahtarları ayarlanmış yeni bir kapsayıcı oluşturun ve kapsayıcı kopyalama işlerini kullanarak verileri taşıyın.
Hiyerarşik bölüm anahtarları şu anda yalnızca NoSQL hesapları için API için desteklenmektedir. MongoDB ve Cassandra API'leri şu anda desteklenmemektedir.
Hiyerarşik bölüm anahtarları şu anda kullanıcılar ve izinler özelliğiyle desteklenmemektedir. Hiyerarşik bölüm anahtarı yolunun kısmi ön ekine izin atayamazsınız. İzinler yalnızca mantıksal bölüm anahtarı yolunun tamamına atanabilir. Örneğin, - >UserIdile TenantId bölümlediyseniz, belirli bir değeri TenantIdiçin bir izin atayamazsınız. Ancak, hem hem de ''UserId''' değerini belirtirseniz bölüm anahtarı için TenantId bir izin atayabilirsiniz.

Sonraki adımlar

Hiyerarşik bölüm anahtarları hakkında SSS bölümüne bakın.
Azure Cosmos DB'de bölümleme hakkında daha fazla bilgi edinin.
Azure Cosmos DB ile Azure Resource Manager şablonlarını kullanma hakkında daha fazla bilgi edinin.

Aracılığıyla paylaş