What the preview does
Cosmos DB keeps vector embeddings in sync with your data automatically, so you no longer need separate pipelines to do it. In practice, you tell the container which item properties to embed, which Microsoft Foundry embedding model to call, and which path should hold the resulting vector. Cosmos DB then detects data changes and generates the embeddings asynchronously. It writes them back onto the items.
Without the feature, teams typically build code to track changes, call an embedding model, handle errors and retries, and write the vectors back. Microsoft's own blog post describes that pipeline as also needing to handle failures and retries, throttling, scaling, and monitoring as traffic grows. Integrated Embeddings moves much of that work into the database service.
Scope: The feature is documented for Azure Cosmos DB for NoSQL only. Don't read it as covering every Cosmos DB API. Earlier, separate work covered automatic embedding generation in the vCore-based Azure Cosmos DB for MongoDB, which an update tracker lists as a February 2025 preview.
Timeline: why the date looks odd
The Azure Updates entry carries a November 17, 2026 timestamp. Microsoft's Cosmos DB developer hub, however, lists the integrated embeddings public preview for NoSQL under June 2, 2026. The Cosmos DB engineering blog post is also dated early June. Microsoft's Ignite 2026 database roundup now cites automatic embedding generation for Azure Cosmos DB, now in public preview.
The November entry therefore looks like a refresh or re-surfacing of an existing preview. It probably isn't a brand-new launch. That is my inference from the dates. Microsoft hasn't said so explicitly in the material I reviewed.
Preview caveats
- No SLA. Microsoft says the preview has no service-level agreement and isn't recommended for production workloads.
- Gradual regional rollout. Availability varies by region, and the feature may not yet be accessible in yours.
- Partial tooling. Microsoft lists the data-plane and management-plane SDKs as partially supported. The Azure portal, Azure CLI and Bicep are listed as "coming soon" for configuring containers.
- Portal toggle. The documentation does describe an account-level portal step. You open the account's Settings, choose Features, select Integrated Embedding (preview), and enable it. Provisioning can take a few minutes. Enabling the feature doesn't start embedding generation by itself.
Prerequisites
Before you try it, you need:
- An Azure Cosmos DB for NoSQL account.
- All versions and deletes change feed mode enabled on the account.
- A Microsoft Foundry resource with a deployed Azure OpenAI embedding model.
- A system-assigned or user-assigned managed identity on the Cosmos DB account, set as the account's default identity.
- The Cognitive Services OpenAI User role granted to that managed identity on the Foundry resource, so Cosmos DB can call the model.
The documentation sets the default identity with az cosmosdb update. It takes --default-identity "SystemAssignedIdentity", or "UserAssignedIdentity=<resource-id>" for a user-assigned identity.
Supported models are text-embedding-3-large, text-embedding-3-small and text-embedding-ada-002.
How the container policy works
Configuration lives in the container's vector embedding policy. You add an embeddingSource object to the relevant vectorEmbeddings entry. It contains:
sourcePaths: the item properties to embed.deploymentName: the name of your Foundry deployment.modelName: the underlying model.endpoint: the Foundry resource endpoint.authType: currently onlyEntrais supported.
A few behaviors are worth knowing:
- Concatenated input. Cosmos DB concatenates the string values from all
sourcePathsinto one input per item. - 8,192-token limit. If the combined input exceeds that limit, the trailing portion is truncated before it goes to the model. The stored item isn't changed.
- Multiple vectors. You can define several vector paths, each with its own sources and model. Microsoft's example pairs
text-embedding-3-largefor a description withtext-embedding-3-smallfor a title. - Dimensions must match the model. The quickstart uses 1,536 dimensions for
text-embedding-3-smallandtext-embedding-ada-002. It uses 3,072 fortext-embedding-3-large.
Trying it today
The quickstart offers two routes, both built on SDKs:
- Data-plane SDK with account-key auth. There are Python and Node.js examples. They create a database and container, insert three sample items, and poll until the vectors appear.
- Management SDK with Entra ID. This uses Python with
azure-cosmos,azure-identityandazure-mgmt-cosmosdb. The identity running the script needs Cosmos DB Operator and Cosmos DB Built-in Data Contributor on the account.
Don't expect the embedding to exist right after the write. Because generation is asynchronous, the sample scripts poll every five seconds with a 120-second timeout. Those are sample settings, not a latency promise from Microsoft.
The samples use a quantizedFlat vector index. That's an example, not the only supported type.
A Microsoft Cosmos DB blog walkthrough also suggests a verification step in the Azure portal's Data Explorer. You run a query to count items with embeddings, and when the count matches your dataset, generation is done.
Cost: the part to read twice
Microsoft says you pay only for the underlying services:
- Foundry bills the embedding inference.
- Cosmos DB charges request units for writing each embedding back to the item.
- Change detection costs additional RUs. Cosmos DB retains the previous version of each changed item to do this reliably.
As a result, replace and delete operations carry an extra charge. It scales with item size, from 50% to 100% on top of the base write charge.
The documentation also says this is governed by an account-wide configuration. Every replace and delete in every container in the account is subject to the extra charge, not only the container using embeddings. Microsoft says this might change in a future release. If your account hosts busy transactional workloads next to an AI experiment, test this in a separate account.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Embedding missing on new or updated items | Not processed yet, item doesn't match policy, or generation failed | Feature enabled, embeddingSource in the container policy, item has the sourcePaths properties |
| Generation is slow | Change backlog or Foundry rate limiting | Write volume, Cosmos DB throughput, item size, Foundry deployment quota |
| Some items get embeddings, others don't | Missing, empty or null source properties | Compare a working item with a failing one |
Analysis
Embedding pipelines are boring plumbing that breaks at 2 a.m. Moving that plumbing into the database is a reasonable bet. The preview also keeps vectors tied to the item's current state, which is where hand-rolled pipelines tend to drift.
Several things argue for caution:
- Auth gap. The documented quickstart for the SDK route uses account keys, which many security teams discourage.
- Account-wide RU effect. The extra replace and delete charge can surprise teams that only meant to test one container.
- Coupling. Only Azure OpenAI embedding models via Foundry are supported. That ties your vector pipeline to one provider's deployment and quota.
- Maturity. There's no SLA and the portal, CLI and Bicep tooling isn't ready. Treat this as a proof-of-concept feature for now.
For teams already on Cosmos DB for NoSQL with vector search, this is worth a sandbox trial. Measure the RU overhead on your own workload before deciding anything.
References
- (In preview) Public Preview: Embedding generation in Azure Cosmos DB Azure Updates · 2026-11-17T20:00:32Z
- Integrated Embeddings in Azure Cosmos DB (Preview) - Azure Cosmos DB | Microsoft Learn learn.microsoft.com
- Integrated Embeddings in Azure Cosmos DB (Preview) - Azure Cosmos DB | Microsoft Learn learn.microsoft.com