AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

azure-cosmos-rust

Azure Cosmos DB library for Rust (NoSQL API). Document CRUD, containers, and globally distributed data. Triggers: "cosmos db rust", "CosmosClient rust", "document crud rust", "NoSQL rust", "partition key rust".

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read microsoft--azure-cosmos-rust at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 1

SKILL.md

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

| Client | Purpose | Access | | ----------------- | ------------------------- | ----------------------------------------------- | | CosmosClient | Account-level operations | CosmosClient::builder().build(account).await? | | DatabaseClient | Database operations | client.database_client("db") | | ContainerClient | Container/item operations | database.container_client("c").await |

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:

| Role | Access | | ------------------------------------- | ---------- | | Cosmos DB Built-in Data Reader | Read-only | | Cosmos DB Built-in Data Contributor | Read/write |

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

| Resource | Link | | ------------- | ---------------------------------------------------------------------------------- | | API Reference | https://docs.rs/azure_data_cosmos/latest/azure_data_cosmos | | crates.io | https://crates.io/crates/azure_data_cosmos | | Source Code | https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos |