Study guide
4.1 Cosmos DB for NoSQL: SDK Connect & Queries
Exam AI-200: Developing AI Cloud Solutions on Azure Exam
Track your progress as you read
Finished sections get a check mark.
1 Introduction & Exam Overview
1.1 Current Exam Facts 1.2 Audience Profile & Study Path
2 Chapter 1: Container Registry & App Service Hosting
1.1 ACR: Build, Store, Version & Manage Images 1.2 ACR Tasks: Build & Run Images 1.3 Deploy Containers to Azure App Service
3 Chapter 2: Azure Container Apps & KEDA Scaling
2.1 Azure Container Apps: Environments, Config & Revisions 2.2 KEDA Event-Driven Scaling in Container Apps
4 Chapter 3: AKS Manifests & Container Troubleshooting
3.1 Deploy & Manage Apps on AKS with Manifests 3.2 Monitor & Troubleshoot AKS and Container Apps
5 Chapter 4: Cosmos DB for NoSQL Fundamentals
4.1 Cosmos DB for NoSQL: SDK Connect & Queries 4.2 Optimize RUs: Indexing Policies & Consistency Levels
6 Chapter 5: Cosmos DB Vectors & Change Feed
5.1 Embeddings & Vector Similarity Search in Cosmos DB 5.2 Change Feed Processor for New/Updated Items
7 Chapter 6: Azure PostgreSQL Foundations for AI
6.1 Azure Database for PostgreSQL: Connect & Query with SDKs 6.2 Schema Design, Data Types & Indexing Strategies 6.3 pgvector Indexing: Latency & Compute Overhead
8 Chapter 7: PostgreSQL Vector Workloads & RAG
7.1 Configure Compute, Memory & Storage for Vector Workloads 7.2 Vector Search, Semantic Retrieval & RAG with Metadata Filters 7.3 Connection Optimization for Throughput & Latency
9 Chapter 8: Azure Managed Redis for AI Solutions
8.1 Azure Managed Redis: Caching, Expiration & Invalidation 8.2 Redis Vector Indexing for Similarity Search
10 Chapter 9: Service Bus & Event Grid for AI Pipelines
9.1 Service Bus Queues & Message Processing 9.2 Topics, Subscriptions & Dead-Letter Queues 9.3 Event Grid: Custom Events & Filters 9.4 Event Grid Retries & Event-Driven Workflows
11 Chapter 10: Azure Functions for Serverless AI Back Ends
10.1 Azure Functions: Triggers & Bindings 10.2 Build Serverless APIs with Functions 10.3 Configure & Deploy Function Apps
12 Chapter 11: Key Vault & App Configuration
11.1 Azure Key Vault: Secret Storage & Retrieval 11.2 Key Vault Secret Rotation Patterns 11.3 Azure App Configuration for App Settings
13 Chapter 12: OpenTelemetry & KQL Observability
12.1 Distributed Tracing with OpenTelemetry SDKs 12.2 Correlating Traces into Azure Monitoring 12.3 Write KQL Queries to Analyze Logs 12.4 KQL for Metrics & Troubleshooting Scenarios
4.1 Cosmos DB for NoSQL: SDK Connect & Queries
Key Takeaways Explain This Topic AI
Azure Cosmos DB for NoSQL is accessed through language SDKs (Python azure-cosmos, JavaScript @azure/cosmos) using an endpoint URL and a key or Microsoft Entra ID credential
Every item must include a partition key value; queries that filter on the partition key are single-partition and cost far fewer Request Units than cross-partition fan-out queries
The SQL API uses SELECT/FROM/WHERE/ORDER BY against JSON documents; parameterized queries prevent injection and improve plan reuse
For AI-200, expect scenarios that connect from an Azure AI or app service, choose a partition key aligned to access patterns, and run point reads or filtered queries efficiently
Point reads by id and partition key are the cheapest read path; prefer them over queries when you already know both values
Last updated: July 2026
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):
Account endpoint — a URL such as https://<account>.documents.azure.com:443/
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:
- Feature Purpose Exam tip
- SELECT projections Return only needed properties Reduces payload and can lower RU cost
- WHERE filters Narrow candidates Include partition key when possible
- ORDER BY Sort results Needs a composite index for multi-property sorts
- ARRAY_CONTAINS Filter on array membership Common for tags / topic lists
- OFFSET LIMIT Pagination Prefer continuation tokens for large sets
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:
Persist conversation turns after each chat completion — upsert JSON items partitioned by sessionId .
Store document metadata (source URI, chunk ids, embedding job status) for a knowledge base.
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.