使用大分区键创建容器Create containers with large partition key

Azure Cosmos DB 使用基于哈希的分区方案实现数据的水平缩放。Azure Cosmos DB uses hash-based partitioning scheme to achieve horizontal scaling of data. 在 2019 年 5 月 3 日之前创建的所有 Azure Cosmos 容器都使用哈希函数根据分区键的前 100 个字节计算哈希。All Azure Cosmos containers created before May 3 2019 use a hash function that computes hash based on the first 100 bytes of the partition key. 如果多个分区键的前 100 个字节相同,则服务会将这些逻辑分区视为同一逻辑分区。If there are multiple partition keys that have the same first 100 bytes, then those logical partitions are considered as the same logical partition by the service. 这可能会导致问题,例如分区大小配额不正确、对不同的分区键应用了唯一索引。This can lead to issues like partition size quota being incorrect, and unique indexes being applied across the partition keys. 为了解决此问题,我们引入了大分区键。Large partition keys are introduced to solve this issue. Azure Cosmos DB 现在支持其值最高为 2 KB 的大分区键。Azure Cosmos DB now supports large partition keys with values up to 2 KB.

可以使用增强版哈希函数来支持大分区键,该增强版可以使用最高为 2 KB 的分区键生成唯一哈希。Large partition keys are supported by using the functionality of an enhanced version of the hash function, which can generate a unique hash from large partition keys up to 2 KB. 也可将该哈希版本建议用于分区键基数高的情况,不管分区键的大小如何。This hash version is also recommended for scenarios with high partition key cardinality irrespective of the size of the partition key. 根据定义,分区键基数是指唯一逻辑分区的数目,例如,某个容器中有大约 30000 个逻辑分区。A partition key cardinality is defined as the number of unique logical partitions, for example in the order of ~30000 logical partitions in a container. 本文介绍如何使用 Azure 门户和不同的 SDK 通过大分区键创建容器。This article describes how to create a container with a large partition key using the Azure portal and different SDKs.

创建大分区键(Azure 门户)Create a large partition key (Azure portal)

若要在使用 Azure 门户创建新容器时创建大分区键,请选中“我的分区键大于 100 字节”选项。To create a large partition key, when you create a new container using the Azure portal, check the My partition key is larger than 100-bytes option. 如果不需要大分区键,或者应用程序在 1.18 之前的 SDK 版本上运行,请取消选中该复选框。Unselect the checkbox if you don't need large partition keys or if you have applications running on SDKs version older than 1.18.

使用 Azure 门户创建大分区键

创建大分区键 (PowerShell)Create a large partition key (PowerShell)

若要创建具有大分区键支持的容器,请参阅To create a container with large partition key support see,

创建大分区键 (.Net SDK)Create a large partition key (.Net SDK)

若要使用 .NET SDK 创建具有大分区键的容器,请指定 PartitionKeyDefinitionVersion.V2 属性。To create a container with a large partition key using the .NET SDK, specify the PartitionKeyDefinitionVersion.V2 property. 以下示例说明如何在 PartitionKeyDefinition 对象中指定 Version 属性,以及如何将其设置为 PartitionKeyDefinitionVersion.V2。The following example shows how to specify the Version property within the PartitionKeyDefinition object and set it to PartitionKeyDefinitionVersion.V2.

await database.CreateContainerAsync(
    new ContainerProperties(collectionName, $"/longpartitionkey")
    {
        PartitionKeyDefinitionVersion = PartitionKeyDefinitionVersion.V2,
    })

支持的 SDK 版本Supported SDK versions

以下 SDK 最低版本支持大分区键:The Large partition keys are supported with the following minimum versions of SDKs:

SDK 类型SDK type 最低版本Minimum version
.Net.Net 1.181.18
Java 同步Java sync 2.4.02.4.0
Java 异步Java Async 2.5.02.5.0
REST APIREST API 使用 x-ms-version 请求标头时版本高于 2017-05-03version higher than 2017-05-03 by using the x-ms-version request header.
Resource Manager 模板Resource Manager template 版本 2(通过使用 partitionKey 对象中的 "version":2 属性)。version 2 by using the "version":2 property within the partitionKey object.

目前不能在 Power BI 和 Azure Logic Apps 中将容器与大分区键配合使用。Currently, you cannot use containers with large partition key within in Power BI and Azure Logic Apps. 在这些应用程序中,可以在没有大分区键的情况下使用容器。You can use containers without a large partition key from these applications.

后续步骤Next steps