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

Şunlara uygulanır: ✅ 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çin

Ç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 birinci 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ı dezavantajlar 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, ilk düzeyden başlayarak, hiyerarşik bölüm anahtarınızın tam yolunun her düzeyi şunları içermelidir:
- 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ırlar. Örneğin, birinci düzey anahtarınızın TenantId üzerinde olduğunu ve yalnızca beş benzersiz kiracınız 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ının bölmelerden sonra birden çok bölüme yayılması için yeterli veri yoksa ve tamamlanması 4-6 saat arasında sürebilirse, fiziksel bölüm sayısı büyük olasılıkla 1'dir.
- RU tüketimini ve veri depolamayı tüm mantıksal bölümlere eşit olarak yayma. Bu dağılım, fiziksel bölümlerinizde RU tüketimi ve depolama dağıtımının eşit şekilde olmasını sağlar.
  - gibi UserIdyüksek kardinaliteye sahip gibi görünen birinci 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ü, sırasıyla TenantId, UserId ve SessionId hiyerarşik bölüm anahtarlarından 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, bölüm anahtarını kullanarak kiracıları izole eden bir iş yüküne ve yazma yükü açısından diğerlerinden daha fazla olan birkaç büyük kiracıya sahip olduğumuzu varsayalım. Bugün Azure Cosmos DB, 20 GB veriyi aşarsa herhangi bir bölüm anahtarı değerinde veri alımını durduruyor. 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. /TenantId tarafından bölümleme, 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.

TenantId ve UserId birleştiren yapay bir bölüm anahtarı kullanmak uygulamaya karmaşıklık katar. 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. Eğer TenantId ve UserId bileşiminin 20 GB'ı aşan bölümler üretmesini bekliyorsanız, SessionId üzerinde baş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 TenantIdTenantIdUserIddeğ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 beş fiziksel bölümdeyse, sorgu daha az sayıda ilgili fiziksel bölüme yönlendirilir.

Hiyerarşide öğe kimliğini kullanma

Hiyerarşik bölüm anahtarlarını kullanırken, 20 GB mantıksal bölüm anahtarı sınırının ötesine ölçeklenebileceğinizi garanti etmek için öğe kimliğini hiyerarşinizdeki son düzey olarak ekleyebilirsiniz. Bu yaklaşım özellikle birinci düzey veya birinci ve ikinci anahtar düzeylerinin birleşimi için kullanışlıdır.

Örneğin, TenantId ve UserId ile bölümlenmiş çok kiracılı bir iş yükünde, bu değerlerin tek bir bileşimi 20 GB'ı aşarsa, yüksek kardinaliteye sahip üçüncü düzey bir anahtar ekleyin. GUID iyi bir seçimdir çünkü , TenantIdve GUID birleşiminin UserId20 GB'ı aşma olasılığı düşüktür ve TenantId bileşiminin UserId 20 GB'ın üzerine etkili bir şekilde ölçeklendirilmesine olanak sağlar.

Öğe kimliğinin neden etkili bir bölüm anahtarı seçimi (yüksek kardinalite, çift dağıtım ve verimli nokta okumaları) olduğuna ilişkin kapsamlı yönergeler için bkz. Bölümlemeye genel bakış bölümünde bölüm anahtarı olarak öğe kimliğini kullanma .

Get started

Important

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 topluluk forumumuzda 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
Java SDK v4	>= 4.42.0	https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/cosmos/azure-cosmos
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

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

Başlamak için, önceden tanımlanmış alt bölümleme anahtarı yollarının listesini kullanarak üç derinlik düzeyine kadar 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 kolay yolu Azure portalını kullanmaktır.

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

Note

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.
İki kez Hiyerarşik bölüm anahtarı ekle'yi seçin.
Alt bölümlemenin ikinci ve üçüncü katmanları için sırasıyla /UserId ve /SessionId girin.
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")
    )

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

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 Azure Cosmos DB için Azure Resource Manager şablon referansına bakın.

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	Value
`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, TenantId>UserId>SessionId'den oluşan hiyerarşik bir bölüm anahtarınız olduğunu varsayalım. partitionKey nesnesi, paths özelliğinde tüm üç değeri, bir kind değeri olarak MultiHash ve bir version değeri olarak 2 iç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
}

partitionKey nesnesi hakkında daha fazla bilgi için ContainerPartitionKey belirtimi'ne bakın.

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ü üzerinde alt bölümlendirmeyi etkinleştirmek için, öykünücüyü yükleme dizininden /EnablePreview bayrağı ile başlatın.

.\CosmosDB.Emulator.exe /EnablePreview

Warning

Ö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 emülatör.

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 .NET veya Java SDK'larının önceden belirtilen 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)

Automatic extraction is not supported in the Go SDK.

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.

Tip

SDK'nin yolu nesneden çıkarabilmesine rağmen, tam bölüm anahtarı yolunu belirtmek, büyük ölçekte performansı iyileştirebilir.

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

NewPartitionKey , bölüm anahtarı değeri oluşturmak için oluşturucu benzeri bir API'yi kullanıma sunar. Değer, kapsayıcıda öğe oluşturmak için kullanılabilecek bir PartitionKey nesnesidir.

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)

Öğ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>UserId>SessionIdhiyerarş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 id özelliğini ve yolun üç bileşeni de dahil olmak üzere bölüm anahtarının tam değerini girin.

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

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)

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.

Hiyerarşik bölüm anahtarı yolunun ön ekini hedefleyen sorgular için, sorgunun verimli bir şekilde yönlendirilebilmesi için bu önde gelen bölüm anahtarı değerlerini WHERE yan tümcesine eklemeniz gerekir. Değerleri sadece PartitionKeyBuilder aracılığıyla sağlamak tek başına verimli yönlendirmeyi garanti etmez. WHERE yan tümcesinden bölüm anahtarı değerlerini atlayan sorgular önemli ölçüde daha yüksek RU maliyetlerine neden olabilir.

Örneğin, TenantId>UserId>SessionId'ten oluşan hiyerarş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.

Query	Routing
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' AND c.SessionId = '0000-11-0000-1111'`	Belirtilen , `TenantId`, ve `UserId` değerlerini içeren verinin bulunduğu `SessionId` yönlendirilir.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'`	Yalnızca belirtilen ve `TenantId` değerlerine ait verileri içeren mantıksal ve fiziksel bölümlerin hedeflenmiş alt kümesine 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ümlere ayrılmış 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]}
    ]
))

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
}

Alt bölümlenmiş kapsayıcıda hedeflenen çoklu bölüm sorgusu

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

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
}

Mevcut kapsayıcıları hiyerarşik bölüm anahtarlarına geçirme

Hiyerarşik bölüm anahtarları kapsayıcı oluşturma zamanında ayarlanmalıdır ve mevcut kapsayıcılarda değiştirilemez. Mevcut bir kapsayıcıyı hiyerarşik bölüm anahtarlarını kullanacak şekilde geçirmek için:

İstenen hiyerarşik bölüm anahtarı yapılandırmasıyla yeni bir kapsayıcı oluşturun.
Çevrimdışı geçiş için kapsayıcı kopyalama işlerini kullanarak verileri kopyalayın veya dinamik geçiş için değişiklik akışını en düşük kapalı kalma süresiyle kullanın.
Uygulamanızı yeni kapsayıcıya işaret eden şekilde güncelleştirin.
Sorguların hiyerarşik anahtar ön eklerini kullanarak doğru olduğunu doğrulayın.

Sınırlamalar ve bilinen sorunlar

Hiyerarşik bölüm anahtarları kullanan kapsayıcılarla çalışmak 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, TenantId - >UserId ile bölümleme yaptıysanız, TenantId için belirli bir değere sahip izni atayamazsınız. Ancak, hem TenantId hem de UserId değerlerini belirtirseniz, bölüm anahtarı için bir izin atayabilirsiniz.

Sonraki Adımlar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-27