{"id":12275,"date":"2026-06-02T12:15:34","date_gmt":"2026-06-02T19:15:34","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=12275"},"modified":"2026-06-02T13:57:34","modified_gmt":"2026-06-02T20:57:34","slug":"announcing-general-availability-of-the-azure-cosmos-db-vnext-emulator","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/announcing-general-availability-of-the-azure-cosmos-db-vnext-emulator\/","title":{"rendered":"Announcing General availability of the Azure Cosmos DB vNext emulator"},"content":{"rendered":"<p>The <strong>Azure Cosmos DB vNext emulator<\/strong> 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\u2019d rather not use a live account.<\/p>\n<p>You can get started right away with a couple of simple commands:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">docker pull mcr.microsoft.com\/cosmosdb\/linux\/azure-cosmos-emulator:vnext-latest\r\n\r\ndocker run -p 8081:8081 -p 8080:8080 -p 1234:1234 mcr.microsoft.com\/cosmosdb\/linux\/azure-cosmos-emulator:vnext-latest<\/code><\/pre>\n<p>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\u2019s new at GA and how to use it.<\/p>\n<p><iframe src=\"\/\/www.youtube.com\/embed\/qcmpIIKzfII\" width=\"560\" height=\"314\" allowfullscreen=\"allowfullscreen\"><\/iframe><\/p>\n<h2>Bootstrap and explore data with the bundled Azure Cosmos DB Shell<\/h2>\n<p><a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/shell\/overview\">Azure Cosmos DB Shell<\/a> is an open-source CLI for interacting with Azure Cosmos DB using bash-like commands. It\u2019s now bundled inside the emulator image, so you can drop into an interactive session against a running container without installing anything separately:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">docker exec -it &lt;container-name&gt; cosmoshell.sh<\/code><\/pre>\n<p>The wrapper auto-detects the emulator endpoint and authenticates with the well-known account key.<\/p>\n<p>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 <code>.csh<\/code> scripts at the top level of <code>\/init<\/code> in alphabetical order <em>before<\/em> the emulator is ready to accept requests. The bootstrap step moves out of your application and into the container itself.<\/p>\n<p>This is useful for many scenarios, including:<\/p>\n<ul>\n<li><strong>CI integration tests.<\/strong> Every job starts from an identical, deterministic dataset, with no app-side bootstrap and no readiness polling.<\/li>\n<li><strong>Local dev reset.<\/strong> Pair <code>--rm<\/code> with an <code>\/init<\/code> folder for a one-command reset back to a known state between runs.<\/li>\n<li><strong>Demos and tutorials.<\/strong> Ship fixture scripts next to your sample so readers see real data on first run, not an empty database.<\/li>\n<li><strong>Bug repros.<\/strong> Capture a problematic dataset as a small folder of scripts and attach it to an issue.<\/li>\n<\/ul>\n<p>The example below sets up a <code>ShopDB<\/code> with <code>Users<\/code> and <code>Orders<\/code> containers, both partitioned on <code>\/customerId<\/code> so a customer\u2019s orders co-locate with their profile. It uses separate scripts for each step.<\/p>\n<p><code>01-init.csh<\/code> creates the database and both containers. Adding <code>cd ShopDB<\/code> at the end means later scripts don\u2019t have to repeat <code>--database=ShopDB<\/code> on every line, since the shell session is shared across files.<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">mkdb ShopDB\r\nmkcon Users \/customerId --database=ShopDB\r\nmkcon Orders \/customerId --database=ShopDB\r\ncd ShopDB<\/code><\/pre>\n<p><code>02-load.csh<\/code> inserts a couple of users and a few of their orders:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">mkitem -container Users '{\"id\":\"u1\",\"customerId\":\"u1\",\"name\":\"Alice\",\"tier\":\"gold\"}'\r\nmkitem -container Users '{\"id\":\"u2\",\"customerId\":\"u2\",\"name\":\"Bob\",\"tier\":\"silver\"}'\r\nmkitem -container Orders '{\"id\":\"o1\",\"customerId\":\"u1\",\"total\":129.50,\"status\":\"shipped\"}'\r\nmkitem -container Orders '{\"id\":\"o2\",\"customerId\":\"u1\",\"total\":42.00,\"status\":\"pending\"}'\r\nmkitem -container Orders '{\"id\":\"o3\",\"customerId\":\"u2\",\"total\":18.75,\"status\":\"shipped\"}'<\/code><\/pre>\n<p>Mount the folder at <code>\/init<\/code> and start the container:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">docker run --name emulator --rm -e ENABLE_INIT_DATA=true \\\r\n-v \"$(pwd):\/init\" -p 8081:8081 -p 1234:1234 \\\r\nmcr.microsoft.com\/cosmosdb\/linux\/azure-cosmos-emulator:vnext-latest<\/code><\/pre>\n<p>By the time the emulator is up, both containers are populated and queryable. Verify with a one-liner that pulls Alice\u2019s orders:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">docker exec emulator cosmoshell.sh -c 'query \"SELECT c.id, c.total, c.status FROM c WHERE c.customerId = '\\''u1'\\''\" --container=Orders --database=ShopDB'<\/code><\/pre>\n<p>If you just want a quick look without writing any scripts, the image also ships with example seed scripts under <code>\/scripts\/init_examples\/<\/code> that load automatically when <code>ENABLE_INIT_DATA=true<\/code> is set. Or, if you need the seeded state to survive container restarts, bind-mount a host folder at <code>\/data<\/code> and the emulator will skip initialization on subsequent runs. The <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/emulator-linux#use-azure-cosmos-db-shell-with-the-emulator\">documentation<\/a> has the full set of options.<\/p>\n<h2>Vector search for local AI development<\/h2>\n<p>The emulator supports <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/vector-search\">vector search<\/a>, 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:<\/p>\n<pre class=\"prettyprint language-json\"><code class=\"language-json\">{\r\n  \"vectorEmbeddingPolicy\": {\r\n    \"vectorEmbeddings\": [\r\n      { \"path\": \"\/embedding\", \r\n        \"dataType\": \"float32\", \r\n        \"distanceFunction\": \"cosine\", \r\n        \"dimensions\": 1024 \r\n      }\r\n    ]\r\n  }\r\n}<\/code><\/pre>\n<p>Then, you can execute semantic search queries using the <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/nosql\/query\/vectordistance\">VectorDistance()<\/a> 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\u2019re iterating on your application.<\/p>\n<p>Try out this sample that embeds and loads data into the emulator. It uses <a href=\"https:\/\/www.langchain.com\/\">LangChain<\/a>, a popular open-source framework for building AI applications, and <a href=\"https:\/\/ollama.com\/\">Ollama<\/a>, a tool for running open-source models locally.<\/p>\n<p>You\u2019ll need Python 3.x, and Ollama installed locally.<\/p>\n<p>Start by running the emulator:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">docker run --detach --name emulator \\\r\n-p 8081:8081 -p 1234:1234 \\\r\nmcr.microsoft.com\/cosmosdb\/linux\/azure-cosmos-emulator:vnext-latest<\/code><\/pre>\n<p>Install Ollama, start the local server, and pull <code>mxbai-embed-large<\/code>. It produces 1024-dimension embeddings and is small enough to run comfortably on a developer laptop:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">curl -fsSL https:\/\/ollama.com\/install.sh | sh\r\nollama serve &amp;\r\nollama pull mxbai-embed-large<\/code><\/pre>\n<p>Clone the sample and install its dependencies in a virtual environment:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">git clone https:\/\/github.com\/abhirockzz\/cosmosdb-emulator-local-vector-search-example\r\n\r\ncd cosmosdb-emulator-local-vector-search-example\r\n\r\npython3 -m venv .venv &amp;&amp; source .venv\/bin\/activate\r\npip install -r requirements.txt<\/code><\/pre>\n<p>The sample reads its database name, container name, and embedding model from environment variables:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">export DATABASE_NAME=\"docsdb\"\r\nexport CONTAINER_NAME=\"docs\"\r\nexport EMBEDDINGS_MODEL=\"mxbai-embed-large\"\r\nexport EMBEDDING_DIMENSIONS=\"1024\"<\/code><\/pre>\n<p>Now load the data. <code>load_data.py<\/code> 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 (<code>\/embedding<\/code>, <code>float32<\/code>, <code>cosine<\/code> distance) and a DiskANN vector index.<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">python3 load_data.py<\/code><\/pre>\n<p>With the data loaded, you can run vector queries. <code>vector_search.py<\/code> takes a natural-language query, embeds it with the same local model, and runs a <code>VectorDistance()<\/code> query against the emulator container to return the <code>top-k<\/code> matching chunks by cosine similarity:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">python3 vector_search.py \"show me an example of a vector embedding policy\"<\/code><\/pre>\n<p>You\u2019ll 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:<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">python3 vector_search.py \"how do I tune recall vs latency for vector queries\"\r\npython3 vector_search.py \"best practices for multi-tenant vector workloads\"<\/code><\/pre>\n<h2>Other improvements<\/h2>\n<p>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.<\/p>\n<p><strong>Health probe endpoint<\/strong><\/p>\n<p>The emulator exposes dedicated health endpoints on port <code>8080<\/code>: <code>\/alive<\/code> for liveness, <code>\/ready<\/code> for readiness, and <code>\/status<\/code> for detailed status.<\/p>\n<p>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.<\/p>\n<p><strong>OpenTelemetry support<\/strong><\/p>\n<p>The emulator supports the <a href=\"https:\/\/opentelemetry.io\/\">OpenTelemetry Protocol (OTLP)<\/a> for exporting telemetry. With <code>--enable-otlp<\/code> (or <code>ENABLE_OTLP_EXPORTER=true<\/code>), 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, &#8211;enable-console (or <code>ENABLE_CONSOLE_EXPORTER=true<\/code>) 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 <a href=\"https:\/\/github.com\/Azure\/azure-cosmos-db-emulator-docker\/blob\/master\/docs\/opentelemetry.md\">live in the GitHub repo<\/a>.<\/p>\n<p><strong>Broader feature and API coverage<\/strong><\/p>\n<p>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, <code>JOIN<\/code>s, range and aggregate queries, subdocument queries, hierarchical partition keys, <code>TTL<\/code>, and an expanded set of string and array operators.<\/p>\n<p>For example, you can now query deeply nested properties and guard against missing fields in a single statement:<\/p>\n<pre class=\"prettyprint language-sql\"><code class=\"language-sql\">SELECT c.username, c.profile.contact.phone\r\nFROM c\r\nWHERE IS_DEFINED(c.profile.contact)<\/code><\/pre>\n<p>See the <a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/azure-cosmos-db-vnext-emulator-query-and-observability-enhancements\/\">preview enhancements post<\/a> for more query walkthroughs across JOINs, operators, and subdocuments.<\/p>\n<p>A few endpoints that aren\u2019t core to data operations (offers, users, permissions, etc.) are now accepted as no-ops. They return valid HTTP status codes but don\u2019t perform the underlying operation, so application code that happens to touch them won\u2019t break when pointed at the emulator.<\/p>\n<h2>Get started<\/h2>\n<p>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.<\/p>\n<pre class=\"prettyprint language-default\"><code class=\"language-default\">docker pull mcr.microsoft.com\/cosmosdb\/linux\/azure-cosmos-emulator:vnext-latest<\/code><\/pre>\n<p>If you hit an issue or have a feature request, please open it on the <a href=\"https:\/\/github.com\/Azure\/azure-cosmos-db-emulator-docker\/issues\">GitHub repository<\/a>.<\/p>\n<h2 id=\"about-azure-cosmos-db\"><strong>About Azure Cosmos DB<\/strong><\/h2>\n<p>Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.<\/p>\n<p>To stay in the loop on Azure Cosmos DB updates, follow us on\u00a0<a href=\"https:\/\/twitter.com\/AzureCosmosDB\" target=\"_blank\" rel=\"noopener\">X<\/a>,\u00a0<a href=\"https:\/\/aka.ms\/AzureCosmosDBYouTube\" target=\"_blank\" rel=\"noopener\">YouTube<\/a>, and\u00a0<a href=\"https:\/\/www.linkedin.com\/company\/azure-cosmos-db\/\" target=\"_blank\" rel=\"noopener\">LinkedIn<\/a>.\u00a0 Join the discussion with other developers on the\u00a0<a href=\"https:\/\/discord.gg\/pczdC2SU\" target=\"_blank\" rel=\"noopener\">#nosql channel on the Microsoft Open Source Discord<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 [&hellip;]<\/p>\n","protected":false},"author":181737,"featured_media":12519,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1980,2017],"tags":[],"class_list":["post-12275","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-azure-cosmos-db","category-azure-cosmos-db-tools"],"acf":[],"blog_post_summary":"<p>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 [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12275","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/181737"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=12275"}],"version-history":[{"count":2,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12275\/revisions"}],"predecessor-version":[{"id":12461,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12275\/revisions\/12461"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/12519"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=12275"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=12275"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=12275"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}