Restrições de chave exclusivas no Azure Cosmos DB

APLICA-SE A: NoSQL

As chaves exclusivas adicionam uma camada de integridade de dados a um contêiner do Azure Cosmos DB. Você cria uma política de chave exclusiva ao criar um contêiner do Azure Cosmos DB. Com chaves exclusivas, você garante que um ou mais valores dentro de uma partição lógica sejam exclusivos. Você também pode garantir exclusividade por chave de partição.

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 é evitada, conforme especificado pela restrição de chave exclusiva. A chave de partição combinada com a chave exclusiva garante a exclusividade de um item dentro do escopo do contêiner.

Por exemplo, considere um contêiner do Azure Cosmos DB com Email address como a restrição de chave exclusiva e CompanyID como a chave de partição. Quando você configura o endereço de e-mail do usuário com uma chave exclusiva, cada item tem um endereço de e-mail exclusivo dentro de um determinado 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. Na API do Azure Cosmos DB para NoSQL, os itens são armazenados como valores JSON. Esses valores JSON diferenciam maiúsculas de minúsculas. Ao escolher uma propriedade como uma chave exclusiva, você pode inserir valores que diferenciam maiúsculas de minúsculas para essa propriedade. Por exemplo, se você tiver uma chave exclusiva definida na propriedade name, "Gaby" é diferente de "gaby" e você pode inserir ambos no contêiner.

Para criar itens com o mesmo endereço de e-mail, mas não com o mesmo nome, sobrenome e endereço de email, adicione mais caminhos à política de chave exclusiva. Em vez de criar uma chave exclusiva com base apenas no endereço de e-mail, você também pode criar uma chave exclusiva com uma combinação de nome, sobrenome e endereço de e-mail. Essa chave é conhecida como chave exclusiva composta. Neste caso, cada combinação única dos três valores dentro de um dado CompanyID é permitida.

Por exemplo, o contêiner pode conter itens com os seguintes valores, onde cada item honra a restrição de chave exclusiva.

ID da Empresa	Nome próprio	Apelido	Endereço de e-mail
Contoso	Gaby	Duperre	gaby@contoso.com
Contoso	Gaby	Duperre	gaby@fabrikam.com
Fabrikam	Gaby	Duperre	gaby@fabrikam.com
Fabrikam	Ivan	Duperre	gaby@fabrikam.com
Fabrkam		Duperre	gaby@fabraikam.com
Fabrkam			gaby@fabraikam.com

Se você tentar inserir outro item com as combinações listadas na tabela anterior, receberá um erro. O erro indica que a restrição de chave exclusiva não foi atendida. Você recebe uma ou Resource with specified ID or name already exists Resource with specified ID, name, or unique index already exists como uma mensagem de retorno.

Definir uma chave exclusiva

Você pode definir chaves exclusivas somente quando cria um contêiner do Azure Cosmos DB. Uma chave exclusiva tem como escopo uma partição lógica. No exemplo anterior, se você particionar o contêiner com base no CEP, poderá ter os mesmos itens em cada partição lógica. Considere as seguintes propriedades ao criar chaves exclusivas:

• Não é possível atualizar um contêiner existente para usar uma chave exclusiva diferente. Em outras palavras, depois que um contêiner é criado com uma política de chave exclusiva, a política não pode ser alterada.

• Para definir uma chave exclusiva para um contêiner existente, crie um novo contêiner com a restrição de chave exclusiva. Use a ferramenta de migração de dados apropriada para mover os dados do contêiner existente para o novo contêiner. Para contêineres SQL, use os trabalhos de cópia de contêiner para mover dados. Para contêineres MongoDB, use mongoimport.exe ou mongorestore.exe para mover dados.

• Uma política de chave exclusiva pode ter no máximo 16 valores de caminho. Por exemplo, os valores podem ser /firstName, /lastNamee /address/zipCode. Cada política de chave exclusiva pode ter um máximo de 10 restrições ou combinações de chave exclusivas. No exemplo anterior, nome, sobrenome e endereço de e-mail juntos são uma restrição. Essa restrição usa 3 dos 16 caminhos possíveis.

• Quando um contêiner tem uma política de chave exclusiva, as taxas da Unidade de Solicitação (RU) para criar, atualizar e excluir um item são um pouco maiores.

• Não há suporte para chaves exclusivas esparsas. Se alguns valores de caminho exclusivos estiverem faltando, eles serão tratados como valores nulos, que participam da restrição de exclusividade. Por esse motivo, pode haver apenas um único item com um valor nulo para satisfazer essa restrição.

• Os nomes de chave exclusivos diferenciam maiúsculas de minúsculas. Por exemplo, considere um contêiner com a restrição de chave exclusiva definida como /address/zipcode. Se seus dados tiverem um campo chamado ZipCode, o Azure Cosmos DB insere "null" como a chave exclusiva porque zipcode não é o mesmo que ZipCode. Devido a essa sensibilidade a maiúsculas e minúsculas, todos os outros registros com CEP não podem ser inseridos porque a duplicata "null" viola a restrição de chave exclusiva.

Próximos passos

• Saiba mais sobre partições lógicas
• Explore como definir chaves exclusivas ao criar um contêiner
• Tentando fazer o planejamento de capacidade para uma migração para o Azure Cosmos DB? Você pode usar informações sobre seu cluster de banco de dados existente para planejamento de capacidade.
  • Se tudo o que você sabe é o número de vcores e servidores em seu cluster de banco de dados existente, leia sobre como estimar unidades de solicitação usando vCores ou vCPUs
  • Se você souber as taxas de solicitação típicas para sua carga de trabalho de banco de dados atual, leia sobre como estimar unidades de solicitação usando o planejador de capacidade do Azure Cosmos DB