Skip to content

Latest commit

 

History

History
152 lines (116 loc) · 5.45 KB

how-to-define-unique-keys.md

File metadata and controls

152 lines (116 loc) · 5.45 KB
title description author ms.service ms.subservice ms.topic ms.date ms.author ms.custom
Define unique keys for an Azure Cosmos DB container
Learn how to define unique keys for an Azure Cosmos DB container using Azure portal, PowerShell, .NET, Java, and various other SDKs.
seesharprun
cosmos-db
nosql
how-to
12/02/2019
sidandrews
devx-track-python, devx-track-js, devx-track-csharp, ignite-2022, devx-track-dotnet, devx-track-extended-java

Define unique keys for an Azure Cosmos DB container

[!INCLUDENoSQL]

This article presents the different ways to define unique keys when creating an Azure Cosmos DB container. It's currently possible to perform this operation either by using the Azure portal or through one of the SDKs.

Use the Azure portal

  1. Sign in to the Azure portal.

  2. Create a new Azure Cosmos DB account or select an existing one.

  3. Open the Data Explorer pane and select the container that you want to work on.

  4. Click on New Container.

  5. In the Add Container dialog, click on + Add unique key to add a unique key entry.

  6. Enter the path(s) of the unique key constraint

  7. If needed, add more unique key entries by clicking on + Add unique key

    :::image type="content" source="./media/how-to-define-unique-keys/unique-keys-portal.png" alt-text="Screenshot of unique key constraint entry on Azure portal":::

Use PowerShell

To create a container with unique keys see, Create an Azure Cosmos DB container with unique key and TTL

Use the .NET SDK

.NET SDK V2

When creating a new container using the .NET SDK v2, a UniqueKeyPolicy object can be used to define unique key constraints.

client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("database"), new DocumentCollection
{
    Id = "container",
    PartitionKey = new PartitionKeyDefinition { Paths = new Collection<string>(new List<string> { "/myPartitionKey" }) },
    UniqueKeyPolicy = new UniqueKeyPolicy
    {
        UniqueKeys = new Collection<UniqueKey>(new List<UniqueKey>
        {
            new UniqueKey { Paths = new Collection<string>(new List<string> { "/firstName", "/lastName", "/emailAddress" }) },
            new UniqueKey { Paths = new Collection<string>(new List<string> { "/address/zipCode" }) }
        })
    }
});

.NET SDK V3

When creating a new container using the .NET SDK v3, use the SDK's fluent API to declare unique keys in a concise and readable way.

await client.GetDatabase("database").DefineContainer(name: "container", partitionKeyPath: "/myPartitionKey")
    .WithUniqueKey()
        .Path("/firstName")
        .Path("/lastName")
        .Path("/emailAddress")
    .Attach()
    .WithUniqueKey()
        .Path("/address/zipCode")
    .Attach()
    .CreateIfNotExistsAsync();

Use the Java SDK

When creating a new container using the Java SDK, a UniqueKeyPolicy object can be used to define unique key constraints.

// create a new DocumentCollection object
DocumentCollection container = new DocumentCollection();
container.setId("container");

// create array of strings and populate them with the unique key paths
Collection<String> uniqueKey1Paths = new ArrayList<String>();
uniqueKey1Paths.add("/firstName");
uniqueKey1Paths.add("/lastName");
uniqueKey1Paths.add("/emailAddress");
Collection<String> uniqueKey2Paths = new ArrayList<String>();
uniqueKey2Paths.add("/address/zipCode");

// create UniqueKey objects and set their paths
UniqueKey uniqueKey1 = new UniqueKey();
UniqueKey uniqueKey2 = new UniqueKey();
uniqueKey1.setPaths(uniqueKey1Paths);
uniqueKey2.setPaths(uniqueKey2Paths);

// create a new UniqueKeyPolicy object and set its unique keys
UniqueKeyPolicy uniqueKeyPolicy = new UniqueKeyPolicy();
Collection<UniqueKey> uniqueKeys = new ArrayList<UniqueKey>();
uniqueKeys.add(uniqueKey1);
uniqueKeys.add(uniqueKey2);
uniqueKeyPolicy.setUniqueKeys(uniqueKeys);

// set the unique key policy
container.setUniqueKeyPolicy(uniqueKeyPolicy);

// create the container
client.createCollection(String.format("/dbs/%s", "database"), container, null);

Use the Node.js SDK

When creating a new container using the Node.js SDK, a UniqueKeyPolicy object can be used to define unique key constraints.

client.database('database').containers.create({
    id: 'container',
    uniqueKeyPolicy: {
        uniqueKeys: [
            { paths: ['/firstName', '/lastName', '/emailAddress'] },
            { paths: ['/address/zipCode'] }
        ]
    }
});

Use the Python SDK

When creating a new container using the Python SDK, unique key constraints can be specified as part of the dictionary passed as parameter.

client.CreateContainer('dbs/' + config['DATABASE'], {
    'id': 'container',
    'uniqueKeyPolicy': {
        'uniqueKeys': [
            {'paths': ['/firstName', '/lastName', '/emailAddress']},
            {'paths': ['/address/zipCode']}
        ]
    }
})

Next steps