Restrições de chaves exclusivas no Azure Cosmos DB

APLICA-SE A: NoSQL

Chaves exclusivas adicionam uma camada de integridade dos 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ê certifica-se de que um ou mais valores em uma partição lógica são exclusivos. Também é possível garantir exclusividade por chave de partição.

Após criar um contêiner com uma política de chave exclusiva, a criação de um novo item ou uma atualização de um existente que resulte em duplicação em uma partição lógica será impedida, 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. 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. 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 para NoSQL do Azure Cosmos DB, 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 e minúsculas para essa propriedade. Por exemplo, se você tiver uma chave exclusiva definida na propriedade Name, "Gaby" será diferente de "gaby" e você poderá inserir ambos no contêiner.

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. Em vez de criar uma chave exclusiva baseada apenas no endereço de email, também é possível criar uma chave exclusiva com uma combinação do nome, sobrenome e endereço de email. Essa chave é conhecida como uma chave exclusiva composta. Nesse caso, cada combinação exclusiva dos três valores dentro de um determinado CompanyID é permitido.

Por exemplo, o contêiner pode conter itens com os valores a seguir, em que cada item respeita a restrição de chave exclusiva.

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

Definir uma chave exclusiva

É possível definir chaves exclusivas somente ao criar um contêiner do Azure Cosmos DB. Uma chave exclusiva é definida para uma partição lógica. No exemplo anterior, se particionar o contêiner com base no código postal, você 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. Isso significa que, após criar um contêiner com uma política de chave exclusiva, a política não poderá 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 os 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 do caminho. Por exemplo, os valores podem ser /firstName, /lastName e /address/zipCode. Cada política de chave exclusiva pode ter um máximo de 10 restrições ou combinações de chave exclusiva. No exemplo anterior, o nome, sobrenome e endereço de email juntos são uma restrição. Essa restrição usa 3 dentre os 16 caminhos possíveis.

• Quando um contêiner tiver uma política de chave exclusiva, os encargos de RU (Unidade de Solicitação) para criar, atualizar e excluir um item serão ligeiramente mais elevados.

• Não há suporte para chaves exclusivas esparsas. Se alguns valores de caminho exclusivos estiverem ausentes, 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 atender a essa restrição.

• Nomes exclusivos de chave diferenciam maiúsculas de minúsculas. Por exemplo, considere um contêiner com a restrição de chave exclusiva definida como /address/zipcode. Se os dados tiverem um campo nomeado ZipCode, o Azure Cosmos DB irá inserir "null" como a chave exclusiva porque zipcode não é o mesmo que 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.

Próximas etapas

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