home / skills / sickn33 / antigravity-awesome-skills / azure-cosmos-rust

azure-cosmos-rust skill

safe

This skill enables Rust developers to perform CRUD, queries, and container operations on Azure Cosmos DB using the Rust SDK.

npx playbooks add skill sickn33/antigravity-awesome-skills --skill azure-cosmos-rust

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.2 KB

---
name: azure-cosmos-rust
description: |
  Azure Cosmos DB SDK for Rust (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.
  Triggers: "cosmos db rust", "CosmosClient rust", "container", "document rust", "NoSQL rust", "partition key".
package: azure_data_cosmos
---

# Azure Cosmos DB SDK for Rust

Client library for Azure Cosmos DB NoSQL API — globally distributed, multi-model database.

## Installation

```sh
cargo add azure_data_cosmos azure_identity
```

## Environment Variables

```bash
COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/
COSMOS_DATABASE=mydb
COSMOS_CONTAINER=mycontainer
```

## Authentication

```rust
use azure_identity::DeveloperToolsCredential;
use azure_data_cosmos::CosmosClient;

let credential = DeveloperToolsCredential::new(None)?;
let client = CosmosClient::new(
    "https://<account>.documents.azure.com:443/",
    credential.clone(),
    None,
)?;
```

## Client Hierarchy

| Client | Purpose | Get From |
|--------|---------|----------|
| `CosmosClient` | Account-level operations | Direct instantiation |
| `DatabaseClient` | Database operations | `client.database_client()` |
| `ContainerClient` | Container/item operations | `database.container_client()` |

## Core Workflow

### Get Database and Container Clients

```rust
let database = client.database_client("myDatabase");
let container = database.container_client("myContainer");
```

### Create Item

```rust
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct Item {
    pub id: String,
    pub partition_key: String,
    pub value: String,
}

let item = Item {
    id: "1".into(),
    partition_key: "partition1".into(),
    value: "hello".into(),
};

container.create_item("partition1", item, None).await?;
```

### Read Item

```rust
let response = container.read_item("partition1", "1", None).await?;
let item: Item = response.into_model()?;
```

### Replace Item

```rust
let mut item: Item = container.read_item("partition1", "1", None).await?.into_model()?;
item.value = "updated".into();

container.replace_item("partition1", "1", item, None).await?;
```

### Patch Item

```rust
use azure_data_cosmos::models::PatchDocument;

let patch = PatchDocument::default()
    .with_add("/newField", "newValue")?
    .with_remove("/oldField")?;

container.patch_item("partition1", "1", patch, None).await?;
```

### Delete Item

```rust
container.delete_item("partition1", "1", None).await?;
```

## Key Auth (Optional)

Enable key-based authentication with feature flag:

```sh
cargo add azure_data_cosmos --features key_auth
```

## Best Practices

1. **Always specify partition key** — required for point reads and writes
2. **Use `into_model()?`** — to deserialize responses into your types
3. **Derive `Serialize` and `Deserialize`** — for all document types
4. **Use Entra ID auth** — prefer `DeveloperToolsCredential` over key auth
5. **Reuse client instances** — clients are thread-safe and reusable

## Reference Links

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

Overview

This skill provides an idiomatic Rust SDK wrapper for Azure Cosmos DB (NoSQL API) to perform document CRUD, queries, container management, and work with globally distributed data. It shows how to authenticate, obtain Cosmos/Database/Container clients, and perform point reads, writes, patches, and deletes using serde models. The content emphasizes Entra ID authentication, partition-key usage, and client reuse for safe concurrent access.

How this skill works

The skill inspects the typical Cosmos client hierarchy and demonstrates creating a CosmosClient, deriving DatabaseClient and ContainerClient, and executing item-level operations. It explains authentication via DeveloperToolsCredential (Entra ID) and optional key-based auth via a feature flag. Examples include create_item, read_item, replace_item, patch_item, and delete_item, plus deserializing responses with into_model() and serde traits.

When to use it

Building Rust services that store or query JSON documents in Azure Cosmos DB (NoSQL).
Implementing CRUD endpoints or background jobs that operate on globally distributed data.
When you need partition-key aware point reads/writes for performance and scalability.
When you want idiomatic Rust types with serde serialization/deserialization.
When using Entra ID (DeveloperToolsCredential) for secure auth in development or CI/CD.

Best practices

Always specify the partition key for point reads and writes to avoid cross-partition operations.
Derive Serialize and Deserialize for all document structs and use into_model() to deserialize responses safely.
Prefer Entra ID authentication (DeveloperToolsCredential) over key auth; enable key_auth feature only when necessary.
Reuse CosmosClient/DatabaseClient/ContainerClient instances — they are thread-safe and intended for reuse.
Use PatchDocument for minimal updates instead of full replaces when only a few fields change.

Example use cases

A REST API in Rust that creates, reads, updates, and deletes user or product documents in Cosmos DB.
A background ETL worker that patches and upserts telemetry or metrics documents by partition key.
A multi-region service that reads and writes user session/state data to a globally distributed container.
A migration script that enumerates containers and performs bulk replaces or deletes with serde-typed models.

FAQ

Do I need to set environment variables?

Set COSMOS_ENDPOINT, COSMOS_DATABASE, and COSMOS_CONTAINER for convenience; the client can also be instantiated directly with explicit values.

Which auth method should I choose?

Prefer Entra ID (DeveloperToolsCredential) for development and CI/CD. Use key auth only when Entra ID is not available and enable the key_auth feature.