Item collections en DynamoDB

Una item collection es el set de todos los items de una tabla (o índice) que comparten el mismo valor de clave de partición — una propiedad emergente de tu key schema.

En el momento en que dos items llevan la misma clave de partición, forman una collection, y esa collection se convierte en la unidad que DynamoDB te deja leer juntos en un solo Query.

Hazlo bien y tus lecturas vuelven en un solo round trip. Hazlo mal y te quedas atascado con un Scan.

¿Qué es una item collection de DynamoDB?

Una item collection de DynamoDB es el set de todos los items que comparten el mismo valor de clave de partición, guardados juntos y ordenados por sort key. La collection emerge de tu key schema. La collection es la unidad que un solo Query lee de forma eficiente, mientras que un Scan recorre cada partición.

• Una collection es solo «misma clave de partición».» Dos o más items con el mismo valor de clave de partición se guardan juntos, ordenados por clave de ordenación.
• Es la unidad de un Query eficiente. Query lee una collection; Scan recorre cada partición. Esa es toda la historia de rendimiento.
• Sin sort key, sin collection. Una tabla solo de clave de partición guarda un item por clave — nada que coleccionar.
• Dos límites muerden: el techo de 10 GB por collection cuando existe un LSI, y las particiones calientes por claves de baja cardinalidad.

El problema: leer items relacionados juntos

Digamos que llevas una flota de vehículos, cada uno streameando telemetría — velocidad, temperatura del coolant, nivel de fuel — cada pocos segundos. La lectura dominante es «dame las lecturas recientes del vehículo V-7741».

Si vienes de SQL, indexarías una columna vehicle_id y dejarías que el planner hiciera el trabajo. Un almacén clave-valor plano no tiene ese lujo.

Trata cada lectura como un registro aislado, así que esa pregunta significa escanear la tabla entera y filtrar. Lento, caro, y peor conforme crece la flota.

La respuesta de DynamoDB es hacer de «todas las lecturas de un vehículo» una cosa físicamente agrupada y direccionable directamente. Ese agrupamiento es la item collection.

Qué es de verdad una collection

DynamoDB guarda items en particiones, y enruta cada item a una partición hasheando su clave de partición. Cada item con el mismo valor de clave de partición se guarda junto y ordenado por sort key. Empiezan en una partición, pero sin un LSI DynamoDB puede partir una collection grande o caliente a través de particiones en un límite de sort key; solo un LSI fija la collection entera a una sola partición (por eso el tope de 10 GB de abajo es solo de LSI).

La AWS Developer Guide lo nombra exactamente. Los items que comparten un valor de clave de partición son una item collection, guardados juntos y ordenados por sort key.

Esta es la misma idea que introdujo el paper de Amazon Dynamo de 2007 — consistent hashing para asignar claves a nodos — extendida con una dimensión de sort para que items relacionados se sienten adyacentes en disco.

Como están adyacentes y ordenados, DynamoDB devuelve una corrida contigua de ellos con un solo seek. Por eso Query es barato y Scan no: Query lee una sola collection; Scan recorre cada partición.

Para formar una collection necesitas una clave primaria compuesta — una clave de partición y una sort key. Una tabla claveada solo en clave de partición tiene exactamente un item por valor de clave, así que no hay nada que coleccionar.

Nuestro ejemplo trabajado: vehículo → lecturas de telemetría

Modela el stream de telemetría con una clave compuesta. La clave de partición identifica el vehículo; la sort key es el timestamp de la lectura, que mantiene las lecturas en orden de timestamp (ascendente por defecto; pasa ScanIndexForward=false para newest-first).

Aquí viven dos collections — una por vehículo. El item META (metadata del vehículo) y todas las lecturas de V-7741 forman una collection; los items de V-7742 forman otra.

Dale a la metadata una sort key (META) que ordene antes que cualquier valor TS#..., y un solo Query con PK = "VEH#V-7741" devuelve el perfil del vehículo y sus lecturas juntos.

Ese es el patrón padre-e-hijos en el corazón del single-table design.

Cada caja es una item collection: misma clave de partición, items ordenados por sort key. Un Query lee exactamente una caja.

Hacer Query a una collection

Como la collection está ordenada por sort key, obtienes lecturas de rango gratis. Para sacar las lecturas registradas en una ventana de diez minutos para un vehículo, acotas la sort key:

# Query
KeyConditionExpression   vehicleId = :v AND recordedAt BETWEEN :from AND :to
ScanIndexForward         false        # newest first

La key condition te restringe a una collection (vehicleId = :v) y luego a un trozo contiguo de ella (recordedAt BETWEEN ...). DynamoDB solo lee esos items y solo te factura por ellos. ¿Solo quieres la metadata? recordedAt = "META" trae el único item META.

Construir estas key conditions y projection expressions a mano es engorroso. El DynamoDB Expression Builder genera el KeyConditionExpression, los ExpressionAttributeNames y los ExpressionAttributeValues por ti, para que los detalles de palabras reservadas y placeholders no muerdan.

Collections en índices

Un índice secundario tiene su propio key schema, así que forma sus propias item collections.

Añade un global secondary index claveado en depotCode (partición) y recordedAt (sort), y «todas las lecturas del depot DEP-LON-3, las más nuevas primero» se convierte en un solo Query contra la collection de ese índice — una lectura que la tabla base no puede servir.

Por eso importa el tipo de índice: gobierna qué collections puedes formar y cómo se comportan. Ver GSI vs LSI para el trade-off.

Una distinción afilada: un local secondary index (LSI) comparte la clave de partición de la tabla base, así que su collection está físicamente atada a la item collection base — y ese vínculo crea un límite duro, abajo.

Los límites que muerden

Las item collections son potentes, pero dos restricciones deciden cómo das forma a las claves:

• El límite de 10 GB del LSI. Cuando una tabla tiene uno o más índices secundarios locales, una sola item collection — los items base más sus proyecciones LSI para una clave de partición — no puede superar 10 GB. Superarlo y las escrituras que crecen la collection empiezan a fallar con ItemCollectionSizeLimitExceededException. Una tabla sin LSI no tiene ese techo por collection. Exactamente por eso un stream unbounded que no para de crecer (telemetría que nunca para) es un mal fit para un LSI: la collection solo crece. Un GSI obtiene sus propias particiones, así que esquiva el límite.
• Particiones calientes. Una collection vive en una partición, y una sola partición tiene throughput finito. Si un vehículo (o un depotCode) atrae una parte salvajemente desproporcionada del tráfico, puedes hot-spotear esa partición aunque la tabla en conjunto esté bien bajo su throughput provisionado. Adaptive capacity — cubierta en los deep-dives re:Invent de AWS «Advanced Design Patterns for DynamoDB» — aisla y sube claves calientes automáticamente, pero no puede rescatar una clave sin spread en absoluto. Elige claves de partición con alta cardinalidad para que el tráfico se reparte a través de muchas collections.

Míralo en DynoTable

La forma más rápida de construir intuición sobre collections es mirar una. En DynoTable, hacer Query a una clave de partición renderiza la collection entera como una lista contigua ordenada por sort key — el item META se sienta justo delante de sus lecturas con timestamp, en pantalla, sin reconstrucción mental.

Escollos y próximos pasos

• Sin sort key, sin collection. Una tabla solo de clave de partición no puede agrupar items relacionados. Si necesitas leer items juntos, necesitas una clave compuesta.
• No dejes que una collection LSI crezca sin cota. Los streams append-only pertenecen a un GSI (o a una clave de partición con time-bucket), no a un LSI, por el techo de 10 GB.
• Reparte tus claves de partición. Una collection solo escala tanto como la partición en la que vive. Las claves de partición de baja cardinalidad crean hot spots.
• Llega a Query, no a Scan. Las collections existen para que puedas leer items relacionados con un Query dirigido; caer a un Scan tira esa ventaja — ver Query vs Scan.

Boceta tu propio key schema, lanza un Query contra una clave de partición real y mira cómo vuelve la collection ordenada. Descarga DynoTable y explora las collections de tus tablas directamente.