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)
Para RBAC importante son los roles
Cosmos DB Built-in Data Reader- only read opsCosmos DB Build-in Data Contributor- read/write ops
Follow connection best practices
Lo ideal es reusar una instancia de CosmosClient durante el ciclo de vida de la app. Esto mejora la performance y la eficiencia de recursos ya que el cliente mantiene cache, background ops y si lo descartamos con cada request, esto se pierde y añade latencia. Esto es crítico para AI apps.
lo ideal es registrar el CosmosClient como un singleton
from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential
# Code fragment - focus on client reuse pattern
class CosmosService:
def __init__(self, endpoint: str):
credential = DefaultAzureCredential()
self._client = CosmosClient(endpoint, credential=credential)
self._database = self._client.get_database_client("aidata")
self._products_container = self._database.get_container_client("products")
@property
def products(self):
return self._products_container
# Create once at application startup
cosmos_service = CosmosService("https://myaccount.documents.azure.com:443/")
Navegar la resource hierarchy
Después de crear el CosmosClient se navega por BBDD y contenedores a través de objetos con get_database_client() y get_container_client(). Estos recursos son lightweight client objects que referencian recursos específicos.
Estos recursos no hacen llamadas de red ni verifican que el recurso en sí exista.
# Code fragment - focus on navigating resource hierarchy
database = client.get_database_client("productcatalog")
products = database.get_container_client("products")
users = database.get_container_client("users")
# These operations use the container clients
item = products.read_item(item="product-123", partition_key="electronics")
CRUDs
Crear database y contenedores
- Usar
create_database()- si falla peta y avisa de duplicados create_database_if_not_exists()
# Code fragment - focus on idempotent database creation
database = client.create_database_if_not_exists(id="productcatalog")
print(f"Database ready: {database.id}")
Para crear un contenedor hay que especificar una partition key, que determina como se distribuyen los datos en particiones. Esta partition key referencia una propiedad JSON que existe en tus items.
el param offer_throuhput indica las RU/s - se puede ignorar si la BBDD usa shared throughput a través de contenedores
from azure.cosmos import PartitionKey
# Code fragment - focus on container creation with partition key
container = database.create_container(
id="products",
partition_key=PartitionKey(path="/categoryId"),
offer_throughput=400
)
ejemplo para autoscale throughput
# Code fragment - focus on autoscale throughput
from azure.cosmos import ThroughputProperties
container = database.create_container_if_not_exists(
id="inferencecache",
partition_key=PartitionKey(path="/modelId"),
offer_throughput=ThroughputProperties(auto_scale_max_throughput=4000) # Autoscale: 400-4000 RU/s
)
Create and update items
Hay varios métodos
- create_item() - inserta y falla si ya existe
upsert_item()- inserta y sobreescribereplace_item()- igual que el upsert pero soporta usaretagy la operación solo es OK si eletagdel item es igual que el que mandamos
ejemplo de replace usando etag
# Code fragment - focus on optimistic concurrency
from azure.cosmos import exceptions
item = container.read_item(item="product-12345", partition_key="electronics")
# Modify the item
item["price"] = 149.99
# Replace with etag check
try:
container.replace_item(
item=item["id"],
body=item,
if_match=item["_etag"] # Optimistic concurrency
)
except exceptions.CosmosAccessConditionFailedError:
print("Item was modified by another process")
Read items efficiently
Al hacer reads hay que elegir entre
- point reads
read_item(): retrieve de un single item por suidy partition key. Latencia y coste en RU/s más bajo. - queries: retrieve de múltiples items basado en filtros
point read
# Code fragment - focus on point read efficiency
item = container.read_item(
item="product-12345",
partition_key="electronics"
)
print(f"Product name: {item['name']}")
Delete items
ejemplo de borrado
# Code fragment - focus on delete operation
from azure.cosmos import exceptions
try:
container.delete_item(
item="product-12345",
partition_key="electronics"
)
print("Item deleted successfully")
except exceptions.CosmosResourceNotFoundError:
print("Item not found")
Handle response metadata
Ver metadatos de una request, como por ej. x-ms-request-charge (indica los RU consumidos)
# Code fragment - focus on response metadata
container.upsert_item(body=product)
# Access response headers
headers = container.client_connection.last_response_headers
request_charge = headers['x-ms-request-charge']
activity_id = headers['x-ms-activity-id']
print(f"RU charge: {request_charge}")
print(f"Activity ID: {activity_id}") # Useful for support requests