LLI Wiki — My Digital Knowledge Base

Cosmos DB: first steps with az CLI, PowerShell, the emulator and backups

Create account, database and container, insert and query items, indexing basics, the local emulator and periodic vs continuous backups.

After the theory, my first practical steps: create an account, a database and a container from the command line, insert and query items, look at the indexing policy, run the emulator locally and understand backups. I only kept commands and parameters I found in Microsoft documentation. Generic names: rg-cosmos-dev, cosmos-contoso-dev, AppDb, orders.

Create the account, database and container with az CLI

az group create --name rg-cosmos-dev --location westeurope

az cosmosdb create --name cosmos-contoso-dev --resource-group rg-cosmos-dev `
  --default-consistency-level Session `
  --locations regionName=westeurope failoverPriority=0 isZoneRedundant=False

az cosmosdb sql database create --account-name cosmos-contoso-dev `
  --resource-group rg-cosmos-dev --name AppDb

az cosmosdb sql container create --account-name cosmos-contoso-dev `
  --resource-group rg-cosmos-dev --database-name AppDb --name orders `
  --partition-key-path "/customerId" --throughput 400

The account name must be lowercase and under 44 characters. For autoscale, replace --throughput with --max-throughput (the CLI reference states a minimum value of 4000). For serverless, create the account with --capabilities EnableServerless and pass no throughput to the container.

The same with PowerShell (Az.CosmosDB)

$loc = New-AzCosmosDBLocationObject -LocationName "West Europe" -FailoverPriority 0 -IsZoneRedundant 0

$account = New-AzCosmosDBAccount -ResourceGroupName "rg-cosmos-dev" `
  -LocationObject $loc -Name "cosmos-contoso-dev" -ApiKind "Sql" `
  -DefaultConsistencyLevel "Session" -EnableAutomaticFailover:$true

$db = New-AzCosmosDBSqlDatabase -ParentObject $account -Name "AppDb"

New-AzCosmosDBSqlContainer -ParentObject $db -Name "orders" `
  -PartitionKeyKind Hash -PartitionKeyPath "/customerId" -Throughput 400

New-AzCosmosDBSqlContainer also accepts -AutoscaleMaxThroughput instead of -Throughput.

Insert and query items

The az CLI manages resources (control plane), not items. For data use the portal's Data Explorer, an SDK, or Cosmos DB Shell. An example with the Python SDK:

from azure.cosmos import CosmosClient

client = CosmosClient(endpoint, credential)  # endpoint + key, or Entra identity
container = client.get_database_client("AppDb").get_container_client("orders")

container.create_item({"id": "o-1001", "customerId": "C42", "status": "paid", "total": 129.9})

# Point read: id + partition key, the cheapest (about 1 RU for 1 KB)
item = container.read_item(item="o-1001", partition_key="C42")

# Query: NoSQL SQL syntax, "c" is the container alias
rows = list(container.query_items(
    query="SELECT c.id, c.total FROM c WHERE c.customerId = @cid AND c.status = @st",
    parameters=[{"name": "@cid", "value": "C42"}, {"name": "@st", "value": "paid"}]))

What I take away:

Indexing policy basics

By default a container is in consistent mode and indexes every property (/*), which is convenient in development but costs RUs on every write. You can exclude paths or add composite indexes:

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [ { "path": "/*" } ],
  "excludedPaths": [ { "path": "/notes/?" }, { "path": "/\"_etag\"/?" } ],
  "compositeIndexes": [
    [ { "path": "/customerId", "order": "ascending" },
      { "path": "/total", "order": "descending" } ]
  ]
}

Apply it at creation with --idx @policy.json (or with az cosmosdb sql container update --idx). Production reflex: index only properties that are actually filtered or sorted on.

The local emulator

To develop without a subscription there is an emulator. The Linux "vNext" version runs in Docker:

docker run --detach --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 \
  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

Backups: periodic or continuous

Periodic (default) Continuous
Principle Full backup every 4 h, 2 copies kept by default Point-in-time restore
Settings Interval (minimum 1 h) and retention (up to a month) Tiers Continuous7Days, Continuous30Days, Continuous35Days
Restore Support request, into a new account Self-service (portal, PowerShell, CLI)

Continuous backup is chosen at creation and can't be switched back to periodic; you can migrate from periodic to continuous. It requires a single-write-region account, on the NoSQL or MongoDB API (or Table/Gremlin).

az cosmosdb create --name cosmos-contoso-dev --resource-group rg-cosmos-dev \
  --backup-policy-type Continuous --continuous-tier "Continuous7Days" \
  --default-consistency-level Session --locations regionName="West Europe"
New-AzCosmosDBAccount -ResourceGroupName "rg-cosmos-dev" -Location "West Europe" `
  -BackupPolicyType Continuous -ContinuousTier Continuous7Days `
  -Name "cosmos-contoso-dev" -ApiKind "Sql"

To audit the backup mode of all accounts, an Azure Resource Graph query on microsoft.documentdb/databaseaccounts and properties.backupPolicy.type is enough.

Lessons learned

Further reading

Mastodon LLIMastodon SocialFosstodon