Azure Cosmos Rust

Azure Cosmos DB library for Rust

Client library for Azure Cosmos DB NoSQL API — document CRUD, containers, and globally distributed data.

Use this skill when:

• An app needs to store or query documents in Cosmos DB from Rust
• You need CRUD operations on items with partition keys
• You need key-based auth as an alternative to Entra ID

IMPORTANT: Only use the official azure_data_cosmos crate published by the azure-sdk crates.io user. Do NOT use the unofficial azure_cosmos or azure_sdk_for_rust community crates. Official crates use underscores in names and none have version 0.21.0.

Installation

cargo add azure_data_cosmos azure_identity serde serde_json tokio

If your code uses azure_core types directly (for example, azure_core::credentials::TokenCredential), add azure_core to Cargo.toml. If you only use azure_data_cosmos re-exports, direct azure_core dependency is optional.

Environment Variables

COSMOS_ENDPOINT=https://<account>.documents.azure.com/ # Required for all operations

Authentication

Rust Azure SDK code must not use DefaultAzureCredential. The Rust identity crate does not provide that type.

use azure_identity::DeveloperToolsCredential;use azure_data_cosmos::{    CosmosClient, AccountReference, AccountEndpoint, RoutingStrategy,};
#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> {    // Local dev: DeveloperToolsCredential. Production: use ManagedIdentityCredential.    let credential = DeveloperToolsCredential::new(None)?;    let endpoint: AccountEndpoint = "https://<account>.documents.azure.com/"        .parse()?;    let account = AccountReference::with_credential(endpoint, credential);    let client = CosmosClient::builder()        .build(account, RoutingStrategy::ProximityTo("East US".into()))        .await?;    Ok(())}

Prefer the crate README/examples when checking builder signatures and CRUD method shapes instead of reconstructing APIs from memory or generated internals.

Client Hierarchy

Core Workflow

use serde::{Serialize, Deserialize};use azure_data_cosmos::CosmosClient;
#[derive(Serialize, Deserialize)]struct Item {    pub id: String,    pub partition_key: String,    pub value: String,}
async fn crud(client: CosmosClient) -> Result<(), Box<dyn std::error::Error>> {    let container = client        .database_client("myDatabase")        .container_client("myContainer")        .await;
    let item = Item {        id: "1".into(),        partition_key: "pk1".into(),        value: "hello".into(),    };
    // Create    container.create_item("pk1", "1", item, None).await?;
    // Read    let resp = container.read_item("pk1", "1", None).await?;    let mut item: Item = resp.into_model()?;
    // Update    item.value = "updated".into();    container.replace_item("pk1", "1", item, None).await?;
    // Delete    container.delete_item("pk1", "1", None).await?;    Ok(())}

Patch Item

use azure_data_cosmos::{PatchInstructions, PatchOperation};
let patch = PatchInstructions::from(vec![    PatchOperation::set("/value", serde_json::json!("patched")),]);let patched: Item = container    .patch_item("pk1", "1", patch, None)    .await?    .into_model()?;println!("Patched value: {}", patched.value);

Key Auth (Optional)

Enable account key authentication with the feature flag:

cargo add azure_data_cosmos --features key_auth

RBAC Roles

For Entra ID auth, assign one of these built-in Cosmos DB roles:

Best Practices

1. Use cargo add to manage dependencies, never edit Cargo.toml directly. Add and remove Rust SDK dependencies with cargo commands instead of manual manifest edits.
2. Add azure_core only when importing azure_core types directly. If your code imports azure_core::http::Url, azure_core::http::RequestContent, or azure_core::error::ErrorKind, include azure_core; otherwise a direct dependency is optional.
3. Use DeveloperToolsCredential for local dev, ManagedIdentityCredential for production — Rust does not provide a single DefaultAzureCredential type
4. Never hardcode credentials — use environment variables or managed identity
5. Reuse CosmosClient — clients are thread-safe; create once, share across tasks
6. Use RoutingStrategy::ProximityTo — route to the nearest region for lowest latency
7. Always specify partition key for item operations — Cosmos DB requires it for all CRUD
8. Run cargo clippy -- -D warnings when the prompt, eval, or CI expects lint-clean output
9. Future-proof #[non_exhaustive] SDK models — when constructing SDK model/options structs, end the initializer with ..Default::default() (add #[allow(clippy::needless_update)]) and use a _ wildcard arm when matching SDK enums, so new service-added fields/variants don't break your build

Reference Links