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:
SELECT ... FROM c WHERE ...looks like SQL but works on JSON documents;SELECT VALUE COUNT(1) FROM ccounts items.- A query filtering on
id+ partition key is not a point read: only the SDK/REST read operation is. - Putting the partition key in the
WHEREavoids cross-partition fan-out. - In the portal, "Query Stats" shows the RU cost.
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
- The endpoint is
http://localhost:8081, Data Explorer is onhttp://localhost:1234, the health probe on port 8080. - The .NET and Java SDKs don't support HTTP mode: start with
--protocol https. - Limits: NoSQL API only, no authentication enforced, RUs aren't implemented, and only DiskANN vector indexes are honored (other indexing policies are accepted but optimize nothing). It doesn't replace a test on a real account for cost and indexing.
- A Windows emulator also exists (provisioned throughput only, no serverless).
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
- Create the account with the right backup mode from day one.
- Pick the partition key before the first container: it can't be changed.
- Account keys are secrets: prefer Microsoft Entra authentication, and never put keys in a versioned script.
- Delete the test resource group to avoid charges.