4.1 Cosmos DB for NoSQL: SDK Connect & Queries

Azure Cosmos DB for NoSQL is the document database most often paired with Azure AI solutions when you need globally distributed, low-latency JSON storage for chat history, embeddings metadata, product catalogs, or grounding corpora. On AI-200, you are expected to connect with an official SDK, understand how partition keys shape both scale and query cost, and write SQL API queries that retrieve the right documents without wasting Request Units (RUs).

What “Cosmos DB for NoSQL” Means on the Exam

Cosmos DB is a multi-model service. Cosmos DB for NoSQL (historically called the SQL API or Core API) stores schemaless JSON items and queries them with a SQL-like language. Other APIs (MongoDB, Cassandra, Gremlin, Table) exist, but AI-200 scenarios for this domain focus on the NoSQL API: containers of JSON documents, partition keys, and the SQL dialect.

An account contains databases; a database contains containers; a container holds items. Throughput (RUs/second) can be provisioned at the database or container level, or you can use serverless. For application code, you almost always work at the container level: create, read, replace, delete, and query items.

Connecting with the SDKs

You need two pieces of connection information from the Azure portal (or Key Vault / managed identity):

1. Account endpoint — a URL such as https://<account>.documents.azure.com:443/
2. Credential — either an account key (primary/secondary master key) or a Microsoft Entra ID (Azure AD) token via DefaultAzureCredential / managed identity

JavaScript / TypeScript (@azure/cosmos) typical pattern:

const { CosmosClient } = require("@azure/cosmos");

const client = new CosmosClient({
  endpoint: process.env.COSMOS_ENDPOINT,
  key: process.env.COSMOS_KEY
});

const database = client.database("aiAppDb");
const container = database.container("sessions");

Python (azure-cosmos) typical pattern:

from azure.cosmos import CosmosClient

client = CosmosClient(url=endpoint, credential=key)
database = client.get_database_client("aiAppDb")
container = database.get_container_client("sessions")

Production AI apps should prefer Entra ID / managed identity over embedding master keys in app settings. Keys remain common in labs and sample code, so recognize both patterns. After you obtain a container client, all item operations share that client’s connection policy (retry, consistency preference, preferred regions).

Partition Keys: The Design Decision That Drives Queries

Every container has a partition key path (for example /tenantId, /userId, or /sessionId). Each item must supply a value for that path. Cosmos DB hashes the partition key value and places the item in a logical partition. Logical partitions are distributed across physical partitions as the container grows.

Why this matters for AI-200:

• Point reads and queries that include an equality filter on the partition key execute against a single logical partition — lower latency and lower RU cost.
• Cross-partition queries fan out across physical partitions, merge results, and consume more RUs. They still work, but they are a last resort for hot paths.

Choose a partition key that:

• Matches how the app looks up data (for example, always load chat turns by sessionId)
• Avoids unbounded hot partitions (a single status = "active" value is a poor key)
• Keeps related items together when they are read together

For retrieval-augmented generation (RAG) metadata stores, common patterns are /docId, /workspaceId, or /tenantId depending on whether queries are per document, per workspace, or per customer.

Point Reads vs Queries

If you know both the item id and its partition key value, use a point read (read / read_item). Point reads are billed at a fixed, low RU cost and do not require the query engine. Use queries when you need filters, projections, or ordering across many items.

JavaScript point read:

const { resource } = await container.item(id, partitionKeyValue).read();

Python point read:

item = container.read_item(item=id, partition_key=pk_value)

SQL API Queries

Cosmos DB for NoSQL uses a SQL-like syntax over JSON. A simple filtered query:

SELECT c.id, c.role, c.content, c.createdAt
FROM c
WHERE c.sessionId = @sessionId AND c.role = @role
ORDER BY c.createdAt ASC

Always prefer parameterized queries (@sessionId) over string concatenation. Parameters avoid injection risks and help the service cache query plans.

JavaScript query with partition key scope:

const querySpec = {
  query: "SELECT * FROM c WHERE c.sessionId = @sid",
  parameters: [{ name: "@sid", value: sessionId }]
};
const { resources } = await container.items
  .query(querySpec, { partitionKey: sessionId })
  .fetchAll();

Passing partitionKey in the request options (when the filter equals the partition key) keeps the query single-partition. Omitting it makes the same SQL a cross-partition query.

Python query:

query = "SELECT * FROM c WHERE c.sessionId = @sid"
params = [{"name": "@sid", "value": session_id}]
items = list(container.query_items(
    query=query,
    parameters=params,
    partition_key=session_id
))

Useful SQL API features for AI workloads:

Continuation tokens (not OFFSET alone) are the scalable way to page through large result sets in SDK loops.

SDK Patterns That Show Up in AI Solutions

AI-200 often ties Cosmos DB to apps that call Azure OpenAI or Azure AI Search. Typical flows:

1. Persist conversation turns after each chat completion — upsert JSON items partitioned by sessionId.
2. Store document metadata (source URI, chunk ids, embedding job status) for a knowledge base.
3. Look up user or tenant configuration with a point read before calling a model.

When writing items, include id (string) and the partition key property. Upserts are convenient for idempotent writes of the same logical entity. For high ingest, batch or transactional batch APIs can group operations within a single partition key.

Error Handling and Connectivity Essentials

Expect 429 (Request rate too large) when you exceed provisioned RUs — SDKs retry with backoff by default. 404 means the item or container was not found. Network and TLS settings must allow outbound HTTPS to the account endpoint from App Service, Functions, AKS, or your local machine.

For multi-region accounts, configure the SDK preferred regions so reads prefer a nearby replica. Consistency level (covered in the next section) can be set account-wide or overridden per request in supported SDKs.

Exam Scenario Checklist

When a question describes “an AI chat app must retrieve the last 20 messages for a session,” the efficient answer is: partition by sessionId, query with WHERE c.sessionId = @id ORDER BY c.createdAt, and optionally project only the fields the prompt builder needs. When the question gives both id and partition key, choose a point read over a SELECT * query. When the question asks how to connect securely from Azure Functions, prefer managed identity over copying the primary key into plain text settings.