DEV Community: Abhishek Gupta

How to Use 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!

Build AI Tooling in Go with the MCP SDK – Connecting AI Apps to Databases

Abhishek Gupta — Wed, 07 Jan 2026 17:12:51 +0000

A hands‑on walkthrough of building MCP servers that can plug AI applications into Azure Cosmos DB

The Model Context Protocol (MCP) has established itself as the ubiquitous standard for connecting AI applications to external systems. Since its release, there have been implementations across various programming languages and frameworks, enabling developers to build solutions that expose data sources, tools, and workflows to AI applications.

For Go developers, however, the journey to an official MCP SDK took longer (compared to other SDKs like Python and TypeScript). Discussions and design/implementation work on the official Go implementation began during early to mid 2025. At the time of writing (January 2026) it stands at version 1.2.0. As a Gopher, I'm excited (and relieved!) to finally have a stable, official MCP Go SDK that the Go community can rely on.

To explore its capabilities, I built an MCP server for Azure Cosmos DB. This blog post will dive into the MCP Go SDK fundamentals by walking through its specifics, and exploring concepts such as tools, servers, etc. By the end, you'll understand how to use the MCP Go SDK to build your own MCP servers, with Azure Cosmos DB serving as a practical example.

Note: This project is not intended to replace the Azure MCP Server or Azure Cosmos DB MCP Toolkit. Rather, it serves as an experimental learning tool that demonstrates how to combine the Azure and MCP Go SDKs to build AI tooling for Azure Cosmos DB.

MCP Basics

Let's briefly cover what MCP is and how the MCP Go SDK works.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems. It's often referred to as a USB-C port for AI applications — just as USB-C provides a standardized way to connect devices, MCP provides a standardized way to connect AI applications to data sources, tools, and workflows.

With MCP, AI applications (ranging from IDEs like VS Code, CLI coding tools like GitHub Copilot or apps like Claude web/desktop) can:

Access data sources (local files, databases, APIs)
Use tools (search engines, calculators, external services)
Execute workflows (specialized prompts, multi-step operations)

This standardization means developers can build MCP servers once and have them work with any MCP-compatible AI application, rather than creating custom integrations for each platform.

MCP Go SDK

The official Go MCP SDK provides the building blocks to create MCP servers and clients in Go. Here's a minimal example of an MCP server with a simple tool:

package main

import (
    "context"
    "log"
    "strings"

    "github.com/modelcontextprotocol/go-sdk/mcp"
)

type ReverseInput struct {
    Text string `json:"text" jsonschema:"the text to reverse"`
}

type ReverseOutput struct {
    Reversed string `json:"reversed" jsonschema:"the reversed text"`
}

func ReverseText(ctx context.Context, req *mcp.CallToolRequest, input ReverseInput) (
    *mcp.CallToolResult,
    ReverseOutput,
    error,
) {
    runes := []rune(input.Text)
    for i, j := 0, len(runes)-1; i < j; i, j = i+1, j-1 {
        runes[i], runes[j] = runes[j], runes[i]
    }
    return nil, ReverseOutput{Reversed: string(runes)}, nil
}

func main() {
    // Create server
    server := mcp.NewServer(&mcp.Implementation{
        Name:    "text-tools",
        Version: "v1.0.0",
    }, nil)

    // Add a tool
    mcp.AddTool(server, &mcp.Tool{
        Name:        "reverse",
        Description: "reverses the input text",
    }, ReverseText)

    // Run over stdio
    if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
        log.Fatal(err)
    }
}

This example demonstrates the key concepts:

Tool definition: A mcp.Tool with a name and description
Input/Output types: Structs with JSON schema tags that define the tool's interface
Handler function: The actual logic that executes when the tool is called
Server: Created with mcp.NewServer() and configured with tools
Transport: How the server communicates (here using stdio)

These concepts will be covered later on the blog.

MCP Server in Action

▶️ To get a sense of what the server can do, take a look at this short demo of using the MCP server with Agent Mode in Visual Studio Code:

This server exposes several tools that enable AI applications to interact with Azure Cosmos DB:

list_databases - List all databases in a Cosmos DB account
list_containers - List all containers in a specific database
read_item - Read a specific item using its ID and partition key
execute_query - Execute SQL queries against containers
create_container - Create new containers with partition keys
add_item_to_container - Add items to containers
read_container_metadata - Retrieve container configuration details

If you want to setup and configure the server, check out the GitHub repository.

Alright, let's dive into how it's built.

Understanding the Implementation

Tools are the building blocks of an MCP server. Each tool represents a specific operation that the server can perform.

Let's use the read_item tool as an example to understand the fundamental concepts of the MCP Go SDK and how it integrates with the Azure Cosmos DB Go SDK.

MCP Tools: Definition, Handler, and Execution Flow

An MCP tool consists of these components:

Tool Definition

The tool definition describes the tool to the AI application. Here's how we define the read_item tool:

func ReadItem() *mcp.Tool {
    return &mcp.Tool{
        Name:        "read_item",
        Description: "Read a specific item from a container in an Azure Cosmos DB database using the item ID and partition key",
    }
}

The Tool struct contains:

Name: A unique identifier for the tool
Description: Helps the AI understand when to use this tool

The SDK can automatically infer input and output schemas from your handler function's types, which we'll see next.

Input and Output Types

Type-safe input and output structures define the tool's interface:

type ReadItemToolInput struct {
    Account      string `json:"account" jsonschema:"Azure Cosmos DB account name"`
    Database     string `json:"database" jsonschema:"Name of the database"`
    Container    string `json:"container" jsonschema:"Name of the container to read data from"`
    ItemID       string `json:"itemID" jsonschema:"ID of the item to read"`
    PartitionKey string `json:"partitionKey" jsonschema:"Partition key value of the item"`
}

type ReadItemToolResult struct {
    Item string `json:"item" jsonschema:"The item data as JSON string"`
}

The SDK uses these types to automatically generate JSON schemas and handle validation. JSON tags define how fields are serialized, and jsonschema tags provide descriptions that help AI applications understand what each field represents

Tool Handler

The handler is where the actual work happens. The MCP Go SDK provides a generic AddTool function that can bind tools to functions with this signature:

func(ctx context.Context, request *CallToolRequest, input InputType) (result *CallToolResult, output OutputType, error)

Here's the read_item handler:

func ReadItemToolHandler(ctx context.Context, _ *mcp.CallToolRequest, input ReadItemToolInput) (*mcp.CallToolResult, ReadItemToolResult, error) {
    // 1. Validate inputs
    if input.Account == "" {
        return nil, ReadItemToolResult{}, errors.New("cosmos db account name missing")
    }
    if input.Database == "" {
        return nil, ReadItemToolResult{}, errors.New("database name missing")
    }
    // ... more validation

    // 2. Get Cosmos DB client
    client, err := GetCosmosClientFunc(input.Account)
    if err != nil {
        return nil, ReadItemToolResult{}, err
    }

    // 3. Navigate to the container
    databaseClient, err := client.NewDatabase(input.Database)
    if err != nil {
        return nil, ReadItemToolResult{}, fmt.Errorf("error creating database client: %v", err)
    }

    containerClient, err := databaseClient.NewContainer(input.Container)
    if err != nil {
        return nil, ReadItemToolResult{}, fmt.Errorf("error creating container client: %v", err)
    }

    // 4. Read the item using Cosmos DB SDK
    partitionKey := azcosmos.NewPartitionKeyString(input.PartitionKey)
    itemResponse, err := containerClient.ReadItem(ctx, partitionKey, input.ItemID, nil)
    if err != nil {
        return nil, ReadItemToolResult{}, fmt.Errorf("error reading item: %v", err)
    }

    // 5. Return the result
    return nil, ReadItemToolResult{Item: string(itemResponse.Value)}, nil
}

The handler handles (pun intended!) several things:

Validates input parameters
Interacts with Azure Cosmos DB
Returns structured output

Notice we return nil for the *mcp.CallToolResult. The SDK automatically handles the response marshaling for us. If we return an error, the SDK sets IsError: true in the result automatically.

Authenticating with Azure Cosmos DB

The MCP server uses NewDefaultAzureCredential from the Azure Identity SDK, which automatically handles multiple authentication methods, such as Azure CLI credentials (for local development), Managed Identity (for production), environment variables, and more:

func GetCosmosDBClient(accountName string) (*azcosmos.Client, error) {
    endpoint := fmt.Sprintf("https://%s.documents.azure.com:443/", accountName)

    cred, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        return nil, fmt.Errorf("error creating credential: %v", err)
    }

    client, err := azcosmos.NewClient(endpoint, cred, nil)
    if err != nil {
        return nil, fmt.Errorf("error creating Cosmos client: %v", err)
    }

    return client, nil
}

Once we have the client, we use the standard Azure Cosmos DB SDK patterns:

client.NewDatabase() to get a database client
databaseClient.NewContainer() to get a container client
containerClient.ReadItem() to perform the actual read operation

MCP Server: Bringing Tools Together

The beauty here is that MCP provides the standardized interface for AI interactions, while the Azure Cosmos DB SDK handles all the database operations – the handler acts as the bridge between these two worlds.

Now that we understand individual tools, let's see how they're organized within an MCP server. An MCP server exposes specific capabilities (tools, resources, prompts) to AI applications through the standardized MCP protocol.

Creating the Server

Here's how we create and configure the MCP server in main.go:

func main() {
    // Create the server with metadata
    server := mcp.NewServer(&mcp.Implementation{
        Name:       "mcp_azure_cosmosdb_go",
        Title:      "Go based MCP server for Azure Cosmos DB using the Azure SDK for Go and the MCP Go SDK",
        Version:    "0.0.1",
        WebsiteURL: "https://github.com/abhirockzz/mcp_cosmosdb_go",
    }, nil)

    // Register all tools with their handlers
    mcp.AddTool(server, tools.ListDatabases(), tools.ListDatabasesToolHandler)
    mcp.AddTool(server, tools.ListContainers(), tools.ListContainersToolHandler)
    mcp.AddTool(server, tools.ReadContainerMetadata(), tools.ReadContainerMetadataToolHandler)
    mcp.AddTool(server, tools.CreateContainer(), tools.CreateContainerToolHandler)
    mcp.AddTool(server, tools.AddItemToContainer(), tools.AddItemToContainerToolHandler)
    mcp.AddTool(server, tools.ReadItem(), tools.ReadItemToolHandler)
    mcp.AddTool(server, tools.ExecuteQuery(), tools.ExecuteQueryToolHandler)

    // ... transport setup (covered next)
}

Breaking this down:

mcp.NewServer() creates a new server instance with:
- Implementation metadata: Name, title, and version that identify the server
- ServerOptions: Additional configuration (we use nil for defaults)
mcp.AddTool() registers each tool with the server:
- Takes the server instance
- The tool definition (from functions like tools.ReadItem())
- The handler function (like tools.ReadItemToolHandler)

When the server connects to a client, it automatically advertises the tools capability, making all registered tools discoverable by the AI application.

Transport: Connecting Server to Client

A transport defines how the server communicates with clients. It's the communication channel that carries JSON-RPC messages between the server and client. The MCP Go SDK supports multiple transport types.

HTTP Streamable Transport

The server also supports http transport, which is ideal for web-based AI applications. Here's how we set it up:

// Create the streamable HTTP handler
handler := mcp.NewStreamableHTTPHandler(func(req *http.Request) *mcp.Server {
    return server
}, nil)

// Start the HTTP server
if err := http.ListenAndServe(":9090", handler); err != nil {
    log.Fatalf("Server failed: %v", err)
}

The NewStreamableHTTPHandler creates an HTTP handler that accepts incoming HTTP requests from MCP clients, and returns the appropriate server instance for each request. It handles the streamable transport protocol automatically, and supports multiple concurrent client sessions

This transport is ideal when you want to support web-based AI applications and the server needs to be accessible over HTTP/HTTPS. This allows multiple clients to connect simultaneously.

Stdio Transport

Another common MCP transport is stdio, used when the server runs as a subprocess:

err := server.Run(context.Background(), &mcp.StdioTransport{})
if err != nil {
    log.Fatal(err)
}

The stdio transport runs as a subprocess started by the client and communicates via standard input/output streams. It's perfect for local MCP clients like GitHub Copilot CLI, Claude Code (or Desktop), etc. Both transports implement the same MCP protocol, so the server's tools work identically regardless of which transport you choose. The difference is purely in how the server connects to and communicates with clients.

With the server created, tools registered, and transport configured, the MCP server is ready to accept connections from AI applications and execute operations against Azure Cosmos DB.

Testing the MCP Server

This involves verifying functionality at different layers of the stack. This server uses integration tests at two levels: tests that verify the MCP protocol aspects, and tests that focus on handler logic with database interactions. Let's explore both approaches.

Before diving into testing, let's briefly understand what an MCP client is.

Understanding MCP Clients

An MCP client is the component that connects to an MCP server to consume its capabilities. In the context of the MCP server:

In production: The client is typically an AI application (like Claude Desktop or VS Code) that discovers and calls our tools
In testing: We create programmatic clients to verify our server works correctly

The MCP Go SDK provides a Client type that we can use to connect to our server and call its tools, simulating how a real AI application would interact with it.

Handler-Level Integration Testing with Azure Cosmos DB vNext Emulator

Let's start by looking at tests that focus on handler logic and database interactions. It uses the Azure Cosmos DB vNext Emulator with testcontainers-go.

From tools_test.go:

func TestListDatabases(t *testing.T) {
    tests := []struct {
        name           string
        input          ListDatabasesToolInput
        expectError    bool
        expectedResult string
        expectedErrMsg string
    }{
        {
            name: "valid account name",
            input: ListDatabasesToolInput{
                Account: "dummy_account_does_not_matter",
            },
            expectError:    false,
            expectedResult: testOperationDBName,
        },
        {
            name: "empty account name",
            input: ListDatabasesToolInput{
                Account: "",
            },
            expectError:    true,
            expectedErrMsg: "cosmos db account name missing",
        },
    }

    for _, test := range tests {
        t.Run(test.name, func(t *testing.T) {
            _, response, err := ListDatabasesToolHandler(
                context.Background(), 
                nil, 
                test.input,
            )

            if test.expectError {
                require.Error(t, err)
                assert.Contains(t, err.Error(), test.expectedErrMsg)
                return
            }

            require.NoError(t, err)
            assert.Contains(t, response.Databases, test.expectedResult)
        })
    }
}

These tests call handlers directly (bypassing the MCP protocol layer) and use table-driven tests for input validation and error handling, business logic correctness, database operations and edge cases.

func setupCosmosEmulator(ctx context.Context) (testcontainers.Container, error) {
    req := testcontainers.ContainerRequest{
        Image:        "mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview",
        ExposedPorts: []string{"8081:8081", "8080:8080"},
        WaitingFor:   wait.ForListeningPort(nat.Port("8080")),
        Env: map[string]string{
            "PROTOCOL": "http",
        },
    }

    container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
        ContainerRequest: req,
        Started:          true,
    })
    // ... error handling

    return container, nil
}

The testcontainers-go library automatically pulls the emulator image, starts the container, and cleans up after tests complete. This is set up once in TestMain function and shared across all tests.

MCP Protocol Integration Testing

Beyond handler testing, we also verify the complete MCP protocol stack—from client request through server processing to response. Here's an example from mcp_integration_test.go:

func TestMCPIntegration_ReadItem(t *testing.T) {
    ctx := context.Background()

    // 1. Create MCP server and register the read_item tool
    server := mcp.NewServer(&mcp.Implementation{
        Name:    "test-cosmosdb-server",
        Version: "0.0.1",
    }, nil)

    mcp.AddTool(server, ReadItem(), ReadItemToolHandler)

    // 2. Create in-memory transports for testing
    serverTransport, clientTransport := mcp.NewInMemoryTransports()

    // 3. Connect server
    serverSession, err := server.Connect(ctx, serverTransport, nil)
    require.NoError(t, err)
    defer serverSession.Close()

    // 4. Create and connect client
    client := mcp.NewClient(&mcp.Implementation{
        Name:    "test-client",
        Version: "0.0.1",
    }, nil)

    clientSession, err := client.Connect(ctx, clientTransport, nil)
    require.NoError(t, err)
    defer clientSession.Close()

    // 5. Call the tool via MCP protocol
    result, err := clientSession.CallTool(ctx, &mcp.CallToolParams{
        Name: "read_item",
        Arguments: map[string]any{
            "account":      "dummy_account_does_not_matter",
            "database":     testOperationDBName,
            "container":    testOperationContainerName,
            "itemID":       id,
            "partitionKey": partitionKeyValue,
        },
    })

    // 6. Verify the response
    require.NoError(t, err)
    require.False(t, result.IsError)
    require.NotEmpty(t, result.Content)

    // 7. Parse and validate the JSON response
    textContent, ok := result.Content[0].(*mcp.TextContent)
    require.True(t, ok)

    var response ReadItemToolResult
    err = json.Unmarshal([]byte(textContent.Text), &response)
    require.NoError(t, err)

    assert.NotEmpty(t, response.Item)
}

This test demonstrates several key concepts:

In-Memory Transports: mcp.NewInMemoryTransports() creates a pair of connected transports without requiring actual network communication—perfect for testing
Client-Server Connection: Both server and client connect to their respective transports, establishing a session
Tool Invocation: clientSession.CallTool() sends a properly formatted MCP request
Response Handling: The result is parsed from the MCP protocol format back to our domain types
Full Protocol Verification: This tests the complete round trip: request serialization → tool execution → response serialization → client parsing

Both handler-level and protocol-level tests use the Azure Cosmos DB vNext emulator, not mocks. Handler-level tests provide feedback on business logic, while protocol-level tests ensure MCP compliance and end-to-end functionality.

Wrap Up

With the MCP Go SDK, building MCP servers has become significantly more accessible for Go developers. You don't have to go for Python anymore (sorry Pythonistas, pun intended!).

This MCP server demonstrates how to combine the MCP Go SDK with domain-specific tools — in this case, the Azure Cosmos DB Go SDK. While this server provides useful functionality for interacting with Cosmos DB from AI applications, its primary purpose is educational. As mentioned before, this is a learning tool that shows how to integrate MCP with real-world services, not a replacement for solutions like the Azure MCP Server or the Azure Cosmos DB MCP Toolkit.

The specific patterns we covered (defining tools, implementing handlers, managing authentication, choosing transports, and writing integration tests) apply to any MCP server you might build. The same concepts apply, whether you're exposing APIs, databases, file systems, or custom business logic.

Next Steps

Ready to build your own MCP server? Here are some resources to get you started:

MCP Go SDK resources: Documentation, design, and examples.
MCP Specification: https://modelcontextprotocol.io/
Azure Cosmos DB Go SDK: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos
Azure Cosmos DB vNext Emulator and Testcontainers Guide: Integration Testing for Go Applications

The MCP ecosystem is growing rapidly, and I am excited for Go developers who now have first-class support for participating in this evolution!

Azure Cosmos DB vNext Emulator: Query and Observability Enhancements

Abhishek Gupta — Sat, 13 Dec 2025 15:28:48 +0000

The Azure Cosmos DB Linux-based vNext emulator (preview) is a local version of the Azure Cosmos DB service that runs as a Docker container on Linux, macOS, and Windows. It provides a cost-effective way to develop and test applications locally without requiring an Azure subscription or network connectivity.

The latest release brings improvements in two key areas:

Enhanced Query engine: Addresses limitations in JOINs, operators, subdocument handling, and more.
Observability: OpenTelemetry support to collect and correlate metrics, logs, and traces for deeper insight into applications.

Query Improvements

This emulator release enables several query patterns that were previously unsupported. In this post, we'll focus on the following enhancements to query capabilities:

Improved JOIN Operations – Support for nested JOINs across multiple array levels, cross-product JOINs, and self-JOINs on primitive arrays
Enhanced Operator Support – Support for string manipulation functions (CONCAT, LENGTH) and array operations (ARRAY_LENGTH, direct array indexing)
Better Subdocument Handling – Improved querying of deeply nested object properties and proper handling of missing properties

Let's explore these with practical examples.

Improved JOINs

In Azure Cosmos DB, JOINs enable you to flatten and traverse data within documents, allowing you to work with nested and hierarchical data structures.

Let's explore this using a sample family dataset where each document represents a family with nested arrays. This includes three families (Andersen, Wakefield, and Miller) with varying numbers of children and pets, demonstrating how JOINs handle different data structures. Notice the hierarchical nesting: each family has a children array, each child has a pets array, and families also have a separate tags array.

[
    {
        "id": "AndersenFamily",
        "lastName": "Andersen",
        "parents": [
            {"firstName": "Thomas", "relationship": "father"},
            {"firstName": "Mary Kay", "relationship": "mother"}
        ],
        "children": [
            {
                "firstName": "Henriette",
                "grade": 5,
                "pets": [{"name": "Fluffy", "type": "Rabbit"}]
            }
        ],
        "tags": ["seattle", "active", "family-friendly"],
        "address": {"state": "WA", "city": "Seattle"}
    },
    {
        "id": "WakefieldFamily",
        "lastName": "Wakefield",
        "parents": [
            {"firstName": "Robin", "relationship": "mother"},
            {"firstName": "Ben", "relationship": "father"}
        ],
        "children": [
            {
                "firstName": "Jesse",
                "grade": 8,
                "pets": [
                    {"name": "Goofy", "type": "Dog"},
                    {"name": "Shadow", "type": "Horse"}
                ]
            },
            {"firstName": "Lisa", "grade": 1, "pets": []}
        ],
        "tags": ["newyork", "urban"],
        "address": {"state": "NY", "city": "New York"}
    },
    {
        "id": "MillerFamily",
        "lastName": "Miller",
        "parents": [{"firstName": "David", "relationship": "father"}],
        "children": [
            {
                "firstName": "Emma",
                "grade": 6,
                "pets": [{"name": "Whiskers", "type": "Cat"}]
            }
        ],
        "tags": ["boston", "academic"],
        "address": {"state": "MA", "city": "Boston"}
    }
]

Basic JOIN – Flattening Arrays

For example, if you need to generate a list of all children across multiple families for a school roster or activity planning, use the JOIN operator to flatten the children array, creating one result row per child across all family documents.

SELECT f.id, f.lastName, c.firstName, c.grade 
FROM f 
JOIN c IN f.children

This returns one row per child (giving you a flattened view of all children with their family information) – Henriette from the Andersen family, Jesse and Lisa from the Wakefield family, and Emma from the Miller family.

JOIN with Filter

To find children within specific grade ranges, add a WHERE clause to JOIN. This lets you filter results based on properties of the array elements, like selecting only middle school students (grade 6 and above).

SELECT f.id, f.lastName, c.firstName, c.grade 
FROM f 
JOIN c IN f.children 
WHERE c.grade >= 6

The result set includes only Jesse (grade 8) and Emma (grade 6), automatically excluding Henriette and Lisa who are in lower grades.

Nested JOIN – Traversing Hierarchical Data

If you need to traverse multiple levels of your data structure to identify all pets and their owners, use chained JOINs to drill down through nested arrays, moving from families to children to pets in a single query.

SELECT f.id, c.firstName AS child, p.name AS pet, p.type 
FROM f 
JOIN c IN f.children 
JOIN p IN c.pets

You'll see each pet listed with its owner and family: Henriette's rabbit Fluffy, Jesse's dog Goofy and horse Shadow, and Emma's cat Whiskers. Notice that Lisa doesn't appear in the results since her pets array is empty, demonstrating the INNER JOIN behavior.

Cross Product JOIN – Combining Independent Arrays

To associate every child with all of their family's characteristics or tags to understand patterns and preferences, join two arrays from the same document to create a cross product pairing each child with each family tag.

SELECT f.id, c.firstName AS child, t AS tag 
FROM f 
JOIN c IN f.children 
JOIN t IN f.tags

This creates every possible child-tag pairing within each family: Henriette appears three times (paired with "seattle", "active", and "family-friendly"), Jesse and Lisa each appear twice (with "newyork" and "urban"), and Emma appears twice (with "boston" and "academic").

JOIN on Primitive Arrays

Analyzing common characteristics across your entire dataset requires flattening simple value arrays. JOINs work on arrays of primitive values like strings or numbers, in addition to complex objects.

SELECT f.id, f.lastName, t AS tag 
FROM f 
JOIN t IN f.tags

Each tag becomes its own row associated with its family: the Andersen family contributes three tags ("seattle", "active", "family-friendly"), while Wakefield and Miller each contribute two tags.

Self-JOIN – Finding Combinations

Analyzing which characteristics tend to appear together in your data (such as discovering that families tagged "urban" are also often tagged "active") requires finding unique pairs within the same array. You achieve this by joining an array with itself using different aliases.

SELECT f.id, t1 AS tag1, t2 AS tag2 
FROM f 
JOIN t1 IN f.tags 
JOIN t2 IN f.tags 
WHERE t1 < t2

The Andersen family yields three unique pairs from their three tags ("active"+"seattle", "active"+"family-friendly", "family-friendly"+"seattle"), while Wakefield and Miller each produce one pair from their two tags – perfect for discovering which characteristics commonly appear together.

Complex Filters – Multi-Level Conditions

Real-world queries often require filtering on multiple criteria at different nesting levels, like finding all rabbits owned by families in Washington state for a local pet adoption program. You can combine conditions on both root document properties (location) and deeply nested array elements (pet type) in a single query.

SELECT f.id, f.address.state, c.firstName, p.name AS pet 
FROM f 
JOIN c IN f.children 
JOIN p IN c.pets 
WHERE f.address.state = 'WA' AND p.type = 'Rabbit'

The query pinpoints exactly what you're looking for: Henriette's rabbit Fluffy in the Andersen family from Washington state, filtering out all other pets and families in one efficient operation.

Code sample

A Python example demonstrating these JOIN scenarios is available in this GitHub Gist: cosmosdb_join_examples.py

To run the example, start the Azure Cosmos DB Emulator:

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

Download and run the script from the gist – it automatically sets up the database, loads the sample data, and runs each query scenario:

python cosmosdb_join_examples.py

Enhanced Operator Support

The emulator now supports operators related to string manipulation, array operations and more. Let's explore these capabilities using an employee dataset where each document contains personal information, skill tags, and performance scores.

[
    {
        "id": "1",
        "firstName": "Alice",
        "email": "alice@company.com",
        "tags": ["senior", "manager", "remote"],
        "scores": [85, 92, 78, 95]
    },
    {
        "id": "2",
        "firstName": "Bob",
        "email": "bob@company.com",
        "tags": ["junior", "developer"],
        "scores": [72, 88, 65, 91]
    },
    {
        "id": "3",
        "firstName": "Charlie",
        "email": "charlie@company.com",
        "tags": ["senior", "architect", "onsite"],
        "scores": [95, 87, 92, 89]
    }
]

String Operations

Build formatted contact lists by combining multiple fields:

SELECT CONCAT(e.firstName, ' - ', e.email) as contact FROM e

This produces formatted strings like "Alice – alice@company.com", useful for generating reports or user-facing displays.

Filter records based on text length for data validation:

SELECT e.firstName FROM e WHERE LENGTH(e.firstName) > 5

This returns only "Charlie" since it's the only name exceeding 5 characters.

Array Operations

Count elements in nested arrays to identify employees with multiple skills:

SELECT e.firstName, ARRAY_LENGTH(e.tags) as skillCount FROM e

This returns the number of tags each employee has – Alice and Charlie each have 3 skills, while Bob has 2.

Query specific array positions to filter by criteria like first performance score:

SELECT e.firstName FROM e WHERE e.scores[0] > 85

This returns "Charlie" whose first score (95) exceeds the threshold, enabling queries on specific elements without flattening the entire array.

Code sample

A Python example demonstrating these operator scenarios above is available in this GitHub Gist: cosmosdb_operator_examples.py

To run the example, start the Azure Cosmos DB Emulator:

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

Download and run the script from the gist – it automatically sets up the database, loads the sample data, and runs each query scenario:

python cosmosdb_operator_examples.py

Improved Subdocument Queries

The emulator now provides better support for querying nested object properties and subdocuments. Let's explore these capabilities using a user profile dataset where each document contains nested profile information, contact details, and settings.

[
    {
        "id": "1",
        "username": "user1",
        "profile": {
            "fullName": "John Doe",
            "age": 30,
            "contact": {
                "email": "john@example.com",
                "phone": "555-0101"
            }
        },
        "settings": {
            "theme": "dark",
            "notifications": true
        }
    },
    {
        "id": "2",
        "username": "user2",
        "profile": {
            "fullName": "Jane Smith",
            "age": 25
        },
        "settings": {
            "theme": "light",
            "notifications": false
        }
    }
]

Selecting Nested Properties with IS_DEFINED

This query selects nested properties while ensuring the parent object exists. It returns all usernames with their full names, correctly handling documents with defined profile objects:

SELECT c.username, c.profile.fullName 
FROM c 
WHERE IS_DEFINED(c.profile)

Checking Nested Properties

To identify users with complete contact information before processing, use this query that returns only users who have the profile.contact defined:

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

Handling Missing Properties

Cases where certain nested properties don't exist need to be handled gracefully. This query accesses a property that may not be present in all documents. It returns the document with the phone property omitted from results when it doesn't exist.

SELECT c.id, c.profile.contact.phone 
FROM c

Code sample

A Python example demonstrating these subdocument query scenarios above is available in this GitHub Gist: cosmosdb_subdocument_examples.py

To run the example, start the Azure Cosmos DB Emulator:

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

Download and run the script from the gist – it automatically sets up the database, loads the sample data, and runs each query scenario:

python cosmosdb_subdocument_examples.py

OpenTelemetry for Observability

OpenTelemetry is an open-source observability framework that provides a collection of tools, APIs, and SDKs for instrumenting, generating, collecting, and exporting telemetry data.

To activate OpenTelemetry in the Azure Cosmos DB Emulator, set the "--enable-otlp" flag to "true" (or ENABLE_OTLP_EXPORTER environment variable) when starting the Docker container. For example:

docker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol http --enable-otlp true

You can also use the "--enable-console" flag (or use the ENABLE_CONSOLE_EXPORTER environment variable) to enable console output of telemetry data that can be useful for debugging purposes.

Use Docker Compose to simplify OpenTelemetry setup with the Azure Cosmos DB Emulator. The configuration below connects the emulator with Jaeger (distributed tracing) and Prometheus (metrics collection):

Copy and save the following in a docker-compose.yml file:

services:
  jaeger:
    image: jaegertracing/jaeger:latest
    container_name: jaeger
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"
    networks:
      - cosmosdb-network

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    networks:
      - cosmosdb-network
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--web.enable-otlp-receiver'
      - '--storage.tsdb.path=/prometheus'

  cosmosdb_emulator:
    image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
    container_name: cosmosdb_emulator
    ports:
      - "8081:8081"
      - "1234:1234"
      - "9712:9712"
      - "8889:8889"
    environment:
      - ENABLE_OTLP_EXPORTER=true
      - ENABLE_CONSOLE_EXPORTER=true
    networks:
      - cosmosdb-network

networks:
  cosmosdb-network:

Also, make sure to create a prometheus.yml file in the same directory as your docker-compose.yml with the following content – this will ensure that Prometheus can scrape metrics from the Azure Cosmos DB Emulator:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'cosmosdb-emulator-metrics'
    scrape_interval: 5s
    static_configs:
      - targets: ['cosmosdb_emulator:8889']

If the emulator is already running, stop it first. Then start the entire stack (Azure Cosmos DB Emulator, Jaeger, and Prometheus) using Docker Compose:

docker-compose up -d

Wait for the services to start, and run the sample Python script from the previous sections (a few times) – this will generate some telemetry data.

Check the Jaeger UI at http://localhost:16686 to view distributed traces, search for specific operations, analyze request latency, and inspect the execution flow of your queries through the Azure Cosmos DB Emulator:

Check the Prometheus UI at http://localhost:9090 to query and visualize metrics, monitor request rates, track query performance statistics, and analyze resource utilization patterns from the Azure Cosmos DB Emulator.

For details, refer to the documentation

Health Probe

The emulator exposes health check endpoints on port "8080" that return a HTTP 200 OK response when all components (Gateway, Data Explorer, etc.) are fully operational.

This is particularly valuable for integration testing frameworks like Testcontainers, which provide waiting strategies to ensure containers are ready before tests run. Instead of using arbitrary sleep delays or log messages (which are unreliable since they may change), you can configure a waiting strategy that will check if the emulator Docker container is listening to the "8080" health check port.

Here's a Go example using testcontainers-go library:

func TestMain(m *testing.M) {
    req := testcontainers.ContainerRequest{
        Image:        emulatorImage,
        ExposedPorts: []string{"8081:8081", "8080:8080"},
        WaitingFor:   wait.ForListeningPort(nat.Port("8080")), // Wait for health check port
        // WaitingFor: wait.ForLog("PostgreSQL=OK, Gateway=OK, Explorer=OK, Ready=YES"), //this works but is less reliable, hence not recommended

    }

    _, err := testcontainers.GenericContainer(context.Background(), testcontainers.GenericContainerRequest{
        ContainerRequest: req,
        Started:          true,
    })

    if err != nil {
        log.Fatal(err)
    }

    // Create credential and client
    cred, err := azcosmos.NewKeyCredential(emulatorKey)
    if err != nil {
        log.Fatal(err)
    }

    client, err = azcosmos.NewClientWithKey(emulatorEndpoint, cred, nil)
    if err != nil {
        log.Fatal(err)
    }

    m.Run()
}

Available endpoints:

Endpoint	Purpose	Behavior
http://localhost:8080/alive	Liveness probe	Returns 503 if PostgreSQL and Gateway are unhealthy
http://localhost:8080/ready	Readiness probe	Returns 503 if any component is not operational (disabled components like Explorer are excluded)
http://localhost:8080/status	Status information	Always returns 200 with detailed JSON status for all components

Conclusion

The latest Azure Cosmos DB Emulator release eliminates key query limitations and adds observability features, enabling you to develop and test more complex scenarios locally. You can now implement advanced data access patterns with nested JOINs, leverage operator support for string and array manipulation, and monitor your application's behavior with OpenTelemetry. You can start using these capabilities to accelerate your development workflow and catch issues earlier in your development cycle.