Restrições de chaves exclusivas no Azure Cosmos DBUnique key constraints in Azure Cosmos DB

Chaves exclusivas adicionam uma camada de integridade dos dados a um contêiner do Azure Cosmos.Unique keys add a layer of data integrity to an Azure Cosmos container. Você cria uma política de chave exclusiva ao criar um contêiner do Azure Cosmos.You create a unique key policy when you create an Azure Cosmos container. Com chaves exclusivas, você certifica-se de que um ou mais valores em uma partição lógica são exclusivos.With unique keys, you make sure that one or more values within a logical partition is unique. Também é possível garantir exclusividade por chave de partição.You also can guarantee uniqueness per partition key.

Depois de criar um contêiner com uma política de chave exclusiva, a criação de um novo ou uma atualização de um item existente, resultando em uma duplicata dentro de uma partição lógica é impedida, conforme especificado pela restrição de chave exclusiva.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. A chave de partição combinada com a chave exclusiva garante a exclusividade de um item dentro do escopo do contêiner.The partition key combined with the unique key guarantees the uniqueness of an item within the scope of the container.

Por exemplo, considere um contêiner do Azure Cosmos com endereço de email como a restrição de chave exclusiva e CompanyID como a chave de partição.For example, consider an Azure Cosmos container with email address as the unique key constraint and CompanyID as the partition key. Ao configurar o endereço de email do usuário com uma chave exclusiva, cada item terá um endereço de email exclusivo dentro de um determinado CompanyID.When you configure the user's email address with a unique key, each item has a unique email address within a given CompanyID. Não é possível criar dois itens com endereços de e-mail duplicados e com o mesmo valor de chave de partição.Two items can't be created with duplicate email addresses and with the same partition key value.

Para criar itens com o mesmo endereço de email, mas não com o mesmo nome, sobrenome e endereço de email, adicione mais caminhos à política de chave exclusiva.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. Em vez de criar uma chave exclusiva com base no endereço de email apenas, você também pode criar uma chave exclusiva com uma combinação do nome, sobrenome e endereço de email.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. Essa chave é conhecida como uma chave exclusiva composta.This key is known as a composite unique key. Nesse caso, cada combinação exclusiva dos três valores dentro de um determinado CompanyID é permitido.In this case, each unique combination of the three values within a given CompanyID is allowed.

Por exemplo, o contêiner pode conter itens com os valores a seguir, em que cada item respeita a restrição de chave exclusiva.For example, the container can contain items with the following values, where each item honors the unique key constraint.

CompanyIDCompanyID NomeFirst name SobrenomeLast name Endereço de emailEmail 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
FabrikamFabrkam DuperreDuperre gaby@fabraikam.com
FabrikamFabrkam gaby@fabraikam.com

Se você tentar inserir outro item com as combinações listadas na tabela anterior, um erro será exibido.If you attempt to insert another item with the combinations listed in the previous table, you receive an error. O erro indica que a restrição de chave exclusiva não foi atendida.The error indicates that the unique key constraint wasn't met. Recebê-las Resource with specified ID or name already exists ou Resource with specified ID, name, or unique index already exists como uma mensagem de retorno.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.

Definir uma chave exclusivaDefine a unique key

É possível definir chaves exclusivas somente ao criar um contêiner do Azure Cosmos.You can define unique keys only when you create an Azure Cosmos container. Uma chave exclusiva é definida para uma partição lógica.A unique key is scoped to a logical partition. No exemplo anterior, se particionar o contêiner com base no CEP você acabará com itens duplicados em cada partição lógica.In the previous example, if you partition the container based on the ZIP code, you end up with duplicated items in each logical partition. Considere as seguintes propriedades ao criar chaves exclusivas:Consider the following properties when you create unique keys:

  • Não é possível atualizar um contêiner existente para usar uma chave exclusiva diferente.You can't update an existing container to use a different unique key. Isso significa que, após criar um contêiner com uma política de chave exclusiva, a política não poderá ser alterada.In other words, after a container is created with a unique key policy, the policy can't be changed.

  • Para definir uma chave exclusiva para um contêiner existente, crie um novo contêiner com a restrição de chave exclusiva.To set a unique key for an existing container, create a new container with the unique key constraint. Use a ferramenta de migração de dados apropriada para mover os dados do contêiner existente para o novo contêiner.Use the appropriate data migration tool to move the data from the existing container to the new container. Para contêineres SQL, use a ferramenta de Migração de Dados para mover dados.For SQL containers, use the Data Migration tool to move data. Para contêineres MongoDB, use mongoimport.exe ou mongorestore.exe para mover dados.For MongoDB containers, use mongoimport.exe or mongorestore.exe to move data.

  • Uma política de chave exclusiva pode ter no máximo 16 valores do caminho.A unique key policy can have a maximum of 16 path values. Por exemplo, os valores podem ser /firstName, /lastName, e /address/zipCode.For example, the values can be /firstName, /lastName, and /address/zipCode. Cada política de chave exclusiva pode ter um máximo de 10 restrições ou combinações de chave exclusiva.Each unique key policy can have a maximum of 10 unique key constraints or combinations. Os caminhos combinados para cada restrição de índice exclusivo não devem exceder 60 bytes.The combined paths for each unique index constraint must not exceed 60 bytes. No exemplo anterior, o nome, sobrenome e endereço de email juntos são uma restrição.In the previous example, first name, last name, and email address together are one constraint. Essa restrição usa 3 dentre os 16 caminhos possíveis.This constraint uses 3 out of the 16 possible paths.

  • Quando um contêiner tem uma política de chave exclusiva unidade de solicitação (RU) encargos para criar, atualizar e excluir um item são um pouco maior.When a container has a unique key policy, Request Unit (RU) charges to create, update, and delete an item are slightly higher.

  • Não há suporte para chaves exclusivas esparsas.Sparse unique keys are not supported. Se alguns valores de caminho exclusivos estiverem ausentes, eles serão tratados como valores nulos, que participam da restrição de exclusividade.If some unique path values are missing, they're treated as null values, which take part in the uniqueness constraint. Por esse motivo, pode haver apenas um único item com um valor nulo para atender a essa restrição.For this reason, there can be only a single item with a null value to satisfy this constraint.

  • Nomes exclusivos de chave diferenciam maiúsculas de minúsculas.Unique key names are case-sensitive. Por exemplo, considere um contêiner com a restrição de chave exclusiva definida como /address/zipcode.For example, consider a container with the unique key constraint set to /address/zipcode. Se os dados tiverem um campo chamado ZipCode, do Azure Cosmos DB insere "null" como a chave exclusiva porque zipcode não é o mesmo que ZipCode.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. Devido a essa diferenciação de maiúsculas e minúsculas, todos os outros registros com ZipCode não poderão ser inseridos porque o "null" duplicado violará a restrição de chave exclusiva.Because of this case sensitivity, all other records with ZipCode can't be inserted because the duplicate "null" violates the unique key constraint.

Próximas etapasNext steps