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.