Azure Cosmos DB の一意キー制約Unique key constraints in Azure Cosmos DB

一意キーを使用すると、Azure Cosmos コンテナーにデータ整合性のレイヤーが追加されます。Unique keys add a layer of data integrity to an Azure Cosmos container. 一意キー ポリシーは、Azure Cosmos コンテナーを作成するときに作成します。You create a unique key policy when you create an Azure Cosmos container. 一意キーを使用して、論理パーティション内にある 1 つ以上の値が一意であることを保証します。With unique keys, you make sure that one or more values within a logical partition is unique. また、パーティション キーごとの一意性を保証することもできます。You also can guarantee uniqueness per partition key.

一意キー ポリシーを使用してコンテナーを作成した後は、論理パーティション内に新しく項目を作成したり既存の項目を更新したりして重複項目を作成することは、一意キー制約で指定されているためできなくなります。After you create a container with a unique key policy, the creation of a new or an update of an existing item resulting in a duplicate within a logical partition is prevented, as specified by the unique key constraint. パーティション キーと一意キーを組み合わせることで、コンテナーのスコープ内にある項目の一意性が確保されます。The partition key combined with the unique key guarantees the uniqueness of an item within the scope of the container.

たとえば、メール アドレスを一意キー制約にし、CompanyID をパーティション キーにして、Azure Cosmos コンテナーを作成するものとします。For example, consider an Azure Cosmos container with email address as the unique key constraint and CompanyID as the partition key. ユーザーのメール アドレスを一意キーとして構成すると、各項目は特定の CompanyID 内で一意のメール アドレスを持つようになります。When you configure the user's email address with a unique key, each item has a unique email address within a given CompanyID. 重複する電子メール アドレスを同じパーティション キー値と組み合わせて、2 つの項目を作成することはできません。Two items can't be created with duplicate email addresses and with the same partition key value.

メール アドレスは同じでも、姓と名とメール アドレスは異なる項目を作成するには、一意キー ポリシーにさらにパスを追加します。To create items with the same email address, but not the same first name, last name, and email address, add more paths to the unique key policy. つまり、メール アドレスだけに基づいて一意なキーを作成するのではなく、姓、名、メール アドレスの組み合わせを使用して、一意キーを作成することもできます。Instead of creating a unique key based on the email address only, you also can create a unique key with a combination of the first name, last name, and email address. このキーは、複合一意キーと呼ばれます。This key is known as a composite unique key. その場合、指定した CompanyID 内では、3 つの値の一意な組み合わせだけが使用できるようになります。In this case, each unique combination of the three values within a given CompanyID is allowed.

たとえば、コンテナーには次の値を使った項目を含めることができます。これらの各項目は、一意キー制約に従っています。For example, the container can contain items with the following values, where each item honors the unique key constraint.

CompanyIDCompanyID First name Last name 電子メール アドレスEmail address
ContosoContoso GabyGaby DuperreDuperre gaby@contoso.com
ContosoContoso GabyGaby DuperreDuperre gaby@fabrikam.com
FabrikamFabrikam GabyGaby DuperreDuperre gaby@fabrikam.com
FabrikamFabrikam IvanIvan DuperreDuperre gaby@fabrikam.com
FabrkamFabrkam DuperreDuperre gaby@fabraikam.com
FabrkamFabrkam gaby@fabraikam.com

上の表で示されている値の組み合わせで別の項目を挿入しようとすると、エラーが発生します。If you attempt to insert another item with the combinations listed in the previous table, you receive an error. そのエラーでは、一意キー制約を満たしていないことが示されます。The error indicates that the unique key constraint wasn't met. Resource with specified ID or name already existsResource with specified ID, name, or unique index already exists のどちらかのメッセージが返されます。You receive either Resource with specified ID or name already exists or Resource with specified ID, name, or unique index already exists as a return message.

一意キーを定義するDefine a unique key

一意キーは、Azure Cosmos コンテナーの作成時にのみ定義できます。You can define unique keys only when you create an Azure Cosmos container. 一意キーは論理パーティションに対してスコープ指定されます。A unique key is scoped to a logical partition. 上の例では、郵便番号に基づいてコンテナーをパーティション分割すると、各論理パーティションに重複する項目が存在するようになります。In the previous example, if you partition the container based on the ZIP code, you end up with duplicated items in each logical partition. 一意キーを作成するときは、次の特性を考慮してください。Consider the following properties when you create unique keys:

  • 異なる一意キーを使用するように、既存のコンテナーを更新することはできません。You can't update an existing container to use a different unique key. つまり、一意キー ポリシーを指定してコンテナーを作成した後で、ポリシーを変更することはできません。In other words, after a container is created with a unique key policy, the policy can't be changed.

  • 既存のコンテナーに対して一意キーを設定するには、一意キー制約を持つ新しいコンテナーを作成します。To set a unique key for an existing container, create a new container with the unique key constraint. 適切なデータ移行ツールを使用して、既存のコンテナーから新しいコンテナーにデータを移動します。Use the appropriate data migration tool to move the data from the existing container to the new container. SQL コンテナーの場合は、データ移行ツールを使用してデータを移動します。For SQL containers, use the Data Migration tool to move data. MongoDB コンテナーの場合は、mongoimport.exe または mongorestore.exe を使用してデータを移動します。For MongoDB containers, use mongoimport.exe or mongorestore.exe to move data.

  • 一意キー ポリシーでは、最大で 16 個のパス値を使用できます。A unique key policy can have a maximum of 16 path values. たとえば、/firstName/lastName/address/zipCode を値として使用できます。For example, the values can be /firstName, /lastName, and /address/zipCode. 一意キー ポリシーには、それぞれ最大 10 個の一意キー制約または一意なキーの組み合わせを含めることができます。Each unique key policy can have a maximum of 10 unique key constraints or combinations. 一意インデックス制約ごとの結合されたパスの長さは、60 バイトを超えないようにする必要があります。The combined paths for each unique index constraint must not exceed 60 bytes. 上の例では、姓、名、メール アドレスの組み合わせで 1 つの制約になっています。In the previous example, first name, last name, and email address together are one constraint. この制約では、可能な 16 個のパスのうち 3 個が使用されています。This constraint uses 3 out of the 16 possible paths.

  • コンテナーに一意キー ポリシーがある場合、項目を作成、更新、削除するための要求ユニット (RU) 料金が若干高くなります。When a container has a unique key policy, Request Unit (RU) charges to create, update, and delete an item are slightly higher.

  • スパースな一意キーはサポートされていません。Sparse unique keys are not supported. 一部の一意パスの値がない場合、それらは null 値として扱われて、一意性制約に組み込まれます。If some unique path values are missing, they're treated as null values, which take part in the uniqueness constraint. そのため、この制約を満たすには、null 値を持つことができる項目は 1 つだけです。For this reason, there can be only a single item with a null value to satisfy this constraint.

  • 一意キー名では大文字と小文字が区別されます。Unique key names are case-sensitive. たとえば、あるコンテナーの一意キー制約が /address/zipcode に設定されているとします。For example, consider a container with the unique key constraint set to /address/zipcode. データに ZipCode という名前のフィールドがあると、zipcodeZipCode は同じではないため、一意キーとして "null" が挿入されます。If your data has a field named ZipCode, Azure Cosmos DB inserts "null" as the unique key because zipcode isn't the same as ZipCode. このように大文字と小文字が区別されることにより、ZipCode を含む他のすべてのレコードは、重複する "null" が一意キー制約に違反するため、挿入できません。Because of this case sensitivity, all other records with ZipCode can't be inserted because the duplicate "null" violates the unique key constraint.

次の手順Next steps