Originally posted on . 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 insourcePaths. 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 bydeploymentName,modelName, andendpoint.
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 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 for your Foundry resource ahead of time and have it ready to drop into.envfile.
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:
CODEgit 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.exampleto.envand fill in your Azure Cosmos DB account endpoint and Microsoft Foundry deployment details:
CODEcp .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:
CODEaz 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
embeddingSourceblock with source path/description, modeltext-embedding-3-small, and output stored at/embedding. It adds aquantizedFlatvector index on/embeddingso you can query the embeddings in step 4.
Run the script:
CODEpython 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, aname, adescription, acategory,tags, and a few other fields — but only/descriptionis sent to the embedding model, per the policy you set in step 1.
CODEpython 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 , which combines vector similarity and full-text (BM25) ranking using Reciprocal Rank Fusion. You can also add a
WHEREclause 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 (for example
gpt-5.4) in your Microsoft Foundry resource and setFOUNDRY_CHAT_DEPLOYMENTin.envto the deployment name. The agent uses the sameFOUNDRY_API_KEYfor 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:
CODEpython rag_agent.py
Try out a few queries. For example, ask about a product category and the agent surfaces every relevant item:
CODEYou: 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:
CODEYou: 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/titleand/descriptionproduces a richer vector.
CODE{
"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_embeddingfrom/descriptionusingtext-embedding-3-large, and/title_embeddingfrom/titleusingtext-embedding-3-small.
CODE{
"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 to create a container with an
embeddingSourcepolicy and insert your first items.- Clone the for the complete reference.
We'd love your feedback during preview! Reach out to us at [email protected].
SOCIAL SHARE CARD GENERATOR