Azure Cosmos Rust

1---
2name: azure-cosmos-rust
3description: |
4  Azure Cosmos DB SDK for Rust (NoSQL API). Use for document CRUD, queries, containers, and globally distributed data.
5  Triggers: "cosmos db rust", "CosmosClient rust", "container", "document rust", "NoSQL rust", "partition key".
6package: azure_data_cosmos
7---
8 
9# Azure Cosmos DB SDK for Rust
10 
11Client library for Azure Cosmos DB NoSQL API — globally distributed, multi-model database.
12 
13## Installation
14 
15```sh
16cargo add azure_data_cosmos azure_identity
17```
18 
19## Environment Variables
20 
21```bash
22COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/
23COSMOS_DATABASE=mydb
24COSMOS_CONTAINER=mycontainer
25```
26 
27## Authentication
28 
29```rust
30use azure_identity::DeveloperToolsCredential;
31use azure_data_cosmos::CosmosClient;
32 
33let credential = DeveloperToolsCredential::new(None)?;
34let client = CosmosClient::new(
35    "https://<account>.documents.azure.com:443/",
36    credential.clone(),
37    None,
38)?;
39```
40 
41## Client Hierarchy
42 
43| Client | Purpose | Get From |
44|--------|---------|----------|
45| `CosmosClient` | Account-level operations | Direct instantiation |
46| `DatabaseClient` | Database operations | `client.database_client()` |
47| `ContainerClient` | Container/item operations | `database.container_client()` |
48 
49## Core Workflow
50 
51### Get Database and Container Clients
52 
53```rust
54let database = client.database_client("myDatabase");
55let container = database.container_client("myContainer");
56```
57 
58### Create Item
59 
60```rust
61use serde::{Serialize, Deserialize};
62 
63#[derive(Serialize, Deserialize)]
64struct Item {
65    pub id: String,
66    pub partition_key: String,
67    pub value: String,
68}
69 
70let item = Item {
71    id: "1".into(),
72    partition_key: "partition1".into(),
73    value: "hello".into(),
74};
75 
76container.create_item("partition1", item, None).await?;
77```
78 
79### Read Item
80 
81```rust
82let response = container.read_item("partition1", "1", None).await?;
83let item: Item = response.into_model()?;
84```
85 
86### Replace Item
87 
88```rust
89let mut item: Item = container.read_item("partition1", "1", None).await?.into_model()?;
90item.value = "updated".into();
91 
92container.replace_item("partition1", "1", item, None).await?;
93```
94 
95### Patch Item
96 
97```rust
98use azure_data_cosmos::models::PatchDocument;
99 
100let patch = PatchDocument::default()
101    .with_add("/newField", "newValue")?
102    .with_remove("/oldField")?;
103 
104container.patch_item("partition1", "1", patch, None).await?;
105```
106 
107### Delete Item
108 
109```rust
110container.delete_item("partition1", "1", None).await?;
111```
112 
113## Key Auth (Optional)
114 
115Enable key-based authentication with feature flag:
116 
117```sh
118cargo add azure_data_cosmos --features key_auth
119```
120 
121## Best Practices
122 
1231. **Always specify partition key** — required for point reads and writes
1242. **Use `into_model()?`** — to deserialize responses into your types
1253. **Derive `Serialize` and `Deserialize`** — for all document types
1264. **Use Entra ID auth** — prefer `DeveloperToolsCredential` over key auth
1275. **Reuse client instances** — clients are thread-safe and reusable
128 
129## Reference Links
130 
131| Resource | Link |
132|----------|------|
133| API Reference | https://docs.rs/azure_data_cosmos |
134| Source Code | https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos |
135| crates.io | https://crates.io/crates/azure_data_cosmos |
136