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".
- License 许可
- MIT
- 所属仓库
- microsoft/skills
- 最近更新
- 2026-11-14
- Stars
- ★ 3.2k
- Forks
- 368
01 前言 Front Matter
- name
- azure-cosmos-rust
- license
- MIT
- metadata
- { "author": "Microsoft", "package": "azure_data_cosmos" }
- description
- 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".
02 资源文件 1
- 参考文档references/validation.md5.6 KB
03 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_cosmoscrate published by the azure-sdk crates.io user. Do NOT use the unofficialazure_cosmosorazure_sdk_for_rustcommunity 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_coretypes directly (for example,azure_core::credentials::TokenCredential), addazure_coretoCargo.toml. If you only useazure_data_cosmosre-exports, directazure_coredependency 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
- Use
cargo addto manage dependencies, never editCargo.tomldirectly. Add and remove Rust SDK dependencies with cargo commands instead of manual manifest edits. - Add
azure_coreonly when importingazure_coretypes directly. If your code importsazure_core::http::Url,azure_core::http::RequestContent, orazure_core::error::ErrorKind, includeazure_core; otherwise a direct dependency is optional. - Use
DeveloperToolsCredentialfor local dev,ManagedIdentityCredentialfor production — Rust does not provide a singleDefaultAzureCredentialtype - Never hardcode credentials — use environment variables or managed identity
- Reuse
CosmosClient— clients are thread-safe; create once, share across tasks - Use
RoutingStrategy::ProximityTo— route to the nearest region for lowest latency - Always specify partition key for item operations — Cosmos DB requires it for all CRUD
- Run
cargo clippy -- -D warningswhen the prompt, eval, or CI expects lint-clean output - 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
04 同仓库更多 Skills
azure-advisor-cost-optimization
Analyze Azure Advisor Cost/IdleResources findings and prevalidate deletion safety, including Service Groups. WHEN: "find unused Azure resources", "what resources am I paying for but no longer using", "idle-resource savings", "historical idle-resource savings", "are these idle resources safe to delete". Generic Cost, other subcategories, and cross-category requests use azure-advisor.
skill-creator
Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating existing skills.
podcast-generation
Generate AI-powered podcast-style audio narratives using Azure OpenAI's GPT Realtime Mini model via WebSocket. Use when building text-to-speech features, audio narrative generation, podcast creation from content, or integrating with Azure OpenAI Realtime API for real audio output. Covers full-stack implementation from React frontend to Python FastAPI backend with WebSocket streaming.
microsoft-docs
Understand Microsoft technologies by querying official documentation. Use whenever the user asks how something works, wants tutorials, needs configuration options, limits, quotas, or best practices for any Microsoft technology (Azure, .NET, M365, Windows, Power Platform, etc.)—even if they don't mention "docs." If the question is about understanding a concept rather than writing code, this is the right skill.
mcp-builder
Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP), Node/TypeScript (MCP SDK), or C#/.NET (Microsoft MCP SDK).
kql
KQL language expertise for writing correct, efficient Kusto Query Language queries. Covers syntax gotchas, join patterns, dynamic types, datetime pitfalls, regex patterns, serialization, memory management, result-size discipline, and advanced functions (geo, vector, graph). USE THIS SKILL whenever writing, debugging, or reviewing KQL queries — even simple ones — because the gotchas section prevents the most common errors that waste tool calls and cause expensive retry cascades. Trigger on: KQL, Kusto, ADX, Azure Data Explorer, Fabric Real-Time Intelligence, EventHouse, Log Analytics, log analysis, data exploration, time series, anomaly detection, summarize, where clause, join, extend, project, let statement, parse operator, extract function, any mention of pipe-forward query syntax.