Cosmos DB Vector Search and the Change Feed
Exam domain: Develop AI solutions by using Azure data management services (25-30%), skill group Azure Cosmos DB for NoSQL (embeddings, vector similarity search, change feed processor).
Why store vectors next to the data
An embedding is a list of numbers produced by a model (for example an Azure OpenAI embeddings deployment) so that semantically similar text lands close together. Cosmos DB for NoSQL stores the vector as a normal property of the item, so the vector and its source data live in one document with one consistency model, with no second database to synchronize.
json{
"id": "doc-17",
"tenantId": "contoso",
"title": "Return policy",
"text": "Items can be returned within 30 days...",
"contentVector": [0.0132, -0.0451, 0.0087]
}Step 1: enable the feature
Vector search is a per-account capability:
bashaz cosmosdb update --resource-group rg-ai --name shop-cosmos \ --capabilities EnableNoSQLVectorSearch
It is auto-approved but can take about 15 minutes. Once enabled on a container it cannot be disabled, and it is not supported on accounts with shared throughput.
Step 2: container vector policy
The vector embedding policy tells the engine what the vectors look like. One policy per path.
| Property | Meaning | Values |
|---|---|---|
path |
Where the vector is | Required, for example /contentVector |
dataType |
Element type | float32, float16, int8, uint8 |
dimensions |
Length of every vector | Default 1536. Must match your embedding model |
distanceFunction |
How "close" is measured | cosine (default), dotproduct, euclidean |
Using float16 instead of float32 roughly halves storage at a small accuracy cost.
Step 3: vector index
| Index type | Search | Max dimensions | Use it when |
|---|---|---|---|
flat |
Exact brute force, 100% recall | 505 | Small, filtered searches |
quantizedFlat |
Brute force over compressed vectors | 4096 | Roughly 50,000 vectors or fewer per search scope |
diskANN |
Approximate nearest neighbor | 4096 | More than ~50,000 vectors, large scale, lowest latency and RU |
quantizedFlatanddiskANNneed at least 1,000 vectors indexed to quantize accurately. With fewer, the engine falls back to a full scan and RU charges can be higher.- You cannot change a vector embedding policy or vector index settings in place. You drop the policy or index and add it again with the new configuration.
- Add the vector path to
excludedPaths(as/contentVector/*) so the vector is only indexed by the vector index and not also as an ordinary array property. The reference examples do this. - Wildcards and vector paths nested inside arrays are not supported.
pythonfrom azure.cosmos import PartitionKey
vector_policy = {
"vectorEmbeddings": [{
"path": "/contentVector",
"dataType": "float32",
"distanceFunction": "cosine",
"dimensions": 1536,
}]
}
indexing_policy = {
"indexingMode": "consistent",
"includedPaths": [{"path": "/*"}],
"excludedPaths": [{"path": "/_etag/?"}, {"path": "/contentVector/*"}],
"vectorIndexes": [{"path": "/contentVector", "type": "diskANN"}],
}
container = database.create_container_if_not_exists(
id="docs",
partition_key=PartitionKey(path="/tenantId"),
indexing_policy=indexing_policy,
vector_embedding_policy=vector_policy,
)Step 4: query with VectorDistance
pythonquery = """
SELECT TOP 5 c.id, c.title,
VectorDistance(c.contentVector, @embedding) AS SimilarityScore
FROM c
WHERE c.tenantId = @tenant
ORDER BY VectorDistance(c.contentVector, @embedding)
"""
results = container.query_items(
query=query,
parameters=[
{"name": "@embedding", "value": question_embedding}, # same model as the stored vectors
{"name": "@tenant", "value": "contoso"},
],
partition_key="contoso",
)- Always use
TOP N. Without it the query tries to return many more results and costs more RUs and latency. - The
WHEREclause can combine ordinary filters with the vector search (for example a tenant or category filter), which is the base of a RAG retrieval step. - Use the same embedding model and the same dimensions for the stored vectors and the query vector.
diskANNis approximate: the same query can return a slightly different order or set. If you need exact results, useflat. TheVectorDistanceoptionsearchListSizeMultipliertrades latency and RUs for recall.- Indexed vectors work best with real embeddings, not random numbers.
The change feed
The change feed is a persistent, ordered record of inserts and updates in a container (ordered per partition key). In the default latest version mode it shows the latest state of each changed item and does not include deletes. All versions and deletes mode (preview) also surfaces deletes and intermediate versions.
Typical uses: keep a search index or vector store in sync, trigger downstream work, materialize views, audit.
The change feed processor
The processor library is a distributed, fault-tolerant consumer. It has four parts:
| Part | Role |
|---|---|
| Monitored container | The container whose changes you read |
| Lease container | State storage that records progress and coordinates workers. One lease document per partition range |
| Compute instance | A VM, pod or App Service instance hosting the processor, identified by a unique instance name |
| Delegate | Your code, called with each batch of changes |
Guarantees and behavior:
- At-least-once delivery. If your delegate throws, the same batch is retried from the last checkpoint, so make handlers idempotent.
- To avoid being stuck on a poison batch, catch exceptions and write the failed documents to an error queue or container, then continue.
- To scale out, run more instances with the same processor name and the same lease container, but a different instance name each. Leases are spread equally across instances. Do not run more instances than there are leases.
- A deployment unit is identified by the processor name plus lease container. Different business flows use different processor names and can share a lease container.
- By default a new processor reads only changes made after it first starts. In latest version mode you can set a start time, or read from the beginning.
- A global account endpoint with
ApplicationRegionorApplicationPreferredRegionsis the right way to pick a region. A regional endpoint creates region-scoped leases. - Read operations on both the monitored and lease containers consume RUs, so throttling there delays processing.
Python: use the pull model or Azure Functions
The change feed processor library exists only for .NET and Java. In Python and Node.js you either:
- Use the change feed pull model, which gives direct access but leaves checkpointing (the continuation token) to you, or
- Host the processor through an Azure Functions Cosmos DB trigger, which runs the processor for you.
python# Pull model: you own the continuation token
for change in container.query_items_change_feed(is_start_from_beginning=True):
handle(change)python# Functions Cosmos DB trigger (Python v2 model): the lease container is managed by the trigger
@app.cosmos_db_trigger(
arg_name="documents",
database_name="shop",
container_name="orders",
connection="CosmosDbConnection",
lease_container_name="leases",
create_lease_container_if_not_exists=True,
)
def sync_orders(documents: func.DocumentList):
for doc in documents:
upsert_into_search_index(doc)Quick check
- Vector search returns too much and costs too many RUs. Add
TOP N. - 100% recall on a few thousand vectors with at most 500 dimensions.
flat. - 2 million vectors, lowest latency.
diskANN. - You must change
dimensionsafter the container exists. Drop and recreate the vector policy and index. - A Python app needs a change feed processor. Functions trigger, or the pull model with your own checkpoints.