Compartilhar via

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 a criação de um contêiner com uma política de chave única, a criação de um novo item ou a atualização de um item existente que resulte em uma duplicata dentro de uma partição lógica é impedida, conforme especificado pela restrição de chave única. 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 Nome, Gaby será diferente de gaby e você poderá inserir ambas 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.

CompanyID Nome Sobrenome Endereço de email
Contoso Gaby Duperre gaby@contoso.com
Contoso Gaby Duperre gaby@fabrikam.com
Fabrikam Gaby Duperre gaby@fabrikam.com
Fabrikam Ivan Duperre gaby@fabrikam.com
Fabrikam Duperre gaby@fabraikam.com
Fabrikam gaby@fabraikam.com

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 seus dados tiverem um campo nomeado ZipCode, o Azure Cosmos DB inserirá nulo como chave exclusiva porque zipcode não é o mesmo que ZipCode. Devido à distinção entre maiúsculas e minúsculas, todos os outros registros com ZipCode não podem ser inseridos porque o valor duplicado de null viola a restrição de chave única.

Próximas etapas

  • Last updated on