Beginner8 min read

DynamoDB Item Collections

An item collection is the set of all items in a table (or index) that share the same value. Nobody declares it; it falls out of your key schema.

The moment two items carry the same partition key, they form a collection, and DynamoDB lets you read a collection together in one Query. Get it right and related items come back in one round trip; get it wrong and you're stuck with a Scan.

What is a DynamoDB item collection?

  • A collection is "same partition key." Items with the same partition key value are stored together, sorted by .
  • It's the unit of one Query. Query reads within one collection; Scan walks every partition.
  • It can mix item types. A parent item and its children can share the key, so one Query returns the profile and its history together.
  • One hard limit, only with an : a collection on a table with an LSI is capped at 10 GB. Without an LSI, DynamoDB can split a collection across partitions.

Say you run a fleet of vehicles, each streaming telemetry (speed, coolant temperature, fuel level) every few seconds. The dominant read is "give me the vehicle's profile and its recent readings" for vehicle V-7741.

Coming from SQL, you'd index a vehicle_id column and let the planner do the work. A plain key-value store treats every reading as an isolated record, so the same question means a filtered scan of the whole table, costlier as the fleet grows.

DynamoDB's answer is to make "everything about one vehicle" a physically grouped, directly addressable thing. That grouping is the item collection.

How DynamoDB stores a collection

DynamoDB routes each item to a partition by hashing its partition key, and stores items with the same partition key together, sorted by sort key. AWS names that group an item collection.

A collection starts on one partition. Without an LSI, DynamoDB splits one that grows large or hot across as many partitions as it needs (AWS docs). An LSI pins the collection to one partition, hence the 10 GB cap below.

Because the collection is sorted, a Query reads a contiguous range of it and bills only the items it reads.

To form a collection you need a : a partition key and a sort key. A table keyed on partition key alone has one item per key value, so there's nothing to collect. The composite primary key guide covers choosing that key.

Our worked example: vehicle → telemetry readings

Model the telemetry stream with a composite key. The partition key identifies the vehicle; the sort key is META for the profile and the timestamp for each reading. Readings sort oldest first; pass ScanIndexForward=false for newest first.

PK (vehicleId)SK (recordedAt)attributes
VEH#V-7741METAplate, model, depotCode
VEH#V-7741TS#2026-06-23T09:00:01ZspeedKph, coolantC, fuelPct, depotCode
VEH#V-7741TS#2026-06-23T09:00:06ZspeedKph, coolantC, fuelPct, depotCode
VEH#V-7741TS#2026-06-23T09:00:11ZspeedKph, coolantC, fuelPct, depotCode
VEH#V-7742METAplate, model, depotCode
VEH#V-7742TS#2026-06-23T09:00:02ZspeedKph, coolantC, fuelPct, depotCode

Two collections live here, one per vehicle. The META item and all of V-7741's readings form one collection; V-7742's items form another. Each reading also records its vehicle's depot, which the index section below relies on.

META sorts before any TS#... value, so a single Query on PK = "VEH#V-7741" returns the vehicle's profile and its readings together. That's the parent-and-children pattern at the heart of single-table design.

Collection · VEH#V-7742META — vehicle profileTS#09:00:02Collection · VEH#V-7741META — vehicle profileTS#09:00:01TS#09:00:06TS#09:00:11

Each box is one item collection: same partition key, items sorted by sort key. A Query reads exactly one box.

Run the access patterns
Query vehicleId = "VEH#V-7741"
ScanIndexForward = true

4 of 6 items read — one Query, one partition. The key condition filters before any data leaves it, so you pay only for the matches.

Base table, in stored order
#vehicleIdrecordedAtAttributes
1VEH#V-7741METAplate, model, depotCode
2VEH#V-7741TS#2026-06-23T09:00:01ZspeedKph, coolantC, fuelPct
3VEH#V-7741TS#2026-06-23T09:00:06ZspeedKph, coolantC, fuelPct
4VEH#V-7741TS#2026-06-23T09:00:11ZspeedKph, coolantC, fuelPct
VEH#V-7742METAplate, model, depotCode
VEH#V-7742TS#2026-06-23T09:00:02ZspeedKph, coolantC, fuelPct

The items and keys are this guide’s own example. Highlighted rows are what the one call above touches; the numbers show the order they come back in. “Items read” counts items, not read units — real billing rounds each read up to 4 KB blocks.

Querying a collection

Because a collection can hold more than one item type, the sort-key condition is how you pick which ones come back. To read only the readings, newest first:

# Query
KeyConditionExpression   vehicleId = :v AND begins_with(recordedAt, :ts)   # :ts = "TS#"
ScanIndexForward         false        # newest first

Drop the sort-key condition and the same Query returns the profile plus every reading; recordedAt = "META" fetches just the profile. Time windows (BETWEEN on a sortable timestamp) and paging past 1 MB are covered in the composite primary key guide.

Building these key conditions by hand is fiddly. The DynamoDB Expression Builder generates the KeyConditionExpression, ExpressionAttributeNames and ExpressionAttributeValues, so reserved words and placeholders don't bite.

Collections on indexes

A secondary index has its own key schema, so it forms its own item collections.

Because every reading carries depotCode, a global secondary index keyed on depotCode (partition) and recordedAt (sort) gathers all readings from depot DEP-LON-3 into one index collection, a read the base table can't serve.

Query it with depotCode = :d AND begins_with(recordedAt, :ts) and ScanIndexForward=false for newest first. Items without depotCode never enter the index, so copying it onto each reading is what makes this read work (sparse indexes).

That's why the index type matters: it governs what collections you can form and how they behave. See GSI vs LSI for the trade-off.

A local secondary index (LSI) shares the base table's partition key, so its entries live in the same collection as the base items, and that creates the hard limit below.

The limits that bite

Two constraints decide how you shape keys:

  • The 10 GB LSI limit. On a table with a local secondary index, one item collection (base items plus LSI entries for one partition key) can't exceed 10 GB; writes that would grow it fail with ItemCollectionSizeLimitExceededException.

    A table with no LSI has no such cap.

    To see it coming, set ReturnItemCollectionMetrics: "SIZE" on writes and alarm when a collection's estimate passes about 8 GB, as the LSI docs suggest.

    At the limit, delete items you no longer need from that collection, or move history to a new table or to S3. An LSI lives as long as its table, so append-only telemetry belongs on a GSI or a time-bucketed partition key from the start.

  • . A split can't spread one item or the leading edge of an ever-increasing sort key such as TS#…, so a hot vehicle or depot needs write sharding; hot partitions covers how.

See it in DynoTable

The fastest way to build intuition for collections is to look at one. In DynoTable, a Query on one partition key lists the collection in sort-key order: the META item sits right ahead of its timestamped readings, on screen.

A DynamoDB Query on one partition key in DynoTable, showing every item in the collection ordered by sort key.
A DynamoDB Query on one partition key in DynoTable, showing every item in the collection ordered by sort key.

Pitfalls and next steps

  • No sort key, no collection. A partition-key-only table can't group items, and its key schema can't change. Add a GSI keyed on the grouping attribute plus a sort attribute, or move to a new table (migrations).
  • Don't let an LSI collection grow unbounded. Append-only streams belong on a GSI (or a time-bucketed partition key), not an LSI, because of the 10 GB ceiling.
  • Spread your partition keys. Low-cardinality keys pile traffic onto a few collections; physical partitions explains the per-partition limits.
  • Reach for Query, not Scan. Collections exist so you can read related items with one targeted Query; see Query vs Scan.

Sketch your own key schema, run a Query against a real partition key, and watch the collection come back ordered. Download DynoTable and explore your tables' collections directly.

By Dmitriy · Updated