DEV Community: Abhishek Gupta

Need a different partition key in Azure Cosmos DB? Pick the right approach

Abhishek Gupta — Mon, 20 Jul 2026 17:10:24 +0000

Once you create a container, its partition key is fixed at creation, and you can't change it in place. However, if your original key starts causing problems like cross-partition queries or hot partitions, you need to consider your options for changing it. This post explains the mechanics of changing a partition key, and the tradeoffs between the options.

First, think about the intent of your change:

Re-partition the data. You want your items (and future writes) to live under a different key. This means moving to a new container and there are three ways, from least to most effort: Change partition key feature, container copy jobs, or a do-it-yourself migration.
Query by a different key without moving. Your writes are fine where they are, and you only have read patterns that fan out across partitions. A Global Secondary Index adds a separate, read-only, automatically-synchronized container with a different partition key and its own data model, a projection of your items (all properties, or just a subset). The source container stays unchanged.

Note that every "change the partition key" option is actually a move: get your data into a new container that has the new key, then point your app at it. The exception is a Global Secondary Index, which adds a different key for read patterns while the source container stays unchanged.

Let's walk through each path and its tradeoffs.

Re-partition the data

The three options below all land your data in a new container with the new key. But, they differ in how much Azure Cosmos DB does for you, whether you can keep writing to the source while the copy runs, and how much control you have over the cutover.

Option 1: the portal Change partition key feature (least effort)

The portal feature is the managed path. In the Azure portal, open Data Explorer, pick your container, go to Scale & Settings → Partition Keys, and select Change.

The portal creates or selects a destination container in the same database, then copies your data into it using container copy jobs (Option 2 covers those, since they're the same engine). If you let the portal create the destination container for you, all configurations except the partition key and unique keys are replicated to the destination, so you only restate those two. You can run the copy online or offline (the next section explains what that means). In online mode you finish the job by selecting Complete, and once the copy is done you start using the new container with the new key and optionally delete the old one.

Read more in the Change partition key limitations

Option 2: container copy jobs directly (same engine, scriptable)

Container copy jobs are the engine behind the portal capability. You can also create and manage them yourself with Azure CLI (via the cosmosdb-preview extension), which is what you want for scripting, automation, or finer control. The workflow is: create the target container with the partition key (and throughput, unique keys, etc.) you want, create the copy job, monitor it, and cut over. When the source and destination are in different accounts, you first give the destination account's identity read access to the source container. Same-account copies don't need this step.

Container copy has two modes: online, where writes continue during the copy, and offline, where you stop writes before the job starts.

Online mode keeps writes flowing during the copy and ends with a short Complete-then-cutover, but every source write is charged double RUs while online copy is enabled, and it needs continuous backup, all-versions-and-deletes change feed, and the account-level capability switched on first. Offline skips those prerequisites at the cost of a write freeze on the source until you cut over. The Container copy jobs documentation walks through the prerequisites and cutover for both modes.

Both modes run on a best-effort basis (there's no guaranteed completion time), and jobs run one at a time in the write region. Two things are worth planning for: a copy doesn't carry TTL across, so an item that hasn't expired restarts its countdown in the destination, and you'll want the target provisioned at roughly twice the source throughput to keep up.

Before you cut over: A new container is also your one window to turn on features that can only be set at creation, the clearest being hierarchical partition keys, so weigh them now if they fit your workload. And since you're re-keying everything, confirm the new partition key value plus id is unique across the destination, or two formerly distinct items can collide.

Option 3: roll your own migration (most control, most work)

If you need transforms during the move, your container exceeds the container-copy limits, or you just want full ownership of the process, create the new container yourself and move the data with your own pipeline. The large-scale migration guidance covers the building blocks:

Bulk ingestion to load the new container fast: the .NET v3 SDK has it built in, and the bulk executor library covers apps still on .NET SDK 2.x.
Azure Data Factory for smaller datasets (configure source and sink, no code), or the Spark connector if you already work in Spark.
Change feed to catch writes that land on the source after your bulk load and replay them into the new container until you cut over. Its default latest-version mode skips deletes and TTL expirations, so use all-versions-and-deletes (which needs continuous backup) to handle delete operations.

Pre-create the destination with enough RU/s and turn off indexing during the load to hold down write cost. You own incremental sync, error handling, cutover, and any reshaping along the way.

Query by a different key, without moving (global secondary index)

If your only pain is cross-partition queries (reads that fan out because your filter property isn't the partition key), you may not need to move at all. For that case, use global secondary indexes.

A global secondary index (GSI) is a separate, read-only container keyed by a different partition key, with its own data model. That model is a projection query over your items (SELECT * for all properties, or just the subset you query), and it stays automatically synchronized with the source container. You keep writing to your existing container with its existing key, and queries whose filter matches the GSI's partition key (the specific patterns you built the GSI for) can become single-partition queries against the GSI instead of cross-partition queries on the source. A GSI helps the patterns it's keyed for, not every cross-partition query.

GSIs fit when changing your existing partition key would be disruptive, and you have multiple query patterns that no single key can satisfy. A GSI needs continuous backups on the account, stays eventually consistent regardless of your consistency level, and runs on autoscale with its own storage and RU costs. Once one exists, replace and delete on the source cost 50–100% more RU (creates aren't affected), and global secondary indexes cover the rest.

A GSI fixes reads. It doesn't change where your writes land, so it won't relieve a write-side hot partition on the source. If your problem is write distribution, or you need a different primary key for the data, you're back to the data re-partitioning option above and you have to move.

To wrap up

If your writes need a different key, you end up moving the data, and the only question left is how much of the copy you hand to Azure Cosmos DB. If only your reads fan out, a GSI fixes that without changing where your writes land. The table below puts all four side by side.

Decision table

Option	Keep writing to the source during the move?	Effort	Use it when
Portal "Change partition key"	Yes (online mode) or no (offline)	Lowest	You want point-and-click, container < 1,000,000 RU/s, < 4 TB, supported region
Container copy jobs (CLI)	Yes (online) or no (offline)	Low–medium	You want the managed engine but scripted, with explicit online/offline control
Roll your own (bulk / ADF / Spark + change feed)	Yes, if you build incremental sync yourself	Highest	You need transforms, are above the copy limits, or want full control of cutover
Global secondary index	N/A, source stays as-is, GSI auto-synced	Medium	The pain is cross-partition reads, not write hot partitions, and you can keep the source key

Learn more

AI agents, meet the Azure Cosmos DB vNext emulator

Abhishek Gupta — Mon, 20 Jul 2026 17:08:31 +0000

If you use the Azure Cosmos DB vNext emulator, you probably know the local development loop: start the emulator, connect to it, create some resources, load test data, run queries, and inspect the results. Each step is straightforward, but together they add setup work before you can test the application you are actually building.

How agents work with the emulator

The emulator includes Cosmos DB Shell, an open-source CLI for working with databases, containers, and items. It runs inside the emulator container and handles the local endpoint and well-known key, giving developers a direct, scriptable way to work with the emulator.

CLIs are well suited to agent workflows because they expose operations as explicit commands and return results the agent can inspect. An agent can discover commands through built-in help, run them non-interactively, respond to errors, and use the output to choose its next action. These characteristics make the CLI a practical interface for agents. Cosmos DB Shell brings that model to the local emulator.

For example, an agent can run Cosmos DB Shell non-interactively inside the emulator container:

docker exec <emulator-container> cosmoshell.sh -c '<command>'

It gives AI coding agents, such as GitHub Copilot CLI, Codex, and Claude Code, a straightforward way to work with the emulator. The developer describes the required outcome instead of translating the task into a sequence of shell commands. Command access is only the starting point. The agent still needs an operating procedure for finding the emulator, choosing appropriate commands, respecting safety boundaries, and verifying its work.

An Agent Skill fills that gap by packaging task-specific guidance for reuse across requests and sessions. For the local emulator, the cosmosdb-emulator-vnext skill helps the agent inspect resources, create databases and containers, load test data, and run queries through Cosmos DB Shell.

Explore the skill on GitHub: cosmosdb-vnext-emulator-skill

From prompt to local test data

Consider a developer building a multi-tenant order-processing application. The integration tests need data across multiple tenants and different stages of the order lifecycle. Creating and maintaining that data by hand can quickly become tedious.

Instead, the developer could give a coding agent this prompt:

I’m building a multi-tenant order-processing app and need realistic data
for integration testing. Set up my local Cosmos DB emulator with synthetic
orders covering two tenants and a mix of new, shipped, and cancelled orders.
Show me the data when it’s ready.

I tested this prompt with GitHub Copilot CLI while the local emulator was already running. The agent located the emulator, used the bundled Cosmos DB Shell, and created OrdersDB with an Orders container partitioned by /tenantId.

It then generated a balanced set of synthetic orders for both tenants. Each order included customer details, nested line items, timestamps, shipping information, and totals. It also added status-specific fields, such as tracking information for shipped orders and cancellation reasons for cancelled ones.

The setup summary showed what the agent created:

Database: OrdersDB
Container: Orders
Partition key: /tenantId
Orders created: 12

To verify the data, the agent queried the container. Six of the 12 orders are shown below:

Order	Tenant	Customer	Status	Total
ord-a001	tenant-alpha	Alice Navarro	new	$145.96
ord-a003	tenant-alpha	Clara Mendes	shipped	$361.99
ord-a005	tenant-alpha	Elena Vasquez	cancelled	$129.00
ord-b001	tenant-beta	Grace Osei	new	$74.97
ord-b003	tenant-beta	Ingrid Sorensen	shipped	$249.00
ord-b006	tenant-beta	Luca Ferrari	cancelled	$101.97

Because the request is open-ended, names, values, and document counts may vary. The workflow remains the same: create the resources, load the data, and query it back. Showing the saved orders confirms that the data is in the emulator and ready for the application to use.

At this point, the developer has persisted, partitioned data for integration testing without writing a seed script or manually assembling documents.

Notice that the prompt describes the application need, not the operating procedure. It says nothing about finding the emulator, using the bundled shell, choosing non-interactive commands, or verifying changes.

Why use an Agent Skill

You could include all of those operating instructions in every prompt. That works for a one-off task, but repeating the same guidance soon becomes tedious. Results can also vary when an important constraint is omitted or phrased differently.

Moving the guidance into global instructions avoids that repetition, but makes emulator-specific context available during unrelated tasks.

An Agent Skill avoids both tradeoffs. The cosmosdb-emulator-vnext skill keeps the emulator guidance in one place and makes it available when a relevant request is detected. As a Markdown file, the skill can be shared, reviewed, tested, versioned, and adapted to a team's conventions or testing workflow.

The same approach extends to other parts of Cosmos DB development. The Azure Cosmos DB team maintains the Cosmos DB Agent Kit, a collection of skills for AI coding agents working with Cosmos DB. It includes guidance on data modeling, partition-key design, query optimization, SDK usage, indexing, throughput, security, and monitoring.

The emulator skill may also be combined into the Agent Kit and maintained there alongside other Cosmos DB skills.

Try it yourself

Agent Skills are a lightweight, open standard that lets you reuse the same skill across coding agents.

Install the skill and put it to work with your local emulator:

npx skills add abhirockzz/cosmosdb-vnext-emulator-skill

Then run the order-processing prompt above to create your first test dataset. From there, adapt the request to the data and workflows your application needs.

Together, the local emulator, Cosmos DB Shell, and the skill make this kind of setup repeatable without hiding how the work gets done. Developers can describe the data they need while the agent runs explicit commands, verifies the result, and leaves an execution trail they can inspect.

How to Use LangChain Deep Agents with Azure Cosmos DB – Plan, act, and verify against operational data

Abhishek Gupta — Tue, 23 Jun 2026 18:26:49 +0000

Originally posted on https://devblogs.microsoft.com/cosmosdb/deep-agents-to-plan-act-verify-against-operational-data/

Deep Agents is an agent harness built on LangGraph, for agents that need to work through a task over many steps instead of a single LLM call. The agent runs tools, looks at the results, and uses that to pick the next one, keeping a todo list as it goes. On top of that loop the harness brings what a longer-running agent needs. It can load instructions on demand instead of holding everything in the prompt (skills), offload large tool outputs so they don't fill the context window, and pause for human approval in apps that need an approval gate before data changes.

Support Ops Agent is a sample app that puts this to work on a customer-support ticket queue. We can ask it which tickets are at risk, who's overloaded, or whether a run of similar complaints is really one outage. When a ticket needs to change, it updates the ticket and reads it back to confirm. Most requests become a handful of reads against the queue. Requests that change a ticket add a patch and a verification read.

That queue lives in Azure Cosmos DB, the operational database the support team already runs on. The agent reads and writes that same store through the Azure Cosmos DB SDK, so it works on the live tickets, with no side index to keep in sync. Each ticket is an Azure Cosmos DB item, with its tags and history kept right inside it, and the agent updates that item directly. With the partition key doing its job, point reads and customer-scoped queries stay cheap. Queue-wide investigations spend RUs based on the cross-partition work they do, which is why the tools project only the fields they need. The schema is flexible, so the agent can add a tag or append to a history array without a migration.

The code is on GitHub with instructions to run it against your own Azure Cosmos DB account. In this post, I'll go through:

what the agent can do, and the Azure Cosmos DB operation behind each kind of request
why Deep Agents and Azure Cosmos DB fit this problem
the tools it uses to work on the ticket queue
practical examples of how the agent works: morning triage, resolving a ticket, and spotting an incident

Agent capabilities

The requests in this sample all come down to a few Azure Cosmos DB operations. Some questions only need reads. Others need the agent to read first, decide what changed, and then patch the ticket.

Ask it to…	What the agent does	Cosmos DB operations
Triage the queue	Finds the at-risk tickets (high priority, still active, gone stale) and reports the handful that actually matter	cross-partition query, filter, ORDER BY
Resolve a ticket	Point-reads the ticket, checks related ones from the same customer, updates status, owner, and history, then re-reads to confirm	point read, related-item query, update, verify
Spot an incident	Searches for a cluster across customers, including symptoms filed under the wrong area, and can tag the group as a known issue	multi-step query, repeated patches
Check queue health	Summarizes the queue by status, by area, and by who is carrying the load	grouped counts
Cover for someone	Takes an absent agent's active tickets and moves them to whoever has the lightest load, then confirms the rebalance	grouped counts, repeated patches

I'll walk through the first three below. The other two use the same tools, so they are useful checks when you run the sample yourself.

Approach: Agentic vs Static

Most ticket questions don't have a one-query answer. Take "is something breaking across customers." We run a query, look at what comes back, and only then know whether a second, narrower query is worth running. Deep Agents handles exactly that kind of back-and-forth. It plans the work as a short todo list, calls tools, reads results, and decides the next step, instead of trying to answer in a single pass. It also keeps the agent's instructions lean: the role and the ticket schema stay loaded at all times, while the longer how-to guides load only when a task needs them.

Every ticket is stored under its customer (/customerId), so anything scoped to one customer, like reading a single ticket or pulling everything for ACME, stays inside one partition and querying it cost-effective. Queue-wide questions like triage or incident detection read across partitions instead, which is the right call when we're asking about every customer at once. The agent picks single-partition or cross-partition to match the question.

How it works

Everything the agent does to the queue goes through the tools, each a thin wrapper over a single Azure Cosmos DB operation: a query, a point read, a grouped count, and a write. The agent never gets a raw database connection. It works the queue with the same handful of operations a support lead would, and decides which one each request calls for.

run_query is the one the agent reaches for most. It takes a SELECT and runs it cross-partition, which is what lets the agent search the whole queue. It's read-only: anything that isn't a SELECT is refused, and so is a cross-partition GROUP BY (more on that below). Writes have their own tool.

@tool
def run_query(query: str, parameters: str = "[]") -> str:
    """Run a read-only Cosmos DB NoSQL SELECT over the tickets container."""
    stripped = query.strip()
    if not stripped.upper().startswith("SELECT"):
        return "Error: only SELECT queries are allowed. Use update_ticket for writes."
    items = _get_container().query_items(
        query=stripped,
        parameters=json.loads(parameters) or None,
        enable_cross_partition_query=True,
    )
 ...

read_ticket is the cheap path. When the agent already knows the ticket id and the customer, it does a point read on the partition key for around 1 RU instead of running a query.

update_ticket is the only way the agent writes. It patches a ticket in place, always refreshes updatedAt, and appends an entry to the ticket's history array, so every change it makes stays traceable.

ops = [{"op": "set", "path": f"/{k}", "value": v} for k, v in fields.items()]
ops.append({"op": "set", "path": "/updatedAt", "value": now})
if history_note:
    ops.append({
        "op": "add", "path": "/history/-",
        "value": {"at": now, "by": history_by, "note": history_note},
    })
_get_container().patch_item(
    item=ticket_id, partition_key=customer_id, patch_operations=ops,
)

aggregate_tickets answers the queue-health questions: how many tickets sit in each status, which area is busiest, who is carrying the most load. It counts tickets across the whole queue, grouped by a single field.

You might expect that to be a plain GROUP BY, and in Azure Cosmos DB's query language it is. The catch is in the SDK. The azure-cosmos Python SDK runs a GROUP BY fine within a single partition, but refuses one that spans partitions, returning "Cross partition query only supports 'VALUE' for aggregates."

The support queue spans every customer, so the grouped counts have to come some other way. aggregate_tickets projects the one field across partitions and counts the values in Python instead, and run_query points the agent here whenever it reaches for a GROUP BY.

Support Ops agent in action

I'll use three requests from the sample runs to show what that looks like. They start the way a support lead would ask them, and the agent has to turn each one into the right mix of queries, reads, and updates.

Morning triage

I just got in, what should I look at first?

There's no single query for "what should I look at first." The agent reads it as a question about risk: which active tickets are closest to slipping. A ticket has no "at risk" field to sort by, so the agent has to decide what at-risk means and turn that into a query. It settles on the tickets that are high priority, still active, and have gone untouched for a few days, and asks Azure Cosmos DB for those, oldest first.

SELECT c.id, c.customerId, c.priority, c.status, c.area, c.assignee, c.updatedAt
FROM c
WHERE c.priority IN ('P1','P2')
  AND c.status IN ('open','in-progress')
  AND c.updatedAt < @staleBefore
ORDER BY c.updatedAt ASC

It doesn't stop at the list. It also runs a few grouped counts to size up the rest of the queue behind those tickets, then reports the handful that matter with a one-line reason each and a suggested order to work them:

Start with the stale high-priority active tickets:

- TICKET-1004 (UMBRELLA): P1 open, unassigned, data issue, untouched since
  Jun 5. Oldest urgent ticket in the queue.
- TICKET-1003 (INITECH): P2 open, unassigned, login lockout, untouched since
  Jun 7. Customer access issue and stale.
- TICKET-1001 (ACME): P1 open, unassigned, billing, untouched since Jun 8.
  Revenue-impacting and still idle.
- TICKET-1002 (GLOBEX): P1 in-progress, performance, with agent.lee, untouched
  since Jun 9. Already owned, but stale enough to need a status check.
- TICKET-1010 (INITECH): P2 open, unassigned, performance, untouched since
  Jun 11.

Queue health in brief: 93 active tickets (57 open, 36 in-progress), and 72 of
them are unassigned. Hottest active area is api (22), then billing (21).

Note how the user didn't define "at risk" up front – the agent had to turn that into something Azure Cosmos DB could query.

Resolve a ticket

The next request names a specific ticket and expects something done about it:

GLOBEX is unhappy about TICKET-1050, can you pick it up and move it forward?

The agent starts with a point read on the ticket. It knows the id and the customer, so this stays inside GLOBEX's partition. The ticket comes back as a login issue, open and unassigned. Before touching it, the agent looks for context: it pulls GLOBEX's other tickets, then checks the active login tickets across the rest of the queue, and notices this isn't an isolated report. Several customers have similar authentication problems open right now.

With that picture, it does the obvious thing: the ticket needs an owner and a status update. It applies the change through update_ticket, which patches the fields, refreshes updatedAt, and appends a history note in one write so the trail is clear.

status → in-progress
assignee → agent.dana
tags += login, auth, needs-investigation
history += "Picked up after customer escalation; flagged for auth investigation."

Then it reads the ticket back to confirm the change landed, rather than trusting the write went through, and reports what it did and why:

TICKET-1050 (GLOBEX) is now in progress with agent.dana assigned.

Why this move:
- It was a stale P2 login issue sitting open and unassigned.
- There are similar active login/auth tickets across other customers, so this
may be part of a broader authentication pattern rather than an isolated report.

Verified state: status in-progress, assignee agent.dana, tags
login / auth / needs-investigation, history note added.

For TICKET-1050, the agent didn't just assign an owner. It checked the customer context, looked for similar login issues, made the update, and then read the ticket back. The agent should not report a write until it has read the updated ticket and seen the new status, assignee, tags, and history note.

Spot an incident

Now try a login related request that starts broad:

Logins feel shaky this week, dig in and flag anything related.

The agent pulls in its incident-search guide before it starts querying. Its first pass is the obvious one: active tickets in the login area. That catches part of the problem, but not all of it. People describe the same symptom in different words, and some login tickets land under another area. So the agent runs a second query against the ticket text, looking for authentication symptoms that landed somewhere else.

SELECT c.id, c.area, c.title FROM c
WHERE c.area != 'login' AND c.status IN ('open','in-progress')
  AND (CONTAINS(LOWER(c.description), 'authentication')
       OR CONTAINS(LOWER(c.description), 'sign in')
       OR CONTAINS(LOWER(c.description), 'log in'))

That second query turns up TICKET-1052 (STARK), filed under other as "Authentication errors on mobile app", which an area = 'login' filter would have missed entirely. A few more queries (grouped counts by customer, and a check on how recent these are) confirm the issue:

There is a real login/auth cluster.

7 active tickets across 6 customers, 6 of them created this week and 4 landed on
Jun 13 alone. The most urgent:

- TICKET-1051 (HOOLI): P1 open, "Multiple users can't log in this morning"
- TICKET-1053 (UMBRELLA): P2 open, "SSO login broken after update"
- TICKET-1052 (STARK): P2 open, area `other`, "Authentication errors on mobile app"
- TICKET-1050 (GLOBEX): P2 open, "Cannot sign in - authentication failing"
- TICKET-1042 (ACME): P2 open, "Unable to log in after MFA enabled"

One relevant ticket is misfiled under `other`, so a pure area = 'login' view
undercounts the issue.

If you want, I can tag these 7 with a shared marker like known-issue:login-surge
so the cluster is easier to track.

Tagging seven tickets is different from updating one, so the agent stops and asks first. If the user confirms, it could have made the update_ticket patch on each one, append the tag and a history note. The login surge only becomes visible after the active-login query, the text search, the customer counts, and the dates are looked at together.

Try it, and build your own

The repo has everything to run this against your own Azure Cosmos DB account: the tools, the seed data, and a CLI that streams each step as the agent works. The README walks through setup and the az login auth. Run python seed.py to load the support queue data, then replay the runs above or ask the agent your own questions.

Once you have the sample running, try the same idea with data from one of your own workflows. Start with read-only questions and watch how the agent breaks them into Azure Cosmos DB operations. Then add scoped writes when the boundary is clear: what the agent can change, what history it should leave, and how it verifies the result. That could be support tickets, incidents, orders, devices, or any other operational data where a multi-step agent can help.

Learn more

For the agent framework, start with the Deep Agents docs
AI agents in Azure Cosmos DB is a good place to step back and review the broader agent concepts: planning, tool use, memory, copilots, autonomous agents, and multi-agent systems.
Agentic Retrieval Toolkit shows how to ground answers with multi-step retrieval over Cosmos DB data
Agent Memory Toolkit covers durable agent memory backed by Cosmos DB.
MCP Toolkit for Azure Cosmos DB shows another way to expose Cosmos DB capabilities to agentic applications.

Announcing General availability of the Azure Cosmos DB vNext emulator

Abhishek Gupta — Tue, 23 Jun 2026 18:15:41 +0000

Originally posted on https://devblogs.microsoft.com/cosmosdb/announcing-general-availability-of-the-azure-cosmos-db-vnext-emulator/

The Azure Cosmos DB vNext emulator is generally available today. It ships as a Docker image that runs on Linux, macOS, and Windows, on both x64 and ARM64 architectures, giving you a local Cosmos DB instance you can develop and test against. Use it for inner-loop development on your laptop, in CI integration tests, and anywhere else you'd rather not use a live account.

You can get started right away with a couple of simple commands:

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

docker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

A lot has shipped since the preview announcement: broader feature and API coverage, an embedded shell, vector search, and OpenTelemetry support. The rest of this post walks through what's new at GA and how to use it.

Bootstrap and explore data with the bundled Azure Cosmos DB Shell

Azure Cosmos DB Shell is an open-source CLI for interacting with Azure Cosmos DB using bash-like commands. It's now bundled inside the emulator image, so you can drop into an interactive session against a running container without installing anything separately:

docker exec -it <container-name> cosmoshell.sh

The wrapper auto-detects the emulator endpoint and authenticates with the well-known account key.

Before this, getting a known dataset into the emulator usually meant an extra script in your test setup: wait for the gateway to come up, then create databases, containers, and seed documents. Thanks to the Azure Cosmos DB Shell integration, the emulator runs any .csh scripts at the top level of /init in alphabetical order before the emulator is ready to accept requests. The bootstrap step moves out of your application and into the container itself.

This is useful for many scenarios, including:

CI integration tests. Every job starts from an identical, deterministic dataset, with no app-side bootstrap and no readiness polling.
Local dev reset. Pair --rm with an /init folder for a one-command reset back to a known state between runs.
Demos and tutorials. Ship fixture scripts next to your sample so readers see real data on first run, not an empty database.
Bug repros. Capture a problematic dataset as a small folder of scripts and attach it to an issue.

The example below sets up a ShopDB with Users and Orders containers, both partitioned on /customerId so a customer's orders co-locate with their profile. It uses separate scripts for each step.

01-init.csh creates the database and both containers. Adding cd ShopDB at the end means later scripts don't have to repeat --database=ShopDB on every line, since the shell session is shared across files.

mkdb ShopDB
mkcon Users /customerId --database=ShopDB
mkcon Orders /customerId --database=ShopDB
cd ShopDB

02-load.csh inserts a couple of users and a few of their orders:

mkitem -container Users '{"id":"u1","customerId":"u1","name":"Alice","tier":"gold"}'
mkitem -container Users '{"id":"u2","customerId":"u2","name":"Bob","tier":"silver"}'
mkitem -container Orders '{"id":"o1","customerId":"u1","total":129.50,"status":"shipped"}'
mkitem -container Orders '{"id":"o2","customerId":"u1","total":42.00,"status":"pending"}'
mkitem -container Orders '{"id":"o3","customerId":"u2","total":18.75,"status":"shipped"}'

Mount the folder at /init and start the container:

docker run --name emulator --rm -e ENABLE_INIT_DATA=true \
-v "$(pwd):/init" -p 8081:8081 -p 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

By the time the emulator is up, both containers are populated and queryable. Verify with a one-liner that pulls Alice's orders:

docker exec emulator cosmoshell.sh -c \
'query "SELECT c.id, c.total, c.status FROM c WHERE c.customerId = '\''u1'\''" --container=Orders --database=ShopDB'

If you just want a quick look without writing any scripts, the image also ships with example seed scripts under /scripts/init_examples/ that load automatically when ENABLE_INIT_DATA=true is set. Or, if you need the seeded state to survive container restarts, bind-mount a host folder at /data and the emulator will skip initialization on subsequent runs. The documentation has the full set of options.

Vector search for local AI development

The emulator supports vector search, so you can build and iterate on RAG and semantic-search workloads locally. Define a vector embedding policy on the container, add a matching vector index, and write the embedding alongside the rest of your document:

{
  "vectorEmbeddingPolicy": {
    "vectorEmbeddings": [
      { "path": "/embedding",
        "dataType": "float32",
        "distanceFunction": "cosine",
        "dimensions": 1024
      }
    ]
  }
}

Then, you can execute semantic search queries using the VectorDistance() function to get results ranked by similarity. Paired with a model running on your laptop, embeddings, storage, and retrieval all stay on the machine, which is handy when you're iterating on your application.

Try out this sample that embeds and loads data into the emulator. It uses LangChain, a popular open-source framework for building AI applications, and Ollama, a tool for running open-source models locally.

You'll need Python 3.x, and Ollama installed locally.

Start by running the emulator:

docker run --detach --name emulator \
-p 8081:8081 -p 1234:1234 \
mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

Install Ollama, start the local server, and pull mxbai-embed-large. It produces 1024-dimension embeddings and is small enough to run comfortably on a developer laptop:

curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull mxbai-embed-large

Clone the sample and install its dependencies in a virtual environment:

git clone https://github.com/abhirockzz/cosmosdb-emulator-local-vector-search-example

cd cosmosdb-emulator-local-vector-search-example

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

The sample reads its database name, container name, and embedding model from environment variables:

export DATABASE_NAME="docsdb"
export CONTAINER_NAME="docs"
export EMBEDDINGS_MODEL="mxbai-embed-large"
export EMBEDDING_DIMENSIONS="1024"

Now load the data. load_data.py fetches two Azure Cosmos DB documentation pages, splits them into Markdown chunks with LangChain, embeds each chunk with Ollama, and writes the chunks plus their vectors into the emulator. The container is created on first run with a vector embedding policy (/embedding, float32, cosine distance) and a DiskANN vector index.

python3 load_data.py

With the data loaded, you can run vector queries. vector_search.py takes a natural-language query, embeds it with the same local model, and runs a VectorDistance() query against the emulator container to return the top-k matching chunks by cosine similarity:

python3 vector_search.py "show me an example of a vector embedding policy"

You'll get back the most semantically relevant chunks of the source documentation, ordered by score. Try a few more queries to get a feel for what the index is doing:

python3 vector_search.py "how do I tune recall vs latency for vector queries"
python3 vector_search.py "best practices for multi-tenant vector workloads"

Other improvements

Beyond the shell and vector search, a handful of other improvements round out the GA release and make the emulator easier to plug into real workflows.

Health probe endpoint

The emulator exposes dedicated health endpoints on port 8080: /alive for liveness, /ready for readiness, and /status for detailed status.

Previously, tests, CI jobs and other components depended on the System is now fully ready to accept requests log line to know when the gateway was up. That works but is brittle. An HTTP probe is a better fit. The legacy log message is still emitted for backward compatibility, but we recommend moving to the probe.

OpenTelemetry support

The emulator supports the OpenTelemetry Protocol (OTLP) for exporting telemetry. With --enable-otlp (or ENABLE_OTLP_EXPORTER=true), it emits request rates, query execution times, resource utilization, and error rates that you can pipe into any OTLP-compatible backend. For quick debugging without a collector, --enable-console (or ENABLE_CONSOLE_EXPORTER=true) prints telemetry to stdout. Conditional TLS is supported on the OTLP exporter, so the emulator can be wired into observability stacks that require secure transport. Detailed setup and examples live in the GitHub repo.

Broader feature and API coverage

The emulator is designed to be used with the standard Azure Cosmos DB SDKs and supports common local development scenarios. The supported API surface has grown to cover common app requirements: change feed, batch operations, JOINs, range and aggregate queries, subdocument queries, hierarchical partition keys, TTL, and an expanded set of string and array operators.

For example, you can now query deeply nested properties and guard against missing fields in a single statement:

SELECT c.username, c.profile.contact.phone
FROM c
WHERE IS_DEFINED(c.profile.contact)

See the preview enhancements post for more query walkthroughs across JOINs, operators, and subdocuments.

A few endpoints that aren't core to data operations (offers, users, permissions, etc.) are now accepted as no-ops. They return valid HTTP status codes but don't perform the underlying operation, so application code that happens to touch them won't break when pointed at the emulator.

Get started

The Azure Cosmos DB Linux emulator is generally available today. Pull the GA image and you have a local Azure Cosmos DB endpoint to develop and test against, right on your machine and without an Azure subscription.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest

If you hit an issue or have a feature request, please open it on the GitHub repository.

Introducing OmniVec: An Open-Source Embedding Platform for AI Apps on Azure

Abhishek Gupta — Tue, 23 Jun 2026 18:13:38 +0000

Originally posted on https://devblogs.microsoft.com/cosmosdb/introducing-omnivec-an-open-source-embedding-platform-for-ai-apps-on-azure/

Today we are open-sourcing OmniVec, a platform for building and operating the embedding pipelines that keep the vector representation of your operational data in sync as it changes. You register data sources, embedding model(s), vector stores (destination), and OmniVec does the rest: initial backfill, change tracking, model invocation to generate, and writing them back to your vector store. We are shipping this with support for Azure Cosmos DB, PostgreSQL, SQL Server (source and destination), and Azure Blob Storage (destination). You deploy OmniVec in your own Azure subscription, and use the web UI, CLI, or the REST API to manage it.

Most AI applications end up building the same plumbing to keep that vector representation in sync: a change-capture process on the source, a consumer pool that generates embeddings, retry and backfill logic, dead-letter handling, and the operational work to keep it all running. OmniVec collapses that stack into four configurable components: a source, a model, a destination, and a pipeline that wires the first three together.

Deep Dive

Deploying OmniVec into your Azure subscription provisions multiple Azure resources, including an Azure Kubernetes Service (AKS) cluster that hosts the OmniVec services (API, controller, and workers), an Azure Cosmos DB account for pipeline metadata, job state, and progress metrics, and an Azure Container Registry that stores the service images AKS pulls from, and more. You control the choices that affect cost and capacity, such as the embedding model (hosted Azure OpenAI or a self-hosted GPU model), the AKS node size and count, and whether to provision a GPU pool, etc.

Key concepts

OmniVec exposes the following core primitives:

Source: A system OmniVec reads records from. The source definition tells OmniVec how to connect to it and how to track changes on it.
Model: The embedding model OmniVec calls to turn record content into a vector. A model registration captures the provider, model name, endpoint, and credentials, and the runtime calls it with batching and retries.
Destination: A vector store where the generated embeddings are written, alongside (or as an update to) the originating record.
Pipeline: The binding that ties a source, a model, and a destination together. It also declares which source fields to embed and which destination field receives the vector.

Architecture at a glance

OmniVec runs as a set of services on Azure Kubernetes Service:

REST API: A FastAPI control plane that holds the configuration of sources, models, destinations, and pipelines, and exposes it over REST. The CLI and the web UI use this API behind the scenes.
Ingestion: Watches each source for changes and queues up the records that need embedding. How it tracks changes depends on the source: the change feed for Azure Cosmos DB, blob events for Azure Blob Storage, and CDC for SQL Server and PostgreSQL.
Workers: A horizontally scalable pool on compute that pulls records off the queue, calls the embedding model, and writes the resulting embedding to the destination.
Model routing layer: A unified entry point in front of the embedding models. It lets a pipeline call either an external provider like Azure OpenAI or a self-hosted GPU model.
Metadata store: An Azure Cosmos DB account that the deployment provisions for you. It holds pipeline definitions, job state, progress metrics, etc.

OmniVec in action

Let's put OmniVec to work end to end. In this walkthrough, you will:

deploy it into your subscription
point it at an Azure Cosmos DB container
wire up a pipeline to automatically generate vector embeddings
then run vector search over this data

We use Azure Cosmos DB as both the source and the destination here as an example, but this applies to any supported combination of sources, models, and destinations.

Prerequisites

Before you start, make sure you have:

An Azure subscription with permissions to create resource groups, an AKS cluster, an ACR, and an Azure Cosmos DB account.
An embedding model. This walkthrough uses an Azure OpenAI embedding model deployed in Microsoft Foundry. Deploy one in your subscription and note the endpoint, model name, and API key. You'll configure them in OmniVec later.
CLI tools:
- Azure Developer CLI (azd) for deployment.
- Azure CLI (az) to setup Azure Cosmos DB (but you can also do it directly via the Azure portal).
- kubectl and Helm
- OmniVec CLI from the OmniVec releases page to manage sources, destinations, pipeline, and config.

Then clone the quickstart repo, which has the sample data and seed script used later:

git clone https://github.com/AzureCosmosDB/omnivec-cosmosdb-quickstart

cd omnivec-cosmosdb-quickstart

Deploy and configure OmniVec

Create a new azd environment for the deployment. Pick an ENV_NAME (it becomes part of resource names), and choose a LOCATION that supports AKS and Azure Cosmos DB in your subscription:

export ENV_NAME="my-omnivec"
export LOCATION="westus2"
export SUBSCRIPTION_ID="<your-subscription-id>"

azd env new "$ENV_NAME" --location "$LOCATION" --subscription "$SUBSCRIPTION_ID"

Configure the deployment:

azd env set OMNIVEC_METADATA_STORE "cosmosdb-provisioned"
azd env set OMNIVEC_ENABLE_BLOB_SOURCE "false"
azd env set OMNIVEC_SYSTEM_NODE_VM_SIZE "Standard_D2ds_v5"
azd env set OMNIVEC_SYSTEM_NODE_COUNT 2
azd env set OMNIVEC_GPU_NODE_VM_SIZE ""
azd env set OMNIVEC_GPU_NODE_COUNT 0
azd env set OMNIVEC_BUILD_MODE "acr"
azd env set OMNIVEC_BUILD true

OMNIVEC_METADATA_STORE provisions a dedicated Azure Cosmos DB account for OmniVec's own pipeline metadata, job state, and progress metrics.
OMNIVEC_ENABLE_BLOB_SOURCE is off because this walkthrough only uses Azure Cosmos DB as a source; turn it on if you need Azure Blob Storage.
Size the AKS system pool with OMNIVEC_SYSTEM_NODE_VM_SIZE and OMNIVEC_SYSTEM_NODE_COUNT based on your expected workload.
The GPU pool (OMNIVEC_GPU_NODE_VM_SIZE, OMNIVEC_GPU_NODE_COUNT) is empty here because we're calling a hosted Azure OpenAI model; set them if you want to run self-hosted embedding models inside the cluster.
OMNIVEC_BUILD_MODE=acr builds the service images in the provisioned ACR, and OMNIVEC_BUILD=true triggers that build as part of this deployment.

You only need one command for deployment:

azd up

This takes a few minutes. It provisions the AKS cluster, Azure Cosmos DB account, and ACR, builds the OmniVec service images in ACR, and installs the Helm chart onto the cluster. When it finishes, you'll see a summary similar to the following (your values will differ):

//..... redacted
Instance ID: my-omnivec-dhmzlhlv4lk7s
Environment: my-omnivec
AKS Cluster: omnivec-aks-dhmzlhlv4lk7s
ACR Registry: omnivecacrdhmzlhlv4lk7s.azurecr.io
CosmosDB: https://omnivec-cosmos-dhmzlhlv4lk7s.documents.azure.com:443/
Admin Token: <admin-token>

OmniVec FQDN: http://my-omnivec-dhmzlhlv4lk7s.westus2.cloudapp.azure.com/ui
OmniVec IP: http://<public-ip>/ui

Health Check: http://my-omnivec-dhmzlhlv4lk7s.westus2.cloudapp.azure.com/health

Save the admin token and the OmniVec FQDN. You'll use both in the next step to point the CLI at this deployment. You can also open the FQDN in a browser to confirm the web UI is up.

The rest of this walkthrough uses the CLI (the web UI exposes the same operations if you prefer to click through it). Point it at your deployment and authenticate:

export SERVER_URL=<e.g. http://my-omnivec-dhmzlhlv4lk7s.westus2.cloudapp.azure.com/>
export ADMIN_TOKEN=<admin-token>

omnivec config set server $SERVER_URL
omnivec auth login --token $ADMIN_TOKEN

Use the bare FQDN, without the /ui suffix.

Confirm the CLI is wired up:

omnivec config view

Finally, register your Azure OpenAI embedding model with OmniVec. Pipelines reference models by the name you give them here:

export FOUNDRY_ENDPOINT=<your-foundry-endpoint>
export FOUNDRY_MODEL_NAME=<e.g. text-embedding-3-small>
export FOUNDRY_API_KEY=<your-foundry-api-key>

omnivec model add \
--name demo-foundry-oai-model \
--type azure-openai \
--model $FOUNDRY_MODEL_NAME \
--endpoint $FOUNDRY_ENDPOINT \
--api-key $FOUNDRY_API_KEY

Set up Azure Cosmos DB

You need an Azure Cosmos DB account, database, and container that OmniVec will read from and write embeddings to. This walkthrough uses the same container as both source and destination. If you don't already have an Azure Cosmos DB account, create one before continuing.

az login
az account set --subscription "$SUBSCRIPTION_ID"

Your signed-in user needs permission to create a database and container on the account. The built-in Cosmos DB Operator role (or any role granting Microsoft.DocumentDB/databaseAccounts/sqlDatabases/* and .../containers/* write actions) is sufficient. Account Contributor or Owner also works.

Set the names you'll use throughout the rest of the walkthrough:

export RG=<your-resource-group>
export COSMOS_ACCOUNT=<your-cosmos-account>
export COSMOS_DB=omnivec-demodb
export COSMOS_CONTAINER=demo-container

Create the database:

az cosmosdb sql database create \
--account-name $COSMOS_ACCOUNT \
--resource-group $RG \
--name $COSMOS_DB

Create the container with a vector embedding policy and a DiskANN vector index on /embedding. The 1536 dimension matches text-embedding-3-small; change it if you registered a different model:

az cosmosdb sql container create \
--account-name $COSMOS_ACCOUNT \
--resource-group $RG \
--database-name $COSMOS_DB \
--name $COSMOS_CONTAINER \
--partition-key-path /id \
--vector-embeddings '{"vectorEmbeddings":[{"path":"/embedding","dataType":"float32","dimensions":1536,"distanceFunction":"cosine"}]}' \
--idx '{"indexingMode":"consistent","automatic":true,"includedPaths":[{"path":"/*"}],"excludedPaths":[{"path":"/\"_etag\"/?"},{"path":"/embedding/*"}],"vectorIndexes":[{"path":"/embedding","type":"diskANN"}]}'

Now seed it with sample data. The seed script uses DefaultAzureCredential, so first grant your signed-in user the Cosmos DB Built-in Data Contributor role on the Azure Cosmos DB account:

export USER_PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv)

az cosmosdb sql role assignment create \
--account-name "$COSMOS_ACCOUNT" \
--resource-group "$RG" \
--role-definition-id "00000000-0000-0000-0000-000000000002" \
--principal-id "$USER_PRINCIPAL_ID" \
--scope "/"

Then install the sample app's dependencies and run the seed script (it reads COSMOS_ACCOUNT, COSMOS_DB, and COSMOS_CONTAINER from the environment):

cd sample-app
python3 -m venv .venv && source .venv/bin/activate

pip install -r requirements.txt
python insert_sample_data.py

You should now have 100 product documents in the container, each with name and description fields.

Grant OmniVec access to Azure Cosmos DB

OmniVec pods authenticate to Azure Cosmos DB using a managed identity, not a connection string. Before you create a source or destination, grant that identity two roles on the Azure Cosmos DB account:

Data plane (Cosmos DB Built-in Data Contributor): read source documents and write embeddings.
Control plane (Cosmos DB Account Reader Role): read the account-level metadata and vector policies that the change-feed processor inspects at startup. Skipping it causes pipeline failures with a readMetadata error.

First, find the principal ID of the OmniVec workload identity. It lives in the OmniVec deployment's resource group (not the Azure Cosmos DB account's $RG). That resource group has several managed identities, so filter by the client ID that azd exported rather than picking the first one:

export OMNIVEC_RG=$(azd env get-value AZURE_RESOURCE_GROUP)

export OMNIVEC_PRINCIPAL_ID=$(az identity list -g "$OMNIVEC_RG" \
--query "[?clientId=='$(azd env get-value AZURE_IDENTITY_CLIENT_ID)'].principalId" -o tsv)

Grant the data-plane role:

az cosmosdb sql role assignment create \
--account-name "$COSMOS_ACCOUNT" \
--resource-group "$RG" \
--role-definition-id "00000000-0000-0000-0000-000000000002" \
--principal-id "$OMNIVEC_PRINCIPAL_ID" \
--scope "/"

Grant the control-plane role:

az role assignment create \
--assignee "$OMNIVEC_PRINCIPAL_ID" \
--role "Cosmos DB Account Reader Role" \
--scope "$(az cosmosdb show -n "$COSMOS_ACCOUNT" -g "$RG" --query id -o tsv)"

Wait 1–2 minutes for the assignments to propagate before moving on.

Wire up the pipeline

With Azure Cosmos DB ready and OmniVec authorized, the rest of the setup is three OmniVec resources: a source, a destination, and a pipeline that binds them to the model you registered earlier.

omnivec source create --name demo-cosmosdb-source \
--type cosmosdb \
--config "{\"endpoint\":\"https://$COSMOS_ACCOUNT.documents.azure.com:443/\",\"database\":\"$COSMOS_DB\",\"container\":\"$COSMOS_CONTAINER\",\"auth_type\":\"managed-identity\"}"

omnivec destination create --name demo-cosmosdb-destination \
--type cosmosdb-vector \
--config "{\"endpoint\":\"https://$COSMOS_ACCOUNT.documents.azure.com:443/\",\"database\":\"$COSMOS_DB\",\"container\":\"$COSMOS_CONTAINER\",\"auth_type\":\"managed-identity\"}"

The pipeline needs three IDs: source, destination, and model. Grab the source and destination IDs from omnivec source list and omnivec destination list (they look like src-… and dst-…). For the model, the registered name (demo-foundry-oai-model) isn't the ID; the internal mdl-ext-* ID is what the pipeline expects:

export SOURCE_ID=<src-id-from-source-list>
export DESTINATION_ID=<dst-id-from-destination-list>
export MODEL_ID=$(omnivec model test demo-foundry-oai-model | sed 's/^OK: Model test returned: //' | jq -r '.id')

Create the pipeline. --content-fields tells OmniVec which fields on each source document to embed (concatenated), --embedding-field is where the resulting vector lands on the destination document, and --vector-index-path is the path the destination container's vector index looks at (it should match the path you set in the az cosmosdb sql container create step):

omnivec pipeline create --name demo-cosmosdb-pipeline \
--source $SOURCE_ID --destination $DESTINATION_ID --model $MODEL_ID \
--content-fields name,description --embedding-field embedding \
--vector-index-path /embedding --processing-mode inline

You should see something like:

OK: Pipeline created: pip-94348d5e (status: paused)

New pipelines start paused. Grab the pipeline ID from the output (or from omnivec pipeline list) and resume it:

export PIPELINE_ID=<pip-id-from-create-output>
omnivec pipeline resume $PIPELINE_ID

Check the pipeline's progress:

omnivec pipeline show $PIPELINE_ID

Once the workers have processed the seed data, you'll see output similar to the following (truncated for brevity):

Pipeline
ID: pip-94348d5e
Name: demo-cosmosdb-pipeline
Status: active
...

Stats
Documents Embedded: 100
Source Docs: 100
Completion: 100.0%
Failed: 0
Pending: 0
...

Completion: 100.0% means every seed document now has an embedding written back to its embedding field. From this point on, any insert or update to the source container flows through the change feed and gets re-embedded automatically.

Run vector search

The embeddings are in place, so you can run vector search against the destination. Use the OmniVec CLI's search command with a natural-language query:

omnivec search "warm waterproof hiking pants" --index $DESTINATION_ID --top-k 3

Try another query to confirm it generalizes beyond the obvious matches:

omnivec search "lightweight running shoes" --index $DESTINATION_ID --top-k 3

The web UI ships with a vector search playground that calls the same API.

Wrapping up

The walkthrough above used Azure Cosmos DB as both source and destination, with a hosted Azure OpenAI embedding model, but you can mix and match sources, destinations, and models. It supports a wide range of scenarios – a common use case is pointing OmniVec at an Azure Blob Storage container full of PDFs and other documents and writing the embeddings into Azure Cosmos DB.

OmniVec is on GitHub at AzureCosmosDB/OmniVec. It is a public preview, so expect changes as it matures. Clone it, deploy it into your own subscription, and try it on one of your own datasets. Bug reports, feedback, and requests are all welcome through GitHub issues. And if you build something interesting on top of it, we'd love to hear about that too!

Announcing the Public Preview of Integrated Embeddings in Azure Cosmos DB: Build AI Apps With Embeddings That Stay in Sync

Abhishek Gupta — Tue, 23 Jun 2026 18:04:23 +0000

Originally posted on https://devblogs.microsoft.com/cosmosdb/announcing-the-public-preview-of-integrated-embeddings-in-azure-cosmos-db-build-ai-apps-with-embeddings-that-stay-in-sync/

AI applications built on Azure Cosmos DB depend on embeddings for grounded results. Keeping them in sync with your data is the hard part: it means building and operating a separate data pipeline to track changes, call an embedding model, and write the results back to Azure Cosmos DB. In practice, that pipeline also has to handle failures and retries, throttling, scaling, and monitoring as your data and traffic grow.

Integrated Embeddings in Azure Cosmos DB, now in Public Preview, removes that heavy lifting. Azure Cosmos DB automatically generates and maintains the embeddings for you as items are written and updated, so the vectors stored alongside your items always reflect the current state of your data. You configure it by specifying the source properties to embed, the Microsoft Foundry embedding model to use, and the path where the generated embeddings are stored, and then focus on building AI applications, such as Retrieval-Augmented Generation (RAG), on top of your data.

How Integrated Embeddings works

Integrated Embeddings is configured through a new embeddingSource block in the container vector policy. The rest of the policy (vector path, dimensions, distance function) stays the same. This block tells Azure Cosmos DB three things:

What to embed: one or more item properties listed in sourcePaths. When you list multiple paths, the values are combined into a single input for the embedding model. An item is re-embedded only when one of these properties changes.
What to embed with: a Microsoft Foundry embedding model deployment, identified by deploymentName, modelName, and endpoint.
How to authenticate: authType: "Entra" — currently the only supported value.

For example, here is a vector policy that embeds the /text property of each item using text-embedding-3-small and writes the resulting vector to /embedding:

{
  "vectorEmbeddings": [
    {
      "path": "/embedding",
      "dataType": "float32",
      "dimensions": 1536,
      "distanceFunction": "cosine",
      "embeddingSource": {
        "sourcePaths": ["/text"],
        "deploymentName": "text-embedding-3-small",
        "modelName": "text-embedding-3-small",
        "endpoint": "https://<foundry-resource-name>.openai.azure.com/",
        "authType": "Entra"
      }
    }
  ]
}

At the time of Public Preview, the following Azure OpenAI embedding models are supported through Microsoft Foundry: text-embedding-3-small, text-embedding-3-large, and text-embedding-ada-002.

Integrated Embeddings in action

To get started with a simple example, try the quickstart in the docs. It walks through creating a container with an embeddingSource policy, inserting a few sample items, and verifying that Azure Cosmos DB writes an embedding to each item.

The walkthrough below is a longer, end-to-end example. You'll load a dataset of outdoor products into Azure Cosmos DB, let Integrated Embeddings generate the vectors, and then run a vector search against the container.

Before you start, complete the Integrated Embeddings prerequisites from the documentation: vector search, change feed mode enabled, and a Microsoft Foundry model deployment. The Azure Cosmos DB account's managed identity also needs the Cognitive Services OpenAI User role on the Microsoft Foundry resource so it can call the model.

In addition, the principal you sign in as needs two role assignments on the Azure Cosmos DB account so the sample app can act on your behalf:

Cosmos DB Operator (Azure RBAC) to create the database and container through Azure Resource Manager.
Cosmos DB Built-in Data Contributor (Azure Cosmos DB RBAC) to upsert and read items. See how to assign these roles in the getting started section.

In step 4 the sample app calls the Microsoft Foundry embedding deployment directly to embed the query string. For simplicity, the sample uses an API key for this call (Integrated Embeddings itself uses Entra ID, as configured in the vector policy). Make sure you have the API key for your Foundry resource ahead of time and have it ready to drop into .env file.

Set up the sample application

The sample app is written in Python; you'll need Python 3.x installed locally. Clone the GitHub repository and install dependencies:

git clone https://github.com/abhirockzz/integrated-embeddings-sample
cd integrated-embeddings-sample

# create a virtual environment and install dependencies
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Copy .env.example to .env and fill in your Azure Cosmos DB account endpoint and Microsoft Foundry deployment details:

cp .env.example .env
# edit .env

Sign in to the Azure CLI so the sample app can authenticate to Azure Cosmos DB and Microsoft Foundry using your identity:

az login

Step 1: Create the database and container

This script creates the database and a container along with a vector embedding policy that has an embeddingSource block with source path /description, model text-embedding-3-small, and output stored at /embedding. It adds a quantizedFlat vector index on /embedding so you can query the embeddings in step 4.

Run the script:

python create_db_and_container.py

The container is provisioned with autoscale 1,000 RU/s.

Step 2: Insert sample data

This script upserts 100 outdoor-product items from items.json into the container. Each item has an id, a name, a description, a category, tags, and a few other fields — but only /description is sent to the embedding model, per the policy you set in step 1.

python insert_sample_data.py

You'll see one line per item as it's inserted. None of the items have an embedding field yet; Azure Cosmos DB picks up the changes and generates embeddings asynchronously.

Step 3: Verify embeddings in the Azure portal

Open the Azure portal, navigate to your Azure Cosmos DB account → Data Explorer, open the container you created in step 1, and run the query below.

SELECT VALUE COUNT(1) FROM c WHERE IS_DEFINED(c.embedding)

When the count reaches 100, all embeddings have been generated.

Step 4: Run a vector search

Now that every item has an embedding, you can run a vector search against the container. The script embeds your query string by calling the same Microsoft Foundry embedding model deployment that Azure Cosmos DB used for the items (using the FOUNDRY_API_KEY you set in .env file), then runs a VectorDistance() query to find the closest items by cosine similarity.

python vector_search.py "I need to stay warm on a cold ski trip"

Running this returns something similar to the following results. You should see a mix of ski-related gloves and jackets along with some cold-weather sleeping bags — all relevant to the concept of "staying warm on a cold ski trip," even though none of the item descriptions contain those exact words.

Query: 'I need to stay warm on a cold ski trip'
Top 5 results:

1. Studio Talon Insulated Storm Glove
category=Winter Sports, Gloves, Insulated Gloves score=0.4974
2. Prairie Nomad Waterproof Resort Shell Jacket
category=Skiing, Outerwear, Shell Jackets score=0.4923
3. Ridge Drift Touchscreen Insulated Ski Glove
category=Winter Sports, Gloves, Insulated Gloves score=0.4855
4. Everest All-Weather Short 850 Fill Trail Sack
category=Camping, Sleeping Bags, Down Bags score=0.4756
5. Brook Shift 850-Fill Trail Sack Sleeping Bag
category=Camping, Sleeping Bags, Down Bags score=0.4570

A couple more queries to give you a feel for what's possible.

Try a planning-style query. Instead of gear, you'll get trip-planning books and trail guides:

python vector_search.py "plan a long hike in unfamiliar terrain"

Or try a more specific query. The top result is a one-person shelter, with closely related tents below it:

python vector_search.py "easy to set up shelter for one person"

You can use --top-k to control how many results are returned (defaults to 5):

python vector_search.py "lightweight cookware for backpacking" --top-k 3

Pure vector search returns the most semantically similar items but doesn't account for exact keyword matches. For queries where both semantic intent and specific terms matter, Azure Cosmos DB for NoSQL supports hybrid search, which combines vector similarity and full-text (BM25) ranking using Reciprocal Rank Fusion. You can also add a WHERE clause to narrow results to a specific category or tag. All of these queries run against the same embeddings that Integrated Embeddings generates and keeps in sync.

Build a simple RAG agent on top of the data

Retrieval-Augmented Generation (RAG) is a pattern where a language model answers user questions by first retrieving relevant content from a knowledge base, then using that content as grounding for its response. For RAG over your Azure Cosmos DB data, the retrieval step is vector search and the knowledge base is your container.

To turn the vector search into a Retrieval-Augmented Generation (RAG) application, we wrap it as a tool that a language model can call. We use a simple LangChain agent with a retrieve_context tool that embeds the user's query and runs the same VectorDistance() search you saw in step 4. The agent decides when to call the tool, reads the results, and answers in natural language. To keep the agent grounded in your data, the system prompt instructs the model to recommend only products that appear in the retrieved results and to ignore any instructions contained in the retrieved text.

The agent needs a large language model (LLM). Deploy the model (for example gpt-5.4) in your Microsoft Foundry resource and set FOUNDRY_CHAT_DEPLOYMENT in .env to the deployment name. The agent uses the same FOUNDRY_API_KEY for both chat and query-time embedding calls.

Once you start the agent, it opens a simple interactive prompt where you can ask catalog-style questions:

python rag_agent.py

Try out a few queries. For example, ask about a product category and the agent surfaces every relevant item:

You: What sleeping bags do you have for cold nights?

The agent calls the retrieval tool, gets back the three cold-weather down bags in the catalog, and lists them with their shared 850-fill warmth and use cases.

Ask about a specific product feature and the agent filters the results for you:

You: What ski goggles do you have with a magnetic lens?

Vector search returns all three ski goggles in the catalog, but the agent recommends only the two that actually have a magnetic lens system. This is the agent + RAG advantage on top of pure vector search: broad retrieval, narrow reasoning.

Integrated Embeddings keeps the item embeddings in sync with the source data automatically, so the agent's retrieval stays accurate as products are added, updated, or removed. You don't have to build or run a separate embedding pipeline to keep the index fresh.

Other ways to configure Integrated Embeddings

You can embed more than one property at a time by listing multiple paths in sourcePaths. Azure Cosmos DB concatenates the values into a single input for the embedding model. This is useful when no single field carries enough information. For example, a product title is usually too short on its own, but combining /title and /description produces a richer vector.

{
  "vectorEmbeddings": [
    {
      "path": "/embedding",
      "dataType": "float32",
      "dimensions": 1536,
      "distanceFunction": "cosine",
      "embeddingSource": {
        "sourcePaths": [
          "/title",
          "/description"
        ],
        "deploymentName": "text-embedding-3-small",
        "modelName": "text-embedding-3-small",
        "endpoint": "https://<foundry-resource-name>.openai.azure.com/",
        "authType": "Entra"
      }
    }
  ]
}

You can also generate multiple embeddings by adding more entries to vectorEmbeddings. Each entry has its own path, model, and source properties, and Azure Cosmos DB maintains all of the vectors in parallel.

The example below generates /desc_embedding from /description using text-embedding-3-large, and /title_embedding from /title using text-embedding-3-small.

{
  "vectorEmbeddings": [
    {
      "path": "/desc_embedding",
      "dataType": "float32",
      "dimensions": 3072,
      "distanceFunction": "cosine",
      "embeddingSource": {
        "sourcePaths": [
          "/description"
        ],
        "deploymentName": "text-embedding-3-large",
        "modelName": "text-embedding-3-large",
        "endpoint": "https://<foundry-resource-name>.openai.azure.com/",
        "authType": "Entra"
      }
    },
    {
      "path": "/title_embedding",
      "dataType": "float32",
      "dimensions": 1536,
      "distanceFunction": "cosine",
      "embeddingSource": {
        "sourcePaths": [
          "/title"
        ],
        "deploymentName": "text-embedding-3-small",
        "modelName": "text-embedding-3-small",
        "endpoint": "https://<foundry-resource-name>.openai.azure.com/",
        "authType": "Entra"
      }
    }
  ]
}

What's supported in Public Preview

You can configure Integrated Embeddings today through the Azure Cosmos DB SDK (for Python) with key-based authentication, or through the Azure Cosmos DB management SDK (Python and JavaScript) with Microsoft Entra ID. Both options are demonstrated in the documentation. Support across the Azure CLI, ARM, Bicep, and other SDKs will be added in subsequent releases.

Azure Portal support for configuring and managing Integrated Embeddings (in Data Explorer) is not available yet. As we work on adding this, you can configure Integrated Embeddings through one of the SDK options.

Get started

With Integrated Embeddings, Azure Cosmos DB keeps vector embeddings in sync with your data automatically, so you no longer need to build and operate separate pipelines to do it. Integrated Embeddings uses your existing Microsoft Foundry and Azure Cosmos DB resources, so the only costs are the Foundry inference calls and the request units used to read the change feed and write embeddings back to your items.

To start building:

Follow the quickstart to create a container with an embeddingSource policy and insert your first items.
Clone the sample app to run the full walkthrough above on your own data.
Read the Integrated Embeddings documentation for the complete reference.

We'd love your feedback during preview! Reach out to us at CosmosSearch@Microsoft.com.

A Chrome Extension That Talks to Your Database

Abhishek Gupta — Mon, 23 Mar 2026 06:55:35 +0000

Cosmos DB Sidekick is a Chrome extension built with the GitHub Copilot SDK and the Azure Cosmos DB JavaScript SDK. The GitHub Copilot SDK lets you embed Copilot's AI capabilities directly into your apps — available for Go, Python, TypeScript, and .NET.

It sits alongside the Cosmos DB vNext emulator Data Explorer and lets you ask questions in plain English. It writes the queries, runs them, and shows results. No copy-pasting SQL, no switching between tabs.

You can find the code on GitHub.

Here is a demo of the app in action:

What can you actually do with it?

Use natural language to query data. In response to something like "Find all orders over $100 from the last month" — the extension figures out the schema, generates a SQL query, runs it against your emulator, and streams back the results.

Write data too. Need test data? Ask it to "Add 10 test users to the users container" and it generates realistic documents with proper id fields and partition keys, then upserts them.

It knows what you're looking at. When the Cosmos DB Data Explorer is open, the extension auto-detects which database and container you're browsing. A context bar shows something like 📂 ordersDb › customers, and your questions automatically target that data. Switch to a different container in the Data Explorer — the context follows.

Conversations persist. You can have multi-turn conversations, switch between sessions, and pick up where you left off. Close the side panel, reopen it — your chat history is still there.

How the Copilot SDK makes this work

Under the hood, the extension is powered by the GitHub Copilot SDK. The architecture is straightforward:

┌─────────────────────┐
│  Chrome Extension   │
│    (side panel)     │
└────────┬────────────┘
         │ HTTP + SSE
┌────────▼────────────┐       ┌──────────────────────┐
│   Node.js Sidecar   │──────▶│  GitHub Copilot SDK  │
│                     │◀──────│  (LLM + tool calls)  │
└────────┬────────────┘       └──────────────────────┘
         │ Cosmos DB JS SDK
┌────────▼────────────┐
│  Cosmos DB vNext    │
│     Emulator        │
└─────────────────────┘

The sidecar is a lightweight Node.js server that acts as the bridge. It creates a CopilotClient, manages chat sessions, and, (most importantly) defines tools that the LLM can call autonomously. Tools are the key to the agentic behavior — they let the model interact with the external world (in this case, your Cosmos DB instance) in a structured way:

list_databases — discover what databases exist
list_containers — see containers and partition keys in a database
sample_documents — grab sample docs to understand the schema
run_query — execute a read-only SQL query
upsert_items — insert or replace documents

For example, what happens when you ask a question like "What does the schema look like?". You didn't tell it which database to query. You didn't tell it to sample documents. But the LLM chains the tools together on its own — lists databases, picks the one from your context, lists containers, samples documents, then describes what it found. That's the agentic part.

Same applies to query generation and execution - you define the tools, the SDK handles the orchestration, and the model decides the sequence.

Here's what a tool definition looks like (simplified):

{
  name: "run_query",
  description: "Execute a read-only SQL query against a Cosmos DB container.",
  parameters: {
    type: "object",
    properties: {
      database:  { type: "string", description: "The database name" },
      container: { type: "string", description: "The container name" },
      query:     { type: "string", description: "The SQL query to execute" },
    },
    required: ["database", "container", "query"],
  },
  handler: async (args) => {
    return await runQuery(args.database, args.container, args.query);
  },
}

The SDK takes care of the rest — passing tool definitions to the model, routing tool calls to your handlers, feeding results back into the conversation, and streaming the final response.

Streaming is built into the session. The sidecar subscribes to session events and forwards them over SSE to the Chrome extension, so responses appear token-by-token in the chat panel. Creating a streaming chat session is a few lines:

const session = await client.createSession({
  model: "gpt-4.1",
  systemMessage: { mode: "append", content: SYSTEM_PROMPT },
  tools: getTools(),
  streaming: true,
  onPermissionRequest: approveAll,
});

Session persistence comes for free too. The SDK's listSessions() and resumeSession() let the extension show chat history and restore previous conversations — the sidecar doesn't need its own storage layer.

Context-aware — no configuration needed

The extension watches which database and container you have open in the Data Explorer and automatically uses that as context. Ask "show me the top 10 documents" and it knows exactly where to look — no need to specify the target every time.

Try it out

The whole thing runs locally — Chrome extension + a Node.js sidecar + the Cosmos DB vNext emulator in Docker. You'll need GitHub Copilot and the Copilot CLI set up for auth.

Follow the steps in the GitHub repo to get it running, and start chatting with your database in natural language. It's a fun demo of how the GitHub Copilot SDK can turn a simple extension into an intelligent agent that understands your data and helps you interact with it seamlessly.

The bigger picture

Cosmos DB Sidekick is one specific use case, but the pattern behind it is general. Define a few tools, hand them to the Copilot SDK, and you get an agent that can reason about when and how to use them — chaining calls, handling errors, and streaming results back to the user. The SDK handles sessions, tool orchestration, and model access; you just bring the domain logic.

That same pattern works for any data source, any API, any workflow. A CLI that talks to your CI/CD pipeline. A Slack bot that queries your observability stack. A dashboard that lets non-technical teammates explore production metrics in plain English. The building blocks are the same: tools, a system prompt, and a session.

If you're looking for a starting point, the Copilot SDK has samples for Go, Python, TypeScript, and .NET. Pick your stack and start building.

DocumentDB on Kubernetes: Resilient, Highly Available Databases with Automatic Failover

Abhishek Gupta — Tue, 03 Mar 2026 08:06:34 +0000

DocumentDB is an open-source MongoDB-compatible database built on PostgreSQL that provides a familiar interface while leveraging PostgreSQL's reliability and extensibility. The DocumentDB Kubernetes Operator brings this database to Kubernetes environments by extending the platform with custom resources. The operator manages DocumentDB clusters declaratively, handling deployment, scaling, upgrades, and high availability scenarios automatically.

The DocumentDB Kubernetes Operator provides multiple levels of high availability, each addressing a different failure domain. Local HA deploys multiple database instances within a single Kubernetes cluster with automatic failover in seconds, protecting against pod and node failures. For further resilience, you can configure availability zone spreading so that replicas land in different AZs, allowing the cluster to survive a full zone outage without manual intervention. Beyond a single cluster, the operator supports multi-region HA across Azure regions (using KubeFleet) and multi-cloud HA across providers like Azure, AWS, and GCP (using Istio). Both use physical WAL replication with manual failover via kubectl documentdb promote. These levels are composable: a production deployment can combine all of them.

This post focuses on local HA, the foundational layer, and walks through automatic failover in action.

Highly Available DocumentDB deployment on Kubernetes

In single-instance database deployments, any failure (such as a pod crash, node issue, or planned upgrade) may result in downtime. Local high availability (HA) solves this problem by deploying multiple database instances within a single Kubernetes cluster. The operator creates one primary instance that handles all client operations, along with multiple replica instances that are continuously replicated via asynchronous WAL streaming. When the primary fails, a replica is automatically promoted to become the new primary, ensuring your application experiences minimal disruption.

Local HA is ideal when you need resilience within a single region without the complexity of multi-region deployments. It's a cost-effective solution for development and staging environments where you want to validate failover behavior without cloud distribution costs, as well as for production workloads that require automatic recovery from infrastructure failures. For cross-region disaster recovery scenarios, the operator also supports multi-cluster replication features.

Architecture Overview

DocumentDB's local HA leverages CloudNativePG (CNPG) as its underlying PostgreSQL foundation. CNPG handles WAL-based streaming replication and automatic failover orchestration, while DocumentDB adds the MongoDB-compatible protocol layer on top.

Here are the key components:

CNPG Cluster: Manages PostgreSQL replication (1 primary + N replicas) with WAL-based streaming
DocumentDB Gateway: A sidecar container injected into each PostgreSQL pod that translates MongoDB wire protocol to PostgreSQL DocumentDB extension calls
Kubernetes Services: Layered service architecture for different access patterns:
- Internal PostgreSQL services (port 5432): <cluster>-rw (primary), <cluster>-ro (replicas only), <cluster>-r (all instances — primary and replicas) - used for internal operations, metrics, and backups
- External Gateway service (port 10260): Routes MongoDB client traffic to the current primary by tracking the cnpg.io/instanceRole: primary label

When the primary fails, CNPG automatically detects the failure and promotes the most advanced replica to primary, updating the pod labels. The Kubernetes service automatically follows the new primary, keeping the external IP stable – no manual DNS changes required. The operator currently supports a maximum of 3 instances (instancesPerNode: 3), providing 1 primary + 2 replicas for optimal balance between availability, performance, and operational flexibility.

Let's see how this works in practice.

Setting Up the Test Environment

You need the following installed:

minikube, kubectl, and helm
Python (for the test client application)

Start your minikube cluster:

minikube start

Also make sure to clone the GitHub repository:

git clone https://github.com/abhirockzz/documentdb-local-ha-tutorial.git
cd documentdb-local-ha-tutorial

Install DocumentDB Operator

First, install cert-manager (required dependency):

helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true

Install the DocumentDB operator:

helm repo add documentdb https://documentdb.github.io/documentdb-kubernetes-operator

helm install documentdb-operator documentdb/documentdb-operator \
  --namespace documentdb-operator \
  --create-namespace \
  --wait

Verify the operator is running:

kubectl get deployment -n documentdb-operator

To check the operator version, run kubectl get pods -n documentdb-operator -o jsonpath='{.items[*].spec.containers[*].image}' && echo

Deploy Local HA Cluster

In a separate terminal, start the minikube tunnel. This creates a network route that enables LoadBalancer services to receive external IPs in your local minikube environment. The tunnel will assign an IP address to the DocumentDB service and route traffic from your host machine to the cluster, allowing the Python test client to connect:

minikube tunnel

# output:
✅  Tunnel successfully started

📌  NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ...

The local_ha.yaml file contains the complete configuration including namespace, credentials secret, and the DocumentDB resource with instancesPerNode: 3 to create a 3-instance HA cluster.

Deploy the cluster:

kubectl apply -f local_ha.yaml

Monitor the pod status. Wait for all pods to be running (this may take 1-2 minutes). In the meantime, you should see output similar to this, and eventually all 3 pods will reach Running status:

kubectl get pods -n documentdb-preview-ns -w

# output:

NAME                                 READY   STATUS            RESTARTS   AGE
documentdb-local-ha-1-initdb-ffrjf   0/1     PodInitializing   0          3s
documentdb-local-ha-1-initdb-ffrjf   1/1     Running           0          24s
documentdb-local-ha-1-initdb-ffrjf   0/1     Completed         0          25s
documentdb-local-ha-1-initdb-ffrjf   0/1     Completed         0          27s
documentdb-local-ha-1-initdb-ffrjf   0/1     Completed         0          27s
documentdb-local-ha-1                0/2     Pending           0          0s
documentdb-local-ha-1                0/2     Pending           0          0s
//....
documentdb-local-ha-3                2/2     Running           0          11s

Go to the minikube tunnel terminal, and verify the tunnel is now active for the DocumentDB service:

Starting tunnel for service documentdb-service-documentdb-local-ha.

You can verify the external IP assigned to the service (should be 127.0.0.1 in this case):

kubectl get svc -n documentdb-preview-ns

# output:
NAME                                     TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)           AGE
documentdb-local-ha-r                    ClusterIP      10.108.176.232   <none>        5432/TCP          4m47s
documentdb-local-ha-ro                   ClusterIP      10.111.154.246   <none>        5432/TCP          4m47s
documentdb-local-ha-rw                   ClusterIP      10.101.235.95    <none>        5432/TCP          4m47s
documentdb-service-documentdb-local-ha   LoadBalancer   10.97.24.62      127.0.0.1     10260:31829/TCP   4m57s

Ok now we are ready to test failover.

Test Failover

The test uses a Python client application that continuously performs write and read operations against the DocumentDB cluster. This includes retry logic with exponential backoff and tracks metrics like operation counts, failures, and downtime.

Note that the client uses retryWrites=True, which allows the MongoDB driver to automatically retry failed writes on the new primary — in very fast failovers, you may see zero reported failures as the driver absorbs the disruption transparently.

Start the client application:

pip install -r requirements.txt
python failover_test_read_write.py

Let it run for ~15 seconds to establish a baseline. You'll see continuous write and read operations succeeding.

//....
[CLIENT][10:29:28.051] ✓ Connected to DocumentDB
[CLIENT][10:29:28.138] ✓ W#1 (44ms) | R#1 (43ms) | Avg W:44ms R:43ms | Docs: 1
[CLIENT][10:29:28.688] ✓ W#2 (2ms) | R#2 (43ms) | Avg W:23ms R:43ms | Docs: 2
[CLIENT][10:29:29.234] ✓ W#3 (2ms) | R#3 (43ms) | Avg W:16ms R:43ms | Docs: 3
[CLIENT][10:29:29.783] ✓ W#4 (3ms) | R#4 (43ms) | Avg W:13ms R:43ms | Docs: 4
[CLIENT][10:29:30.327] ✓ W#5 (2ms) | R#5 (42ms) | Avg W:11ms R:43ms | Docs: 5
//.....

Trigger Failover

In a new terminal, identify the current primary (the primary/replica roles may vary in your deployment):

kubectl get pods -n documentdb-preview-ns -L cnpg.io/instanceRole

# output:
NAME                    READY   STATUS    RESTARTS   AGE   INSTANCEROLE
documentdb-local-ha-1   2/2     Running   0          14m   primary
documentdb-local-ha-2   2/2     Running   0          14m   replica
documentdb-local-ha-3   2/2     Running   0          14m   replica

Note which pod shows primary role, then delete it to simulate a failure:

kubectl delete pod <primary-pod-name> -n documentdb-preview-ns

So, in case your primary pod is documentdb-local-ha-1, you would run: kubectl delete pod documentdb-local-ha-1 -n documentdb-preview-ns

Automatic Recovery

Watch the client terminal. You should see logs similar to this:

[CLIENT][10:32:32.452] ✗ FAILOVER EVENT DETECTED
[CLIENT][10:32:32.452] ℹ   Error: the database system is shutting down, full error: {'ok': 0.0, 'code': 50463173, 'codeName': 'Error', 'errmsg': 'the database system is shutting down'}
[CLIENT][10:32:32.452] ℹ   Last successful write: #178
[CLIENT][10:32:32.452] ℹ ================================================================================
[CLIENT][10:32:32.500] ✗ ⚠ Write FAILED | ⚠ Read FAILED | Downtime: 0.0s | Failed W: 1 R: 1
[CLIENT][10:32:32.551] ↻ Attempting reconnection (backoff: 1.0s)...
[CLIENT][10:32:32.703] ✗ Connection failed: error connecting to server: Connection refused (os error 111), full error: {'ok': 0.0, 'code': 1, 'codeName': 'Internal Error', 'errmsg': 'error connecting to server: Connection refused (os error 111)'}
[CLIENT][10:32:33.705] ↻ Attempting reconnection (backoff: 2.0s)...
[CLIENT][10:32:33.947] ✓ Connected to DocumentDB
[CLIENT][10:32:33.947] ✓ Reconnection successful!
[CLIENT][10:32:33.998] ℹ ================================================================================
[CLIENT][10:32:33.998] ↻ RECOVERY COMPLETE
//.....

Then the read and write operations should resume successfully:

[CLIENT][10:32:34.044] ✓ W#179 (51ms) | R#179 (46ms) | Avg W:8ms R:39ms | Docs: 284
[CLIENT][10:32:34.593] ✓ W#180 (4ms) | R#180 (42ms) | Avg W:8ms R:39ms | Docs: 285
[CLIENT][10:32:35.143] ✓ W#181 (5ms) | R#181 (44ms) | Avg W:9ms R:39ms | Docs: 286
[CLIENT][10:32:35.693] ✓ W#182 (3ms) | R#182 (43ms) | Avg W:9ms R:39ms | Docs: 287
[CLIENT][10:32:36.238] ✓ W#183 (2ms) | R#183 (42ms) | Avg W:8ms R:39ms | Docs: 288
[CLIENT][10:32:36.787] ✓ W#184 (3ms) | R#184 (43ms) | Avg W:9ms R:39ms | Docs: 289
[CLIENT][10:32:37.333] ✓ W#185 (3ms) | R#185 (42ms) | Avg W:8ms R:39ms | Docs: 290
//....

Let's take a closer look at what happened.

Behind the scenes

These are the key events during failover:

Failure detection: Operations start failing with connection errors
FAILOVER EVENT DETECTED: The client recognizes the disruption
Reconnection attempts: Automatic retry with exponential backoff
RECOVERY COMPLETE: Service automatically resumes

Behind the scenes, CNPG automatically detects the primary pod termination, promotes a healthy replica to primary, and updates the cnpg.io/instanceRole: primary label on the new primary pod. The Kubernetes service automatically routes traffic to the new primary (the external IP remains unchanged).

The key to failover is the service's label selector mechanism. Since the service tracks pods with cnpg.io/instanceRole: primary, when CNPG updates this label during promotion, the service endpoint automatically switches to the new primary without any DNS changes or client reconfiguration.

Verify the new primary – you should see a different pod as the new primary (it may vary in your deployment). In this example, documentdb-local-ha-3 has become the new primary:

kubectl get pods -n documentdb-preview-ns -L cnpg.io/instanceRole

# output:
NAME                    READY   STATUS    RESTARTS   AGE     INSTANCEROLE
documentdb-local-ha-1   2/2     Running   0          2m17s   replica
documentdb-local-ha-2   2/2     Running   0          18m     replica
documentdb-local-ha-3   2/2     Running   0          18m     primary

Verify manually

You can also connect directly using mongosh to verify. First, get the connection string:

kubectl get documentdb documentdb-local-ha -n documentdb-preview-ns

# output:

NAME                  STATUS                     CONNECTION STRING
documentdb-local-ha   Cluster in healthy state   mongodb://$(kubectl get secret documentdb-credentials -n documentdb-preview-ns -o jsonpath='{.data.username}' | base64 -d):$(kubectl get secret documentdb-credentials -n documentdb-preview-ns -o jsonpath='{.data.password}' | base64 -d)@127.0.0.1:10260/?directConnection=true&authMechanism=SCRAM-SHA-256&tls=true&tlsAllowInvalidCertificates=true&replicaSet=rs0

Use the connection string to connect with mongosh:

mongosh "mongodb://$(kubectl get secret documentdb-credentials -n documentdb-preview-ns -o jsonpath='{.data.username}' | base64 -d):$(kubectl get secret documentdb-credentials -n documentdb-preview-ns -o jsonpath='{.data.password}' | base64 -d)@127.0.0.1:10260/?directConnection=true&authMechanism=SCRAM-SHA-256&tls=true&tlsAllowInvalidCertificates=true&replicaSet=rs0"

Once connected, you can connect to the testdb database and verify the documents:

rs0 [direct: mongos] test> use testdb
switched to db testdb
rs0 [direct: mongos] testdb> db.getCollectionNames()
[ 'failover_test' ]
rs0 [direct: mongos] testdb> db.failover_test.countDocuments()
408
rs0 [direct: mongos] testdb>

Bonus exercise

Try connecting to each cluster node directly. You can kubectl port-forward to each pod. For example, to connect to documentdb-local-ha-1 over port 27017:

kubectl port-forward -n documentdb-preview-ns documentdb-local-ha-1 27017:10260

Now you can connect with mongosh:

mongosh "mongodb://k8s_secret_user:K8sSecret100@localhost:27017/?directConnection=true&authMechanism=SCRAM-SHA-256&tls=true&tlsAllowInvalidCertificates=true"

Experiment with different commands and observe the behavior.

You can also explore advanced scenarios like multi-region or multi-cloud deployments

Cleanup

To tear down the environment when you're done:

kubectl delete namespace documentdb-preview-ns
helm uninstall documentdb-operator -n documentdb-operator
kubectl delete namespace documentdb-operator
minikube stop

Wrapping Up

The DocumentDB Kubernetes Operator provides local high availability with automatic failover capabilities. You have seen how the operator handles primary failures with minimal manual intervention, making it easier to build resilient database deployments on Kubernetes.

This tutorial demonstrates basic failover recovery using a small dataset in a single-node cluster. In this case, the client-observed recovery time was approximately 1-3 seconds. Since CNPG uses asynchronous replication by default, note that transactions committed on the old primary but not yet replicated to standbys could be lost during an unplanned failover. Make sure to consider factors specific to your deployments for production or with larger datasets.

Go ahead, try it out in your own environment, and let us know your feedback!

Check out the documentation for the latest feature updates. If you run into issues or have questions, reach out on Discord or raise an issue on GitHub. Contributions are welcome, whether it's code, documentation improvements, or simply sharing your experience.

Happy building!

Build a Time Tracking App with GitHub Copilot SDK

Abhishek Gupta — Mon, 02 Mar 2026 06:09:41 +0000

The GitHub Copilot SDK lets you embed Copilot's agentic workflows directly into your apps, and it's available for Python, TypeScript, Go, and .NET.

TimeTrack is a desktop app built with the GitHub Copilot SDK (TypeScript) and Azure Cosmos DB. You can:

⏱️ Track time with a start/stop timer, projects, and tags
🗣️ Ask questions about your time data in plain English — Copilot generates and runs Cosmos DB SQL queries behind the scenes
📊 View reports and charts across multiple users

Here is a demo of the app in action:

If you want to try it yourself, the code is on GitHub. Works with Azure Cosmos DB or the vNext emulator — clone, configure, and npm start.

For local development, you don't need an Azure account. The Cosmos DB vNext emulator runs as a Docker container, so you can seed sample data and start querying right away.

Behind the Scenes

What makes this interesting is the SDK's tool calling. You define a tool using defineTool with a schema (powered by Zod), and Copilot decides when to call it. Here's what the core of it looks like:

const queryTool = defineTool("query_time_data", {
  description: "Execute a read-only Cosmos DB SQL query against time entries",
  parameters: z.object({
    query: z.string().describe("Cosmos DB SQL query"),
  }),
  handler: async ({ query }) => {
    // query is scoped to the user's partition key
    const result = await runQuery(userId, query);
    return JSON.stringify(result);
  },
});

session = await client.createSession({
  tools: [queryTool],
  systemMessage: { mode: "replace", content: "..." },
});

When a user asks "what was my most productive day this week?", the model generates a SQL query, executes it against Cosmos DB (scoped to the user's partition key), and returns a conversational answer. If the generated SQL hits a Cosmos DB error — say, an unsupported ORDER BY on an aggregate alias — the error is returned to the model as a tool result. The model reads it, adjusts the query, and retries. This usually succeeds within 1–2 attempts, with no user intervention.

Here's the overall flow:

+--------------+     +----------------+     +-------------+
|  Electron UI | --> |  Copilot SDK   | --> | Copilot CLI |
|  (renderer)  |     |  (main process)|     |  (sidecar)  |
+--------------+     +----------------+     +------+------+
       ^                                           |
       |                                    tool call: query_time_data
       |                                           |
       |                                    +------v------+
       |                                    |  Cosmos DB  |
       |                                    +------+------+
       |                                           |
       |                                     result or error
       |                                           |
       |                                    +------v------+
       |                                    |    Model    |
       |                                    | (interpret) |
       |                                    +------+------+
       |                                      |         |
       |                                success?     SQL error?
       |                                   |          retry with
       |                                   |        corrected SQL
       |                                   |             |
       +---  AI response  <---------------+     (back to Cosmos DB)

Because the AI writes arbitrary SQL rather than picking from canned reports, the range of questions is wide. A few examples:

Do I tend to work longer hours early in the week or late in the week?
How does my Monday workload compare to Friday?
Compare my total hours this week vs last week
Rank my projects by total hours and show the percentage each represents
Summarize my last two weeks in 3 bullet points

The app uses GPT-4.1 by default, but you can switch to any supported Copilot model — gpt-5, claude-sonnet-4.5, etc. — by setting COPILOT_MODEL in .env.

If you want to go beyond Copilot's model lineup entirely, the app supports BYOK (Bring Your Own Key). Point it at your own Azure AI Foundry deployment — set your endpoint, API key, and deployment name in .env and the SDK routes all AI calls to your model. The tool calling, session management, and agent runtime stay identical. You control the model, the billing, and the identity layer; the SDK provides the agentic infrastructure.

The app also has experimental support for local OpenAI-compatible servers (Ollama, Foundry Local), though results vary depending on the model's tool calling capabilities, and your environment setup (GPU, etc).

Try It Yourself

The full source code is on GitHub. You can run it with the Cosmos DB vNext emulator — no Azure account needed — seed sample data, and start asking questions in natural language. Swap in your own model via BYOK if you want full control over the AI layer.

The Copilot SDK is open source and available for TypeScript, Python, Go, and .NET. Check out the docs to see what else you can build with it.

Agentic Apps with GitHub Copilot SDK

Abhishek Gupta — Mon, 02 Feb 2026 14:45:46 +0000

The GitHub Copilot SDK lets you embed Copilot's AI capabilities directly into your apps — available for Go, Python, TypeScript, and .NET.

Here's a quick demo of building an agentic application with the SDK and Azure Cosmos DB.

Flight Diary is a sample app where you can:

📸 Upload a boarding pass image → Copilot extracts flight details automatically (no separate OCR/vision API needed)
🗣️ Query your flight history in plain English → Copilot generates and runs Cosmos DB SQL queries behind the scenes

The part I find interesting is how the SDK handles tool calling. You define the tools, Copilot figures out when and how to use them. For example, when extracting from a boarding pass, it parses the image and calls the save function — all from a single prompt.

If you want to try it yourself, the code is on GitHub. It also works with the Cosmos DB vNext emulator for local development.

GitHub Copilot CLI + MCP: Talk to Your Database in Plain English

Abhishek Gupta — Sat, 24 Jan 2026 11:56:09 +0000

Here is a quick demo of how to interact with Azure Cosmos DB from GitHub Copilot CLI using MCP. This MCP server lets you interact with Azure Cosmos DB using plain English instead of writing queries or clicking through the portal. List databases, create containers, run SQL queries, add items — all through natural language. It works with both the Cosmos DB service and the vNext emulator (for local development).

The part I really enjoy is watching Copilot CLI figure out which tools to call to get the job done. For example, when I asked for "pending tasks," it generated the query and ran it without me having to think about the syntax.

If you want to try it yourself, the code is on GitHub. It's fairly straightforward to build, and set up with /mcp add. For something production-ready with remote (HTTP) deployment and Entra ID authentication, check out the Azure Cosmos DB MCP Toolkit.

If you haven't tried GitHub Copilot CLI with MCP servers yet, this is an easy way to get started.

Cheers!

Azure Cosmos DB Playground: Learn and experiment with queries in your browser

Abhishek Gupta — Wed, 14 Jan 2026 07:04:05 +0000

Interactive Browser-Based Environment to Learn, Test, and Share Queries

The Azure Cosmos DB Playground is an interactive, browser-based playground for learning and experimenting with Azure Cosmos DB SQL queries without any setup, installation, or cloud costs. The playground runs on the Azure Cosmos DB vNext emulator and leverages the open-source codapi project behind the scenes.

The playground is a great tool for learning, prototyping, testing, and sharing Azure Cosmos DB queries. You can:

📦 Explore with pre-loaded datasets and ready-to-run query examples
📤 Paste or upload your own JSON data to experiment with custom scenarios
⚡ Instantly see query results and modify both data and queries on the fly
🔗 Generate shareable links that capture your current dataset and query for easy sharing
♻️ Restore your last session automatically after a refresh or reopening the page
🧩 Embed interactive, runnable examples directly into HTML files for documentation, blogs, or tutorials

Note: This is an experimental project and not an official Microsoft or Azure offering. It’s designed for learning and sharing, not for production use.

▶️ Quick Demo (click to play)

Try the Playground (or Deploy Your Own) 🚀

You can head over to https://aka.ms/cosmosdb-playground and start experimenting right away!

While the hosted playground is ready to use, you can also deploy your own instance on Azure. The playground uses a fully containerized architecture with Docker Compose. Follow the detailed deployment instructions available on GitHub to set up your own playground instance.

To configure HTTP(s) access for your deployed playground, refer to the instructions available on GitHub.

Playground Features 🛠️

These might evolve over time - You can check out the GitHub repository for up to date list of features.

Behind the Scenes 🏗️

Here is a simplified architecture of the Azure Cosmos DB Playground:

+-------------------+        +-------------------+        +-------------------+
|   User Browser    |  <---> |      nginx        |  <---> |     Codapi        |
| (playground.html) |        | (Reverse Proxy)   |        | (Sandbox Server)  |
+-------------------+        +-------------------+        +-------------------+
                                                           |
                                                           v
                                                +--------------------------+
                                                |  Ephemeral Query Container|
                                                |  (Python + Cosmos SDK)    |
                                                +--------------------------+
                                                           |
                                                           v
                                                +--------------------------+
                                                | Cosmos DB Emulator       |
                                                | (Docker Container)       |
                                                +--------------------------+

At its core, the playground uses the Azure Cosmos DB vNext Emulator as a custom Codapi sandbox.

Azure Cosmos DB vNext Emulator: This is a local version of Azure Cosmos DB (SQL API) available as a Docker container. It emulates the real Azure Cosmos DB service, so you can experiment with queries and data models without any cloud setup or cost.

Codapi: It is a lightweight sandbox server designed for interactive documentation, code examples, and learning environments. In the playground, Codapi manages the creation of isolated Docker containers for each query execution. This ensures that each user’s code and data are executed in an ephemeral environment. Codapi JavaScript widget (codapi-js) is used for the playground frontend integration, which invokes the Codapi API for code execution in the sandbox.

Query Execution Flow

nginx serves the frontend and routes API requests to Codapi, enabling interactive query execution from the browser.

For each run, Codapi spawns an ephemeral query Docker container where a Python component connects to the long-running Cosmos DB emulator. It creates a temporary Cosmos DB container, seeds the data, executes the query, and returns results. After execution, both the temporary Cosmos DB container and the ephemeral query Docker container are cleaned up.

Limitations ⚠️

The playground is a sandbox for learning and experimentation, not production use. It is designed for small(ish) datasets and may have performance constraints, among other limitations. Some of these limitations may change over time. For the most current list, refer to the GitHub repo.

Try It Out! ✨

Visit https://aka.ms/cosmosdb-playground to start experimenting with queries, and share your examples with others.

Have feedback or suggestions? Visit the GitHub repository and share your thoughts. Happy querying!