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

Configurar partition keys para una distribución óptima

IMPORTANTE

Las partition keys es la decisión más crítica al crear un contenedor. CosmosDB usa esta partition key para enrutar operaciones a la partición física correcta y distribuir los datos de manera equitativa a través de tu infraestructura.

Una partition key bien pensada permite tener queries eficientes, un storage balanceado y un rendimiento óptimo.

La partition key debe usar una propiedad que exista en cada documento y tenga muchos valores distintos a lo largo de tu dataset

/IMPORTANTE

Para AI apps con user-specific data se usa userId como una partition key efectiva porque así agrupamos los datos de cada usuario juntos, manteniendo los datos partidos a lo largo de particiones.

Si tenemos catálogos de producto, sería recomendable usar categoryId para tener una buena distribución (siempre que las categorías contengan un número similar de items).

Evitar partition keys donde los valores estén poco distribuidos o sean siempre los mismos. Esto crea hot partitions donde distribuimos el tráfico y el storage de manera desproporcionada.

  • Un boolean isActive crearía solo dos particiones
  • Un valor como DateTime crearía particiones ilimitadas

ejemplo que crea un contenedor con una partition key para product data

from azure.cosmos import CosmosClient, PartitionKey

# Code fragment - focus on container creation with partition key
database = client.get_database_client("productcatalog")

container = database.create_container_if_not_exists(
    id="products",
    partition_key=PartitionKey(path="/categoryId"),
    offer_throughput=400
)

El path param especifica la JSON property path que sirve como partition key. Se pueden usar nested paths como /metadata/region

Una vez hemos creado un contenedor NO se puede cambiar la partition key - hay que migrar los datos a uno nuevo y eliminarlo

Configurar throughput para tu workload

CosmosDB mide la capacidad en request units per second (RU/s), que representan el throughput disponible para database ops. Cada operación consume RU/s según su complejidad, tamaño y consistency level. Esto incluye writes, queries y stored procedure executions.

Se puede provisionar throughput a dos niveles:

  • database level: comparte la capacidad a través de todos los contenedores de la BBDD. Funciona muy bien con contenedores que tienen patrones de uso variable
  • container level: dedica capacidad específica a un contenedor. Se usa cuando la performance es crítica

CosmosDB ofrece dos modos de throughput:

  • manual throughput: se especifíca un número fijo de RU/s (mínimo de 400 RU/s)
  • autoscale throughput: escala entre un mínimo (10% del máximo de RU/s configurado) y el máximo de RU/s (el valor máximo como poco tiene que ser de 1000 RU/s). Se basa en la demanda.

Work with items and system properties

Items son los documentos JSON individuales guardados dentro de los contenedores

Cada item contiene user-defined properties que representan application data + datos de sistema de CosmosDB. Cada item requiere de un property id. La combinación de id + partition key value sirve para identificar un item en el contenedor. Este id lo pone el usuario, no se crea automáticamente.

RU/s and cost optimization

Request units (RU/s) proporcionan un modelo de coste unificado. Incluyen y abstraen CPU, memoria, IOPS en una única métrica.

Cada operación devuelve el coste en RU en los headers de respuesta como x-ms-request-charge, lo que sirve para monitorizar y optimizar el coste.

El coste varía por operación:

  • read 1KB - 1 RU
  • write 1KB - 5 a 10 RU
  • simple query - 3-5 RU

Los RU/s se influencian por:

  • Item size
  • Indexing policy
  • Consistency level
  • Query complexity
  • Cross-partition queries

Additional resources

Databases, containers, and items - Azure Cosmos DB
Partitioning and horizontal scaling - Azure Cosmos DB
Provision Throughput for Containers and Databases - Azure Cosmos DB