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