Posts Tagged - cosmosdb

Understand Indexes (CosmosDB)

CosmosDB usa indexes para ejecutar queries eficientemente sin tener que escanear todos los contenedores.

Automatic index behaviour

By default CosmosDB hace un index de todas las propiedades en cada documento. Así las queries con cualquier propiedad pueden usar los índices inmediatamente sin configurar nada.

IMPORTANTE

Esto tiene trade-offs que son importantes cuando tu AI app escala. Cada índice consume almacenamiento y añade overhead a las write ops. Para aplicaciones que almacenan embedding arrays o texto sobre el que nunca se hacen queries, la default policy indexa datos sin necesidad.

/IMPORTANTE

Explorar index types

CosmosDB soporta múltiples tipos de índices, cada uno optimizado para query patterns diferentes. Estos 4 son los más relevantes para optimizar AI workloads.

  • Range index: soporta equality queries =, range queries <, <=, >, >=, != y ORDER BY en single properties. Soporta string functions como CONTAINS, STARTSWITH, ENDSWITH, IS_DEFINED y StringEquals. Usar (por ej) para filtrar documentos por type, status, date range.
  • Composite index: optimiza queries que ordenan o filtran por múltiples propiedades de manera simultánea. CosmosDB requiere un composite index que haga match exacto con la secuencia de propiedades y la sort direction.
  • Spatial index: permite geospatial queries functions ST_DISTANCE, ST_WITHIN, ST_INTERSECTS. Para AI apps que incorporan filtros por localización geográfica.
  • Vector index: Acelera búsquedas por similitud usando VectorDistance function (flat, quantizedFlat, diskAnn - está en otro post más en detalle)

Indexing mode

CosmosDB soporta dos indexing modes que controlar cuando y como se actualizan los indices

  • Consistent: el indice se actualiza de manera síncrona con cada write op. Las queries siempre reflejan el último estado. Modo por defecto.
  • None: Indexing desactivado en el contenedor. Puede mejorar la write performance para bulk ops, pero las queries sin indices ejecutan full scans. Solo para escenarios específicos donde nunca haces queries por propiedades secundarias

Index storage costs

Index size contribuye al total storage consumido por el contenedor. Esto depende de:

  • Cuantas propiedades tenemos indexadas: cada indice individual incrementa el coste. Tambien si tenemos estructuras nesteadas con muchos niveles
  • Cardinalidad: Propiedades con valores muy distintos entre ellos (o únicos) como IDs o timestamps requieren indices mucho más grandes que propiedades más similares.
  • Array elements: Cuando los arrays se indexan, cada elemento se indexa por si mismo. Arrays grandes con muchos elementos aumentan mucho el index storage.

IMPORTANTE

Para AI apps los embedding arrays pueden contener cientos de miles de valores numéricos. Si incluimos estas arrays en range indexes aumenta el gasto de almacenamiento muchisimo y esto no nos da ninguna ventaja a la hora de hacer queries. Las búsquedas vectoriales deben usar vector indexes. Excluir embedding paths de range indexes puede reducir el coste de almacenamiento substancialmente.

/IMPORTANTE

Incluir y excluir property paths

Indexing policies usan path expressions para especificar que propiedades se indexan. El sistema soporta wildcards

  • /* incluye todas las propiedades desde el root
  • /propertyName/? indexa el valor en la propiedad especificada
  • /arrayName/[] indexa los elementos dentro del array
  • /nested/path/* indexa todas las propiedades bajo el nested path

IMPORTANTE

A la hora de incluir y excluir paths que entran en conflicto, el más específico gana. Esto permite excluir grandes porciones del document tree a la vez que incluyes propiedades específicas que sean necesarias

/IMPORTANTE

indexa todas las propiedades (solo excluye _etag system property)

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    { "path": "/*" }
  ],
  "excludedPaths": [
    { "path": "/\"_etag\"/?" }
  ]
}

ejemplo de una selective indexing policy que indexa solo las propiedades usadas en las queries. Excluye por defecto todos los valores con /* mientras que las más específicas tienen preferencia

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    { "path": "/title/?" },
    { "path": "/category/?" },
    { "path": "/createdDate/?" },
    { "path": "/metadata/*" }
  ],
  "excludedPaths": [
    { "path": "/*" }
  ]
}

System property indexing

CosmosDB maneja los indices de algunas propiedades automaticamente.

  • id y _ts siempre se indexan y no se puede deshabilitar
  • _tag siempre se excluye. Se puede incluir manualmente pero es bastante raro que sea necesario.

La propiedad id sirve de identificador dentro de una partición.

Read More

Tune vector indexes for embedding workloads (CosmosDB)

Las AI apps que almacenan embeddings usan vector indexes para ejecutar búsquedas por similitud eficientes. Elegir el tipo correcto de vector index según tu workload afecta a la latencia, accuracy y RU/s consumidos.

Vector indexes in the indexing policy

Los vector indexes trabajan y residen junto a los range, composite y spatial indexes, dentro de la misma indexing policy.

Mientras que los otros tipos de indexes soportan filtering y sorting, los vector index aceleran las queries de similitud.

Antes de añadir un vector index hay que definir la vector policy para el contenedor que especifica las embedding properties.

ejemplo completo de indexing policy

este ejemplo muestra detalles importantes: el embedding path se tiene que excluir en excludedPaths para prevenir range indexing del embedding array. El vectorIndexes define un diskAnn index para los embeddings. Tenemos range y composite indexes que soportan metadata filters que podemos usar junto al vector search

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    { "path": "/category/?" },
    { "path": "/createdDate/?" },
    { "path": "/documentType/?" }
  ],
  "excludedPaths": [
    { "path": "/*" },
    { "path": "/embedding/*" }
  ],
  "compositeIndexes": [
    [
      { "path": "/category", "order": "ascending" },
      { "path": "/createdDate", "order": "descending" }
    ]
  ],
  "vectorIndexes": [
    { "path": "/embedding", "type": "diskANN" }
  ]
}

Select appropiate vector index type

CosmosDB ofrece 3 tipos de vector index.

Flat index - small datasets

Hace brute-force k-nearest neighbour search, comparando el query vector contra cada indexed vector. Da 100% accuracy porque evalua contra todos los vectores SIN aproximacion

Cuando usar flat index:

  • datasets pequeños con un vector count por partición física modesto
  • escenarios donde los query filters reducen significativamente el espacio de busqueda antes de la comparacion vectorial
  • apps que requieren una accuracy garantizada donde aproximar resultados no es aceptable

Limitaciones:

  • Max 505 dimensiones por vector
  • Latencia y consumo de RU/s más alto para large datasets porque se compara cada vector

Ejemplo: Los usuarios siempre filtran por categoría y cada categoría tiene unos pocos de cientos de documentos

QuantizedFlat index - medium datasets

Comprime vectores usando quantization antes de guardarlos en el índice. Reduce storage requirements y mejora query throughput al coste de un accuracy algo reducido

Cuando usar quantizedFlat:

  • datasets medianos con 1k - 50k vectores por particion fisica
  • apps donde es aceptable cambiar algo de accuracy por una mejor performance
  • escenarios donde combinamos metadata filters con vector search para reducir el set de candidatos

Características:

  • Soporta hasta 4096 dimensiones
  • Hace brute-force search sobre quantized vectors
  • Menor latencia y consumo de RU/s que flat index con resultados comparables de accuracy
  • Requiere minimo 1000 vectores antes de que el indice sea efectivo

Ofrece un balance de accuracy contra performance. Por lo general devuelve los mismos resultados que el flat index, pero ocasionalmente la quantization puede causar diferencias menores

DiskANN - large datasets

Aproxima al nearest neighbour mediante algoritmos de Microsoft. Crea estructuras de datos especializadas que permiten una fast vector search sin tener que comparar contra cada vector.

Cuando usar DiskAnn:

  • datasets grandes con >50k vectores por particion fisica
  • apps que requieren la menor latencia posible
  • workloads donde la eficiencia de RU/s es critica

Características:

  • Soporta hasta 4096 dimensiones
  • Tiene la menor latencia y RU/s cost
  • Mantiene una high accuracy
  • Requiere de al menos 1000 vectores antes de que el indice sea efectivo

Se recomienda para PROD AI apps con colecciones grandes de embeddings

Plan for vector policy immutability

Las vector policies no se pueden modificar después de la creación de un contenedor. Si queremos cambiarlas después, tenemos que crear un contenedor nuevo y migrar los datos.

Read More

Reduce RU costs with strategic indexing (CosmosDB)

RU/s consumption impacta directamente en el coste de tus workloads con CosmosDB. Queries que usen indices consumen RU/s proporcionalmente al result size, mientras que queries que hacen full scans consumen RU/s proporcionalmente al data size.

Analyze query patterns BEFORE deisgning indexes

Antes de diseñar indices hay que entender como la app hace query de los datos. Haz review de las queries e identifica que propiedades aparecen en los WHERE, ORDER BY y funciones agregadas.

  • Filter properties: ¿Que propiedades aparecen en el WHERE? ¿Son equalidad = o rangos >?
  • Sort properties: ¿Que propiedades aparecen en el ORDER BY y con que orden?
  • Property combination: Que propiedades aparecen juntas? Algunas filtran por una propiedad y luego ordenan por otra?
  • Access frequency: Con que frecuencia se ejecutan cada una? priorizar las más frecuentes

Usar query metrics para identificar que indices hacen falta

CosmosDB ofrece query metrics para ver como de eficientes son las queries al usar indices. Si hay queries que tienen una mala performance, las metricas pueden ayudar a identificarlas.

El SDK devuelve las siguientes metricas:

  • index utilization: porcentaje de la query que usa indexes vs scanning
  • retrieved document count: numero de documentos obtenidos del storage. Comparar los obtenidos del storage vs los devueltos. Una diferencia alta indica un filtrado ineficiente
  • output document count: Numero de documentos devueltos en los resultados

ejemplo que obtiene las métricas

from azure.cosmos import CosmosClient

client = CosmosClient(endpoint, credential)
database = client.get_database_client("documents-db")
container = database.get_container_client("documents")

query = "SELECT * FROM c WHERE c.documentType = @type ORDER BY c.uploadDate DESC"
parameters = [{"name": "@type", "value": "pdf"}]

# Use response_hook to capture query metrics from response headers
query_metrics_output = {}

def response_hook(headers, results):
    query_metrics_output["metrics"] = headers.get("x-ms-documentdb-query-metrics", "")
    query_metrics_output["request_charge"] = headers.get("x-ms-request-charge", "")

results = container.query_items(
    query=query,
    parameters=parameters,
    populate_query_metrics=True,
    response_hook=response_hook
)

# Process results (this triggers the query execution and response_hook callback)
items = list(results)

# Access captured query metrics
print(f"Query metrics: {query_metrics_output.get('metrics', '')}")
print(f"Request charge: {query_metrics_output.get('request_charge', '')} RUs")

Excluir properties no usadas en las queries

IMPORTANTE

Las propiedades que la app lee pero no se usan para filtrar NO. NECESITAN. INDICES. Excluir datos como large text fields, binary data o array embeddings que almacenamos y mostramos pero no filtramos por ellos.

/IMPORTANTE

Incluir partition key en el index

La partition key enruta queries a particiones específicas. Aún así las queries que filtran por partition keys también se benefician de range indexes dentro de cada partición.

CosmosDB no indexa la partition key automáticamente cuando usas exclude-by-default.

Design composite indexes for common query combinations

Composite indexes dan los mayores beneficios para queries usadas frecuentemente. Analizar que combinaciones de propiedades aparecen juntas y crear composite indexes para esos patrones.

Priorizar composite indexes por:

  • Query frequency: queries que se ejecutan miles de veces al dia tienen prioridad sobre otras que apenas se ejecutan
  • Data volume: Queries con large datasets consumen más RU/s según su tamaño
  • Filter complexity: Queries con multiples filtros con alta cardinalidad se benefician más

Cada composite index añade overhead a las write ops. Crear docenas de composite indexes para edge cases aumenta el coste de escritura y no tiene por que mejorar el de lectura. Hacer focus en los 5-10 patrones de queries que más impacto tengan

Write-heavy vs read-heavy workloads

No todas las apps se benefician de igual manera de los indices. Una app que escriba mucho y apenas lea le perjudica tener indices. En cambio una app que apenas escribe y solo lee puede ver util crear muchos composite index para todos los casos.

Monitor index transformation progress

Al crear un indice, este no toma efecto hasta que el proceso de transformation termina en background. Asi podemos monitorizar el progreso del transformation para saber cuanto lleva

# Check indexing progress through container properties
container_properties = container.read()
indexing_policy = container_properties.get("indexingPolicy", {})

# The Azure portal shows transformation progress as a percentage
# SDK access provides the policy but not real-time progress
# Use Azure portal or CLI for detailed progress monitoring

Read More

Configure range and composite indexes (CosmosDB)

Una AI apps puede ejecutar en una misma query una búsqueda semántica y filtrar por metadatos. Estas queries requieren configuraciones específicas de índices para ser eficientes. Si se hace mal puede aumentar drásticamente la latencia y el consumo de RU al tener que escanear múltiples contenedores.

Design range indexes for filter ops

Range indexes soportan los filtros más comunes para AI apps. Queries que filtran documentos por type, status, categoria o rangos de fechas usan range indexes para no tener que escanear el contenedor entero.

query que usa range indexes para filtrar por tipo y fecha

SELECT * FROM c
WHERE c.documentType = 'pdf'
  AND c.uploadDate > '2024-01-01'

Si ambos documentType y uploadDate tienes range indexes, CosmosDB usa los indices para encontrar documentos de manera eficiente. Sin índices la query hace un scan de la partición entera, consumiendo RU/s proporcional al tamaño y el result size

Configure composite indexes for multi-property sorting

Usamos composite indexes para queries que ordenan los resultados por múltiples propiedades. El composite index tiene que hacer match exacto de la secuencia de propiedades y la sort direction dentro del ORDER BY

añadimos los composite indexes

{
  "compositeIndexes": [
    [
      { "path": "/relevanceScore", "order": "descending" },
      { "path": "/uploadDate", "order": "descending" }
    ]
  ]
}

query que hace sort usando el índice creado

SELECT * FROM c
ORDER BY c.relevanceScore DESC, c.uploadDate DESC

IMPORTANTE

Un composite index que se declara con ambos DESC también soporta que ambos sean ASC. Lo que no soporta son orders mixtos como uno con DESC y otro con ASC. Esto requiere de otro indice

/IMPORTANTE

Optimize queries with both filters and ORDER BY

Muchas queries filtran por una propiedad y ordenan por otra. Estas queries se pueden optimizar incluyendo la propiedad filtrada dentro del ORDER BY

añadimos un composite index

{
  "compositeIndexes": [
    [
      { "path": "/documentType", "order": "ascending" },
      { "path": "/uploadDate", "order": "descending" }
    ],
    [
      { "path": "/category", "order": "ascending" },
      { "path": "/relevanceScore", "order": "descending" }
    ]
  ]
}

query que NO usa el índice

SELECT * FROM c
WHERE c.documentType = 'pdf'
ORDER BY c.uploadDate DESC

si añadimos la propiedad documentType al ORDER BY, permitimos que use el composite index

SELECT * FROM c
WHERE c.documentType = 'pdf'
ORDER BY c.documentType, c.uploadDate DESC

Use composite indexes for multi-property filters

IMPORTANTE

queries que filtran por múltiples propiedades se pueden beneficiar de composite indexes. Al diseñar composite indexes con filtros, los equality filters = tienen que ir primero en la definición. Cada composite index soporta COMO MUCHO un range filter, que tiene que ser el último en el índice.

/IMPORTANTE

añadimos el composite index

{
  "compositeIndexes": [
    [
      { "path": "/category", "order": "ascending" },
      { "path": "/department", "order": "ascending" },
      { "path": "/createdDate", "order": "ascending" }
    ]
  ]
}

query que usa el composite index

SELECT * FROM c
WHERE c.category = 'reports'
  AND c.department = 'finance'
  AND c.createdDate > '2024-06-01'

Si una query necesita multiples range filters, entonces necesitas multiples composite indexes, porque cada uno solo soporta un range filter

Tuples indexes for array element filtering

Usamos los tuple indexes para mejorar la eficiencia de las queries cuando filtramos por múltiples propiedades que están dentro de arrays.

Ejemplo: tenemos un documento que guarda text chunks con información de la posición

{
  "id": "doc-123",
  "title": "Annual Report 2024",
  "chunks": [
    { "position": 0, "text": "Executive summary...", "tokens": 150 },
    { "position": 1, "text": "Financial highlights...", "tokens": 200 },
    { "position": 2, "text": "Market analysis...", "tokens": 180 }
  ]
}

Un tuple index en el array chunks mejora la eficiencia de la query, indexando las combinaciones de propieades en cada array element

{
  "includedPaths": [
    { "path": "/*" },
    { "path": "/chunks/[]/{position, tokens}/?" }
  ]
}

Tenemos una query que encuentra chunks en posiciones específicas con minimum token count filters

SELECT c.id, chunk.text
FROM c
JOIN chunk IN c.chunks
WHERE chunk.position >= 0
  AND chunk.position < 3
  AND chunk.tokens > 100

Balance read/write performance

Esto resume muy bien el beneficio y el problema de trabajar con índices. Prestarle mucha atención y aprenderlo de memoria

IMPORTANTE

Cada index aumenta la write latency y el consumo de RU/s porque CosmosDB actualiza los indices de manera sincrona durante las write ops. AI apps con un alto volumen de throughput tienen que balancear el index coverage con la write performance.

Guidelines:

  • Include only queries properties: Si una propiedad se guarda pero nunca aparece en filtros de queries o sorting, excluirla del indice
  • Analyze query frequency: Crear composite indexes para queries que se ejecutan frecuentemente. Queries que solo ocurren de vez en cuando no justifican el write overhead del indice adicional
  • Monitor RU consumption: Comaprar el coste en RU/s antes y después de crear el indice. Si los writes son muy dominantes, es mejor tener pocos indices que realmente se aprovechen
  • Use selective indexing: En vez de incluir siempre todas las propiedades con /*, incluir explicitamente solo las que realmente queramos

/IMPORTANTE

Index transformation behaviour

  • Añadir indices: No hacen efecto hasta que se termina de crear y actualizar
  • Eliminar indices: Hace efecto inmediato al borrarlo
  • Reemplazar indices: Añadir primero el indice nuevo y esperar a que haga efecto. Borrar entonces el viejo. Esto asegura que las queries siempre tengan un indice que las soporte.

Read More

Choose consistency levels for optimal performance (CosmosDB)

(esto me parece demasiado a fondo para el examen)

CosmosDB consistency levels controlan el trade-off entre data freshness, latencia, throughput y disponibilidad.

Niveles de consistencia

Ordenadas de strongest a weakest.

Strong consistency

Los reads siempre devuelve el write más reciente.

Cuando el cliente escribe data a una region, un read desde cualquier region devuelve ese valor. Aumenta la latencia para multi-region accounts.

Read More

Use change feed to trigger embedding refresh (CosmosDB)

Es importante mantener los embeddings actualizados y sincronizados con el contenido actual. Si tenemos los embeddings desactualizados y el contenido de los documentos cambia, estaremos haciendo búsquedas en los embeddings sobre contenido que ya no existe.

Change feed

El change feed es un log persistente y ordenado de todos los inserts y updates de un contenedor. Las aplicaciones se suscriben al feed y procesan los cambios en tiempo real tal como pasan, lo que permite arquitecturas event-driven donde los updates a los embeddings ocurren a la vez que los cambios en los documentos

Un buen mecanismo de sincronización de embeddings debe tener:

  • persistent record: los cambios se almacenan y se procesan incluso si la App está offline
  • delivery ordenado: los cambios dentro de una partition key llegan en orden
  • Just-once opportunity: Cada cambio aparece una única vez en el feed
  • Automatic enablement: el change feed está enabled by default en todos los contenedores

Push / pull modes

CosmosDB ofrece dos maneras de consumir el change feed.

  • push model (entrega cambios a tu codigo automaticamente)
    • built-in partition management y load balancing a lo largo de múltiples instancias
    • es más sencillo
    • mejor para CD
  • pull model (eres tu quien hace pull de los cambios)
    • más control de cuando y como se integran los cambios
    • menos consumo
    • sin dependencias externas
    • util para batch refreshes

Para PROD el push model es más seguro y simple. Usar Azure Functions o el change feed processor library para implementar el push model

Azure Functions for change feed processing

IMPORTANTE

Azure Functions ofrecen la integración más simple con el change feed. El CosmosDB trigger invoca automáticamente la función cuando los documentos cambian, se encarga del partition management y mantiene checkpoints para seguir el progreso

/IMPORTANTE

regenera embeddings cuando los documentos cambian en el knowledge container

import azure.functions as func
from openai import AzureOpenAI
from azure.cosmos import CosmosClient
import os

app = func.FunctionApp()

@app.cosmos_db_trigger(
    arg_name="documents",
    container_name="knowledge-base",
    database_name="support-db",
    connection="CosmosDBConnection",
    lease_container_name="leases",
    create_lease_container_if_not_exists=True
)
def refresh_embeddings(documents: func.DocumentList):
    if not documents:
        return

    # Initialize clients
    openai_client = AzureOpenAI(
        api_key=os.environ["OPENAI_API_KEY"],
        api_version="2024-02-01",
        azure_endpoint=os.environ["OPENAI_ENDPOINT"]
    )

    cosmos_client = CosmosClient.from_connection_string(
        os.environ["CosmosDBConnection"]
    )
    container = cosmos_client.get_database_client("support-db").get_container_client("knowledge-base")

    for doc in documents:
        # Check if content that affects embeddings changed
        if should_refresh_embedding(doc):
            # Generate new embedding from updated content
            text_content = f"{doc.get('title', '')} {doc.get('content', '')}"

            response = openai_client.embeddings.create(
                input=text_content,
                model="text-embedding-ada-002"
            )

            # Update document with new embedding
            doc["embedding"] = response.data[0].embedding
            container.upsert_item(doc)

def should_refresh_embedding(doc):
    """Determine if the document needs a new embedding."""
    # Always refresh if no embedding exists
    if "embedding" not in doc or doc["embedding"] is None:
        return True

    # Check for content-related fields that affect embeddings
    # In a full implementation, compare against the previous version
    return True

La config del trigger especifica el contenedor a monitorizar knowledge-base, la BBDD support-db y el lease container leases para hacer tracking del progreso. La opción create_lease_container_if_not_exists crea automaticamente el lease container si se necesita.

Lease Container

El change feed processor (usado por Azure Functions triggers) requiere un contenedor separado para almacenar leases. Los leases hacen tracking de que particiones ownea cada instancia del processor y el track del progreso de cada particion. Esto da:

  • Checkpointing: Si el processing falla o se reinicia, lo retoma desde el último checkpoint en vez de comenzar de nuevo.
  • Coordination: Multiples processor instances se dividen las particiones, permitiendo un escalado horizontal
  • Failover: Si una instancia falla, otras adquieren su lease y continúan

Asegurarse que el lease container tiene un nombre diferente de los data containers. Múltiples funciones monitorizando el mismo data container pueden compartir un lease container si se usa leaseContainerPrefix

Selective embedding refresh

Refrescar los embeddings para cada documento es caro. Podemos implementar lógica para selective refresh para actualizar los embeddings solo cuando haya cambios en el contenido semántico.

comparar versiones de un doc para ver si es necesario un refresh

def should_refresh_embedding(current_doc, previous_doc=None):
    """
    Determine if document changes require new embeddings.
    Returns True if content affecting embeddings has changed.
    """
    # New document always needs embedding
    if previous_doc is None:
        return "embedding" not in current_doc

    # Check fields that contribute to the embedding
    content_fields = ["title", "content", "description", "summary"]

    for field in content_fields:
        current_value = current_doc.get(field, "")
        previous_value = previous_doc.get(field, "")

        if current_value != previous_value:
            return True

    # Metadata-only changes don't need new embeddings
    # Examples: category changes, status updates, access permission changes
    return False

Para PROD podemos hacerlo mediante un hash del contenido usado para generar un embedding. De esta forma es más eficiente. Al refrescar el contenido, actualizamos el hash

import hashlib

def compute_content_hash(doc):
    """Compute hash of content used for embedding generation."""
    text_content = f"{doc.get('title', '')} {doc.get('content', '')}"
    return hashlib.sha256(text_content.encode()).hexdigest()

def should_refresh_embedding(doc):
    """Check if content hash changed since last embedding."""
    current_hash = compute_content_hash(doc)
    stored_hash = doc.get("contentHash", "")

    return current_hash != stored_hash

High-volume changes

Para aplicaciones con cambios de embeddings frecuentes o mucho volumen es necesario tomar una estrategia:

  • Batch API calls: Agrupamos llamadas por batches
  • Rage limiting and backoff: Retry logic con backoff exponencial
  • Queue-based processing: Escribir cambios en un Azure Queue Storage y procesarlos con una función aparte. Esto hace decoupling de change detection y embedding generation, por lo que podemos hacer scaling por separado.
  • Prioritized refresh: priorizar documentos de alta prioridad vs baja prioridad y que vayan por separado con límites separados

Pull model con Python SDK

Esto lo hacemos mediante query_items_change_feed(). El continuation token guarda la posición en el change feed entre runs. Se puede guardar de manera persistente para asegurarse de no perder el por donde ibamos, y tener que reprocesar todo de nuevo.

from azure.cosmos import CosmosClient

cosmos_client = CosmosClient(endpoint, credential)
container = cosmos_client.get_database_client("support-db").get_container_client("knowledge-base")

def process_change_feed_batch():
    """Process a batch of changes using the pull model."""

    # Read changes from the beginning or from a continuation token
    change_feed_iterator = container.query_items_change_feed(
        start_time="Beginning"  # Or use a stored continuation token
    )

    continuation_token = None

    for page in change_feed_iterator.by_page():
        for change in page:
            if should_refresh_embedding(change):
                new_embedding = generate_embedding(change.get("content", ""))
                change["embedding"] = new_embedding
                change["contentHash"] = compute_content_hash(change)
                container.upsert_item(change)

        # Store continuation token for next batch
        continuation_token = change_feed_iterator.continuation_token

    # Save continuation_token for next run
    return continuation_token

Handle errors (idempotency)

Nuestra app tiene que ser idempotente. En algunas ocsasiones el change feed puede enviar varias veces el mismo cambio en casos de fallo. Debemos asegurarnos de que solo aplicamos los cambios una única vez.

Read More

Vector semantic search (CosmosDB)

Una vez tienes un container con documentos, los cuales contienen embeddings, ya podemos ejecutar queries por similitud vectorial para encontrar contenido semánticamente relacionado. Esto se hace mediante la función VectorDistance

Función VectorDistance

La función VectorDistance es el core de la búsqueda vectorial en CosmosDB. Calcula la similitud entre los embeddings de un documento y el vector de una query.

VectorDistance(c.embedding, [0.1, -0.2, 0.3, ...])

params

  • vector_1: document’s embedding path
  • vector_2: query vector
  • bool: brute-force search?

Basic vector search queries

IMPORTANTE

Una vector search query obtiene documentos ordenados por si similitud. INCLUIR SIEMPRE TOP N. Sin él devolvería todos los documentos, cobrando por ello.

/IMPORTANTE

SELECT TOP 10
	c.id,
	c.title,
	c.category,
	VectorDistance(c.embedding, @queryVector) AS SimilarityScore
FROM c
ORDER BY VectorDistance(c.embedding, @queryVector)

Para poder ejecutar una búsqueda vectorial hay que convertir la query del usuario a embeddings, usando el mismo modelo con el que hemos generado los embeddings del documento.

from openai import AzureOpenAI

# User's search query
query_text = "How do I fix WiFi connection problems?"

# Generate query embedding using the same model as documents
openai_client = AzureOpenAI(
    api_key=api_key,
    api_version="2024-02-01",
    azure_endpoint=endpoint
)

response = openai_client.embeddings.create(
    input=query_text,
    model="text-embedding-ada-002"
)
query_embedding = response.data[0].embedding

# Execute vector search
query = """
    SELECT TOP 10
        c.id,
        c.title,
        c.category,
        VectorDistance(c.embedding, @queryVector) AS SimilarityScore
    FROM c
    ORDER BY VectorDistance(c.embedding, @queryVector)
"""

results = container.query_items(
    query=query,
    parameters=[{"name": "@queryVector", "value": query_embedding}],
    enable_cross_partition_query=True
)

for item in results:
    print(f"{item['title']} - Score: {item['SimilarityScore']:.4f}")

Usar queries parametrizadas

Lo ideal es usar queries parametrizadas para pasar los embeddings mediante @queryVector

  • Esto hace hit con la cache
  • evita problemas con long query strings
parameters = [
    {"name": "@queryVector", "value": query_embedding}
]

results = container.query_items(
    query=query,
    parameters=parameters,
    enable_cross_partition_query=True
)

Interpretar similarity scores

La score depende de la distance function que haya configurado. Para cosine similarity:

  • +1.0: vectores idénticos
  • 0.7-0.9: contenidos MUY similares
  • 0.5-0.7: contenidos moderadamente similares
  • 0.1-0.5: contenidos poco similares
  • 0 o negativo: contenidos completamente diferentes

Para AI apps debemos filtrar contenido para quitar low-quality matches. Un límite mínimo de 0.7 filtra contenido altamente relevante, mientras que con 0.5 obtenemos contenido moderadamente relevante.

filtrar solo resultados >= 0.7

SELECT TOP 10
    c.id,
    c.title,
    VectorDistance(c.embedding, @queryVector) AS SimilarityScore
FROM c
WHERE VectorDistance(c.embedding, @queryVector) > 0.7
ORDER BY VectorDistance(c.embedding, @queryVector)

Control result count for different scenarios

El TOP N determina cuantos resultados devuelve la query. El valor óptimo depende según la app:

  • RAG applications: 5-10 resultados para obtener contexto relevante
  • User-facing search: 10-20 resultados siempre con paginación. Si un user no encuentra lo que quiere puede paginar más
  • Recommendation systems: 3-5 contenidos similares altamente relevantes

Por defecto las queries vectoriales usan el vector index configurado para beneficiarse de la velocidad. Las búsquedas mediante indexes pierden un poco de accuracy para obtener mejoras de performance. Si queremos revertir esto para una query podemos volver a una búsqueda de fuerza bruta pasando true como el tercer parámetro de VectorDistance

SELECT TOP 5
    c.title,
    VectorDistance(c.embedding, @queryVector, true) AS SimilarityScore
FROM c
ORDER BY VectorDistance(c.embedding, @queryVector, true)

Usarlo muy de vez en cuando ya que:

  • Compara la query vectorial contra cada documento del contenedor
  • Consume bastante más RUs que una query indexada
  • Tiene más latencia, especialmente para large datasets
  • Escala muy malamente cuantos más datos tengamos

Reservarlo para evaluation o testing, o cuando trabajamos con datasets pequeños donde nos dé igual la performance y el coste.

Optimize query performance

  • Elegir el index type correcto: diskANN es más potente pero más caro que quantizedFlat
  • Limitar result count: Usar TOP N. Pedir 100 resultados si el user solo ve 10 gasta recursos
  • Usar partition keys: incluir la partition key en las queries si se puede
  • Obtener solo campos necesarios: no pedir ampos que no se usan
  • Monitorizar RU consumption

Read More

Combine vector similarity results with metadata filtering (CosmosDB)

Las AI apps reales no usan búsqueda semántica pura. Muchas veces se combinan con filtros por categoría, fechas, permisos, etc. CosmosDB permite integrar queries vectoriales con queries tradicionales en una única query.

Add WHERE clauses to vector queries

Puedes combinar ambas. Los filtros se ejecutan antes o durante el cálculo de la distancia vectorial.

encontrar documentos semánticamente similares pero solo dentro de la categoría establecida y después de JAN 2026

query = """
    SELECT TOP 10
        c.id,
        c.title,
        c.category,
        c.createdDate,
        VectorDistance(c.embedding, @queryVector) AS SimilarityScore
    FROM c
    WHERE c.category = @category
        AND c.createdDate > @startDate
    ORDER BY VectorDistance(c.embedding, @queryVector)
"""

results = container.query_items(
    query=query,
    parameters=[
        {"name": "@queryVector", "value": query_embedding},
        {"name": "@category", "value": "networking"},
        {"name": "@startDate", "value": "2026-01-01T00:00:00Z"}
    ],
    enable_cross_partition_query=True
)

Pre-filtering and post-filtering

Al combinar filtros dentro de una misma query, el query optimizer determina si aplican antes de la comparación vectorial (pre-filtering) o después (ranking)

  • pre-filtering: reduce el espacio a buscar antes de la comparación vectoria. Si filtras 1.000 docs de un total de 100.000, la query vectorial solo se compara contra esos 1.000. Mejora la eficiencia al eliminar documentos
  • post-filtering: aplica filtros después de la query vectorial. Asegura una calidad pero puede devolver menos resultados de los pedidos si hay docs que fallan el filtro.

Optimize queries with partition keys

Al incluir la partition key en el WHERE, CosmosDB enruta solo a una única partición, en vez de escanear todas. Esto reduce mucho el consumo de RU y la latencia. Diseñar las particiones con esto en mente.

query = """
    SELECT TOP 10
        c.id,
        c.title,
        VectorDistance(c.embedding, @queryVector) AS SimilarityScore
    FROM c
    WHERE c.category = @category
    ORDER BY VectorDistance(c.embedding, @queryVector)
"""

# Query routes to single partition
results = container.query_items(
    query=query,
    parameters=[
        {"name": "@queryVector", "value": query_embedding},
        {"name": "@category", "value": "networking"}
    ],
    partition_key="networking"
)

Combine vector and full-text search - hybrid queries

Podemos combinar ambas en búsquedas híbridas usando Reciprocal Rank Fusion (RRF). RRF mergea rankings de diferentes scoring functions en un único result set unificado. Los documentos que rankean altos en ambos aparecen arriba, mientras que los que rankean solo en una, siguen apareciendo en los resultados.

Antes de usar la búsqueda híbrida, configurar el container con ambos una vector policy y una full-text policy.

{
    "defaultLanguage": "en-US",
    "fullTextPaths": [
        {
            "path": "/content",
            "language": "en-US"
        }
    ]
}

la indexing policy tiene que incluir ambas

{
    "vectorIndexes": [
        {"path": "/embedding", "type": "diskANN"}
    ],
    "fullTextIndexes": [
        {"path": "/content"}
    ]
}

con esto configurado, podemos usar ambas mediante ORDER BY RANK RRF

SELECT TOP 10 *
FROM c
ORDER BY RANK RRF(
    VectorDistance(c.embedding, @queryVector),
    FullTextScore(c.content, @searchTerm1, @searchTerm2)
)

Controlar hybrid search weights

Puedes ajustar los weights de cuanto pesa cada uno en los ranks finales de la RRF.

esta query da el doble de valor a la vector search, que a la full-text search

SELECT TOP 10 *
FROM c
ORDER BY RANK RRF(
    VectorDistance(c.embedding, @queryVector),
    FullTextScore(c.content, @searchTerm1, @searchTerm2),
    [2, 1]
)
  • higher vector weight: prioriza semantic understanding
  • higher full-text weight: prioriza exact keyword matches
  • equal weights: un buen punto de salida para búsquedas generales

Para el caso que tengamos múltiples embeddings por documento podemos usar RRF para buscar en múltiples espacios vectoriales

busca semántica en documentos por su título o contenido

SELECT TOP 10 *
FROM c
ORDER BY RANK RRF(
    VectorDistance(c.titleEmbedding, @queryVector),
    VectorDistance(c.contentEmbedding, @queryVector)
)

Performance trade-offs

Queries híbridas complejas con filtros consumen más RU/s que queries vectoriales simples.

  • Filtra selectivamente: Elimina documentos antes de buscar
  • Hybrid search costs more: Combinar VectorDistance con FullTextScore requiere consumir lo de ambas. Usarlo cuando haya beneficio claro.
  • Index all filter properties: Usar la clave de partición en el WHERE
  • Test with PROD data volumes
  • Monitor query metrics

Read More

Store and retrieve embeddings (CosmosDB)

CosmosDB guarda los embeddings como document properties. Se crea un unified data model para mantener los vectores justo a los metadatos en la misma BBDD

Understand vector embeddings

Los representaciones numéricas de datos generados por modelos de embeddings. Algunos servicios como Hugging Face ofrecen APIs para usar estos modelos. Se les pasa un input de texto, imágenes o similar y devuelve vectores.

Diferentes modelos de embeddings generan vectores diferentes.

Design document structure for vector storage

Al diseñar los documentos para vector search, guardamos los embeddings como un array en las propiedades junto a todos los datos.

Una estructura de documentos bien diseñada incluye:

  • Contenido original
  • metadatos relevantes para filtrar
  • embedding vectors
{
    "id": "doc-12345",
    "title": "Troubleshooting wireless network connections",
    "content": "This guide covers common WiFi connectivity issues including connection drops, slow speeds, and authentication failures...",
    "category": "networking",
    "productId": "router-x100",
    "createdDate": "2024-06-15T10:30:00Z",
    "embedding": [0.023, -0.041, 0.067, ...]
}

Configure container vector policies

CosmosDB requiere una vector policy al crear un contenedor que se va a usar para almacenar embeddings. Esta vector policy especifica properties que se usan para búsqueda por similitud.

Antes de usar vector search hay que activar la característica en Settings > Features > Vector Search for NoSQL API o mediante az cosmosdb update --capabilities EnableNoSQLVectorSearch

ejemplo de vector policy que guarda embeddings en el path /embedding

vector_embedding_policy = {
    "vectorEmbeddings": [
        {
            "path": "/embedding",
            "dataType": "float32",
            "distanceFunction": "cosine",
            "dimensions": 1536
        }
    ]
}
  • path: JSON path de la propiedad dentro de los docs que almacena los embeddings
  • dataType: float32, float16, int8, uint8 (default: float32)
  • dimensiones: número de elementos del vector. debe hacer match con el modelo de embeddings
  • distanceFunction: métrica usada para calcular la distancia cosine, dotproduct, euclidean (default: cosine)

Choose a distance function

(sin más, no entrar en tanto detalle)

De ella depende lo que se entiende por contenidos “similares”.

  • Cosine similarity: mide el ángulo entre dos vectores. ideal para vectores donde la magnitud no debe afectar a la similitud.
  • Dot product: mide el ángulo y la magnitud. Para vectores que están normalizados es más rápido que cosine, pero tienen que estar normalizados.
  • Euclidean distance: mide la distancia de la línea recta entre dos vectores. Para casos donde ambos dirección y magnitud importan, pero es menos común para text embeddings.

Data types for storage efficiency

IMPORTANTE

Hay que tener en cuenta la eficiencia. float32 da mucha precisión pero es más caro de almacenar. float16 reduce el coste de almacenamiento un 50% con un impacto mínimo en search quality.

int8 y uint8 da todavía más compresión a través de la cuantización. Estos tipos solo funcionan con embeddings que han sido cuantizados (convertidos de float a int values).

Para la mayoría de AI apps, float32 es el mejor balance por simpleza. Si los costes de almacenamiento son significantes, bajar a float16, siempre que el testing determine que la búsqueda es aceptable

/IMPORTANTE

Store multiple vector types per document

IMPORTANTE

CosmosDB soporta múltiples campos de embeddings por documento. De esta manera puedes generar embeddings diferentes para el título de un documento y su contenido, o guardar ambos embeddings de texto y embeddings de imagen.

/IMPORTANTE

embedding policy que soporta dos embeddings con dimensiones y distance function diferente

vector_embedding_policy = {
    "vectorEmbeddings": [
        {
            "path": "/titleEmbedding",
            "dataType": "float32",
            "distanceFunction": "cosine",
            "dimensions": 1536
        },
        {
            "path": "/contentEmbedding",
            "dataType": "float32",
            "distanceFunction": "cosine",
            "dimensions": 1536
        }
    ]
}

Configure vector indexes

Los vector indexes aceleran las búsquedas por similitud organizando los vectores para un querying eficiente. Sin un index cada query hace un full scan contra todos los vectores guardados.

CosmosDB ofrece tres vector index types

  • flat: guarda vectores en el main index y hace brute-force search. Limita los vectores a 505 dimensiones. Ideal para datasets pequeños o cuando necesitas resultados exactos.
  • quantizedFlat: comprime vectores antes del indexing (por eficiencia). Sigue siendo brute-force pero con menos latencia y coste de RU. Soporta hasta 4096 dimensiones y recomendado para datasets <= 50.000 vectores por partición física.
  • diskANN: Usa un algoritmo para búsquedas rápidas aproximadas. Soporta hasta 4096 dimensiones, y da mejor performance para datasets con millones de vectores

quantizedFlat y diskAnn requieren por lo menos de 1000 vectores antes de que el index sea efectivo. Con menos vectores hace un full scan

indexing_policy = {
    "indexingMode": "consistent",
    "automatic": True,
    "includedPaths": [
        {"path": "/*"}
    ],
    "excludedPaths": [
        {"path": "/\"_etag\"/?"},
        {"path": "/embedding/*"}
    ],
    "vectorIndexes": [
        {"path": "/embedding", "type": "diskANN"}
    ]
}

es importante excluir el embedding path de includedPaths ya que los embedding arrays no se benefician de standard range indexes.

Create a container with vector policies

Al crear un contenedor para vector search tienes que especificar ambos, vector embedding policy e indexing policy. Éstas solo se pueden poner en tiempo de creación. No se pueden añadir después.

from azure.cosmos import CosmosClient, PartitionKey

# Vector embedding policy
vector_embedding_policy = {
    "vectorEmbeddings": [
        {
            "path": "/embedding",
            "dataType": "float32",
            "distanceFunction": "cosine",
            "dimensions": 1536
        }
    ]
}

# Indexing policy with vector index
indexing_policy = {
    "indexingMode": "consistent",
    "automatic": True,
    "includedPaths": [
        {"path": "/*"}
    ],
    "excludedPaths": [
        {"path": "/\"_etag\"/?"},
        {"path": "/embedding/*"}
    ],
    "vectorIndexes": [
        {"path": "/embedding", "type": "diskANN"}
    ]
}

# Create container with vector support
container = database.create_container(
    id="knowledge-base",
    partition_key=PartitionKey(path="/category"),
    indexing_policy=indexing_policy,
    vector_embedding_policy=vector_embedding_policy
)

Additional resources

Integrated Vector Store - Azure Cosmos DB
Index and Query Vector Data in Python - Azure Cosmos DB
Azure OpenAI in Microsoft Foundry Models embeddings (classic) - Microsoft Foundry (classic) portal

Read More

Querying CosmosDB

CosmosDB for NoSQL soporta un lenguaje SQL-like optimizado para documentos JSON.

SELECT and filter results with WHERE

Las queries operan en un single container.

realmente es muy parecido a SQL aunque está muy limitado, por lo menos hasta donde llegué a usar yo en 2023

CosmosDB soporta los operadores =, !=, <, <=, >, >=, AND, OR, NOT

SELECT * FROM products p
WHERE p.categoryId = "electronics" AND p.price < 500

También soporta funciones como CONTAINS, STARTSWITH, ENDSWITH, UPPER, LOWER

SELECT * FROM products p
WHERE CONTAINS(p.name, "Speaker") AND p.price BETWEEN 50 AND 200

También IN y NOT IN para comparar contra listas

SELECT * FROM products p
WHERE p.category IN ("electronics", "appliances", "computers")

Read More

Implement SDK (CosmosDB)

Conectar usando el SDK

La clase CosmosClient es el punto de entrada. Solo pones el account endpoint y credenciales al crear el cliente, y usas el mismo para acceder a BBDD y contenedores.

from azure.cosmos import CosmosClient

# Code fragment - focus on client initialization
endpoint = "https://mycosmosaccount.documents.azure.com:443/"
key = "<your-account-key>"

client = CosmosClient(endpoint, credential=key)

Choose authentication method

Azure CosmosDB soporta dos métodos de auth:

  • account keys: secretos compartidos que dan full access a los recursos dentro de la cuenta. CosmosDB proporciona claves primarias y secundarias, lo que permite rotación sin downtime. Las claves NO se integran con access policies condicionales.
  • Entra ID: ideal para PROD. Usa RBAC. Asignas roles a usuarios, groups, service principals o managed identities y puedes dar acceso específicos a nivel de account, database o container.

La clase DefaultAzureCredential simplifica Entra ID auth seleccionando las credenciales apropiadas según el entorno. En local usa tu Azure CLI. En los entornos usa managed identity.

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

# Code fragment - focus on Entra ID authentication
endpoint = "https://mycosmosaccount.documents.azure.com:443/"
credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

Read More

Azure CosmosDB for NoSQL

Azure CosmosDB usa una estructura jerárquica para organizar y administrar los datos.

En CosmosDB se crea una account que sirve como top-level management unit. Ésta ofrece un endpoint único https://<account-name>-documents.azure.com:443 para todas las conexiones API y SDK. Cada subscripción de Azure puede contener múltiples cuentas de CosmosDB, lo que permite separar las BBDD por entornos.

Por defecto una Azure CosmosDB account puede contener hasta 500 bases de datos y contenedores combinados

Las AI apps suelen organizar los contenedores por área funcional. Lo suyo es separar por user data, product catalogs e inference results en contenedores diferentes dentro de la misma BBDD.

Un contenedor representa la unidad fundamental de escalabilidad y contiene tus JSON documents. Cada contenedor requiere de una partition key que determine como se distribuyen los datos a lo largo de las particiones físicas.

Los containers son schema-agnostic, por lo que diferentes items dentro del mismo contenedor pueden tener diferente estructura <- es la gracia de NoSQL

Read More

Azure CosmosDB Query Examples

This are examples of queries to use for Azure CosmosDB, as this database uses a restricted version of SQL and it doesn’t allow all queries or joins.

Partial queries

To be used with the main, partial query. This query starts with something such as SELECT * FROM c

WHERE c.ts LIKE "%2022/03/10%" 
ORDER BY c.ts DESC
WHERE c.type = "Writeable" 
AND c.ts LIKE "%2022/03/10, 15:2%" 
ORDER BY c.ts DESC

Full queries

Normal SQL queries to be used as custom queries. Note that CosmosDB doesn’t support a 100% of all SQL statements.

(count number of entries)

SELECT COUNT(1) FROM c 
	WHERE c.ts LIKE "%2022/03/10%" 
	ORDER BY c.ts DESC

Read More