Database and Collection Configuration - Cosmos DB Managing Resources

Syntax

# Create a database
az cosmosdb create \
    --name mycosmosaccount \
    --resource-group myresourcegroup \
    --kind GlobalDocumentDB \
    --locations "East US"=0 "West US"=1 \
    --default-consistency-level Strong \
    --enable-automatic-failover true \
    --key-kind Name \
    --tags costCenter=financing \
    --ip-range-filter 192.168.0.0/24

# Create a collection
az cosmosdb collection create \
    --collection-name mycollection \
    --partition-key-path /myPartitionKey \
    --throughput 400 \
    --max-throughput 10000 \
    --resource-group myresourcegroup \
    --name mycosmosaccount \
    --database-name mydatabase

Example

# Create a database
az cosmosdb create \
    --name mycosmosaccount \
    --resource-group myresourcegroup \
    --kind GlobalDocumentDB \
    --locations "East US"=0 "West US"=1 \
    --default-consistency-level Strong    --enable-automatic-failover true \
    --key-kind Name \
    --tags costCenter=financing \
    --ip-range-filter 192.168.0.0/24

# Create a collection
az cosmosdb collection create \
    --collection-name mycollection \
    --partition-key-path /myPartitionKey \
    --throughput 400 \
    --max-throughput 10000 \
    --resource-group myresourcegroup \
    --name mycosmosaccount \
    --database-name mydatabase

Output

After executing the above commands, the output should look like this:

{
    "autoscaleSettings": null,
    "consistencyPolicy": {
        "defaultConsistencyLevel": "Strong",
        "maxStalenessIntervalInSeconds": null,
        "maxStalenessPrefix": null,
        "userConsistencyPolicy": null
    },
    "databaseAccountOfferType": "Standard",
    "disableKeyBasedMetadataWriteAccess": false,
    "documentEndpoint": "https://mycosmosaccount.documents.azure.com:443/",
    "enableAutomaticFailover": true,
    "enableMultipleWriteLocations": true,
    "failoverPolicies": [
        {
            "id": "East US",
            "locationName": "East US",
            "failoverPriority": 0
        },
        {
            "id": "West US",
            "locationName": "West US",
            "failoverPriority": 1
        }
    ],
    "id": "/subscriptions/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myresourcegroup/providers/Microsoft.DocumentDB/databaseAccounts/mycosmosaccount",
    "identity": null,
    "ipRangeFilter": "192.168.0.0/24",
    "isVirtualNetworkFilterEnabled": null,
    "keyVaultKeyUri": null,
    "kind": "GlobalDocumentDB",
    "locations": [
        {
            "documentEndpoint": "https://mycosmosaccount-northcentralus.documents.azure.com:443/",
            "failoverPriority": 0,
            "id": "North Central US",
            "locationName": "North Central US",
            "provisioningState": "Succeeded",
            "replicaCount": 4
        },
        {
            "documentEndpoint": "https://mycosmosaccount-southeastasia.documents.azure.com:443/",
            "failoverPriority": 1,
            "id": "Southeast Asia",
            "locationName": "Southeast Asia",
            "provisioningState": "Succeeded",
            "replicaCount": 4
        }
    ],
    "name": "mycosmosaccount",
    "privateEndpointConnections": [],
    "provisioningState": "Succeeded",
    "publicNetworkAccess": "Enabled",
    "readLocations": [
        {
            "documentEndpoint": "https://mycosmosaccount-northcentralus.documents.azure.com:443/",
            "failoverPriority": 0,
            "id": "North Central US",
            "locationName": "North Central US",
            "provisioningState": "Succeeded",
            "replicaCount": 4
        },
        {
            "documentEndpoint": "https://mycosmosaccount-southeastasia.documents.azure.com:443/",
            "failoverPriority": 1,
            "id": "Southeast Asia",
            "locationName": "Southeast Asia",
            "provisioningState": "Succeeded",
            "replicaCount": 4
        }
    ],
    "tags": {
        "costCenter": "financing"
    },
    "type": "Microsoft.DocumentDB/databaseAccounts",
    "virtualNetworkRules": []
}

{
    "analyticalStorageTtl": null,
    "changeFeedPolicy": null,
    "conflictResolutionPolicy": null,
    "defaultTtl": null,
    "etag": "\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "indexingPolicy": {
        "automatic": true,
        "excludedPaths": [],
        "includedPaths": [
            {
                "indexes": [
                    {
                        "dataType": "String",
                        "kind": "Range",
                        "precision": -1
                    },
                    {
                        "dataType": "Number",
                        "kind": "Range",
                        "precision": -1
                    },
                    {
                        "dataType": "Point",
                        "kind": "Spatial",
                        "precision": -1
                    }
                ],
                "path": "/*"
            }
        ],
        "compositeIndexes": [],
        "spatialIndexes": []
    },
    "location": "North Central US",
    "maxIntervalInSeconds": null,
    "maxStalenessPrefix": null,
    "maxThroughput": 10000,
    "offerThroughput": 400,
    "partitionKey": {
        "kind": "Hash",
        "paths": [
            "/myPartitionKey"
        ],
        "version": 2
    },
    "resource": "dbs/mydatabase/colls/mycollection",
    "resourceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "rid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "throughput": "400",
    "type": "Microsoft.DocumentDB/databaseAccounts/apis/databases/collections",
    "uniqueKeyPolicy": {
        "uniqueKeys": []
    }
}

Explanation

Cosmos DB is a globally distributed, multi-model database service. It allows developers to work with NoSQL data through a variety of APIs and data models, including document, key-value, graph, and column-family

Database Configuration

Before you can create collections which store documents in Cosmos DB, you need to create a database.

az cosmosdb create

This command is used to create a new Cosmos DB account.

• --name: Specifies the name of the new Cosmos DB account.
• --resource-group: Specifies the name of the existing resource group under which the new Cosmos DB account will be created.
• --kind: Specifies which API you will be using to interact with Cosmos DB. In this case, we use the GlobalDocumentDB API, which is used for the document data model.
• --locations: Specifies the regions where the account will be available. In this case, we set it up to be available in East US and West US.
• --default-consistency-level: Specifies the default consistency level for any collections created in the account.
• --enable-automatic-failover: Enables automatic failover to ensure high availability. Must be set to true.
• --key-kind: Specifies the type of access keys to be generated for the Cosmos DB account.
• --tags: Specifies tags for the Cosmos DB account.
• --ip-range-filter: Specifies IP range filters for the Cosmos DB account.

Collection Configuration

After you have created your database, you can then create collections. Collections store documents that use the JSON format and are the equivalent of tables in a relational database.

az cosmosdb collection create

This command is used to create a new collection within a particular database.

• --collection-name: Specifies the name of the new collection.
• --partition-key-path: Specifies the partition key of the new collection. This is required for all Cosmos DB collections and allows for efficient horizontal scaling.
• --throughput: Specifies the throughput capacity in request units per second (RUs/s) for the new collection. This determines the amount of resources that are available for indexing, querying, and serving data to clients.
• --resource-group: Specifies the name of the existing resource group where the Cosmos DB account is located.
• --name: Specifies the name of the Cosmos DB account.
• --database-name: Specifies the name of the database to add the new collection to.

Use

In order to use Cosmos DB, you first need to create a database account. From there, you can create a database and start creating collections within that database.

Important Points

• Cosmos DB is a globally distributed, multi-model database service.
• Before you can create collections, you need to create a database.
• Collections are the equivalent of tables in a relational database.
• Partitions are required for all Cosmos DB collections and allow for efficient horizontal scaling.
• Throughput capacity determines the amount of resources available for indexing, querying, and serving data to clients.

Summary

In summary, this page covered how to create a database account, including creating a database and collections. We also discussed the different options available when creating a Cosmos DB account, and emphasized the importance of partition keys and throughput capacity when creating collections.