Azure Cosmos DB

Expert guidance for globally distributed NoSQL database on Azure.

Create Account

# Create Cosmos DB account
az cosmosdb create \
  --name mycosmosdb \
  --resource-group myResourceGroup \
  --default-consistency-level Session \
  --locations regionName=eastus failoverPriority=0 \
  --locations regionName=westus failoverPriority=1 \
  --enable-automatic-failover true

# Create database
az cosmosdb sql database create \
  --account-name mycosmosdb \
  --resource-group myResourceGroup \
  --name mydb

# Create container
az cosmosdb sql container create \
  --account-name mycosmosdb \
  --resource-group myResourceGroup \
  --database-name mydb \
  --name items \
  --partition-key-path "/partitionKey" \
  --throughput 400

Python SDK

Connection

from azure.cosmos import CosmosClient, PartitionKey
from azure.identity import DefaultAzureCredential

# Connection string
client = CosmosClient.from_connection_string(conn_str)

# Or with Managed Identity
credential = DefaultAzureCredential()
client = CosmosClient(url=endpoint, credential=credential)

# Get database and container
database = client.get_database_client("mydb")
container = database.get_container_client("items")

CRUD Operations

# Create item
item = {
    "id": "item-1",
    "partitionKey": "category-1",
    "name": "Product A",
    "price": 99.99,
    "tags": ["electronics", "sale"]
}
container.create_item(body=item)

# Read item
item = container.read_item(item="item-1", partition_key="category-1")

# Update item (replace)
item["price"] = 89.99
container.replace_item(item="item-1", body=item)

# Upsert item
container.upsert_item(body=item)

# Delete item
container.delete_item(item="item-1", partition_key="category-1")

Queries

# Simple query
query = "SELECT * FROM c WHERE c.price > 50"
items = list(container.query_items(
    query=query,
    enable_cross_partition_query=True
))

# Parameterized query
query = "SELECT * FROM c WHERE c.category = @category AND c.price < @maxPrice"
parameters = [
    {"name": "@category", "value": "electronics"},
    {"name": "@maxPrice", "value": 100}
]
items = list(container.query_items(
    query=query,
    parameters=parameters,
    enable_cross_partition_query=True
))

# Query with partition key (more efficient)
items = list(container.query_items(
    query="SELECT * FROM c WHERE c.price > 50",
    partition_key="category-1"
))

# Aggregate query
query = "SELECT VALUE COUNT(1) FROM c WHERE c.category = @category"
count = list(container.query_items(query=query, parameters=[{"name": "@category", "value": "electronics"}]))[0]

Bulk Operations

from azure.cosmos import exceptions

# Bulk create
items_to_create = [
    {"id": f"item-{i}", "partitionKey": "bulk", "value": i}
    for i in range(100)
]

for item in items_to_create:
    try:
        container.create_item(body=item)
    except exceptions.CosmosResourceExistsError:
        pass  # Item already exists

Change Feed

# Read change feed
change_feed = container.query_items_change_feed(
    is_start_from_beginning=True,
    partition_key="category-1"
)

for change in change_feed:
    print(f"Changed item: {change['id']}")

# Continue from continuation token
continuation_token = change_feed.continuation_token
change_feed = container.query_items_change_feed(
    continuation=continuation_token,
    partition_key="category-1"
)

.NET SDK

using Microsoft.Azure.Cosmos;

// Create client
CosmosClient client = new CosmosClient(connectionString);
Database database = await client.CreateDatabaseIfNotExistsAsync("mydb");
Container container = await database.CreateContainerIfNotExistsAsync(
    "items",
    "/partitionKey",
    throughput: 400
);

// Create item
var item = new { id = "item-1", partitionKey = "cat-1", name = "Product" };
await container.CreateItemAsync(item, new PartitionKey("cat-1"));

// Read item
var response = await container.ReadItemAsync<dynamic>(
    "item-1",
    new PartitionKey("cat-1")
);

// Query
var query = new QueryDefinition("SELECT * FROM c WHERE c.price > @price")
    .WithParameter("@price", 50);

using FeedIterator<dynamic> iterator = container.GetItemQueryIterator<dynamic>(query);
while (iterator.HasMoreResults)
{
    FeedResponse<dynamic> response = await iterator.ReadNextAsync();
    foreach (var item in response)
    {
        Console.WriteLine(item);
    }
}

Consistency Levels

# Set default consistency
az cosmosdb update \
  --name mycosmosdb \
  --resource-group myResourceGroup \
  --default-consistency-level BoundedStaleness \
  --max-staleness-prefix 100000 \
  --max-interval 5

Level	Description
Strong	Linearizable reads, global order
Bounded Staleness	Reads lag by K versions or T time
Session	Read your own writes (default)
Consistent Prefix	Reads never see out-of-order writes
Eventual	No ordering guarantee

Indexing Policy

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/name/?",
      "indexes": [
        { "kind": "Range", "dataType": "String" }
      ]
    },
    {
      "path": "/price/?",
      "indexes": [
        { "kind": "Range", "dataType": "Number" }
      ]
    }
  ],
  "excludedPaths": [
    { "path": "/description/*" },
    { "path": "/_etag/?" }
  ],
  "compositeIndexes": [
    [
      { "path": "/category", "order": "ascending" },
      { "path": "/price", "order": "descending" }
    ]
  ],
  "spatialIndexes": [
    {
      "path": "/location/*",
      "types": ["Point", "Polygon"]
    }
  ]
}

Stored Procedures

// Stored procedure
function bulkDelete(query) {
    var collection = getContext().getCollection();
    var response = getContext().getResponse();
    var deleted = 0;

    var accepted = collection.queryDocuments(
        collection.getSelfLink(),
        query,
        function(err, documents) {
            if (err) throw err;

            for (var i = 0; i < documents.length; i++) {
                var accepted = collection.deleteDocument(
                    documents[i]._self,
                    function(err) {
                        if (err) throw err;
                        deleted++;
                    }
                );
                if (!accepted) break;
            }

            response.setBody({ deleted: deleted });
        }
    );
}

Bicep Deployment

resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
  name: accountName
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    locations: [
      {
        locationName: location
        failoverPriority: 0
        isZoneRedundant: true
      }
    ]
    databaseAccountOfferType: 'Standard'
    enableAutomaticFailover: true
    capabilities: [
      { name: 'EnableServerless' }
    ]
  }
}

resource database 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2023-04-15' = {
  parent: cosmosAccount
  name: databaseName
  properties: {
    resource: {
      id: databaseName
    }
  }
}

resource container 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2023-04-15' = {
  parent: database
  name: containerName
  properties: {
    resource: {
      id: containerName
      partitionKey: {
        paths: ['/partitionKey']
        kind: 'Hash'
      }
      indexingPolicy: {
        indexingMode: 'consistent'
        includedPaths: [{ path: '/*' }]
        excludedPaths: [{ path: '/_etag/?' }]
      }
    }
  }
}

Resources

• Azure Cosmos DB Documentation
• Cosmos DB Python SDK
• Best Practices