DynamoDB Composite Primary Key: Partition + Sort Key
A composite primary key is two attributes: a partition key and a sort key. The partition key decides where an item lives; the sort key orders the items that share that partition key.
Coming from SQL, it's closer to a clustered index on (partition, sort) than
to a unique id column.
What is a DynamoDB composite primary key?
- Two parts, two jobs. DynamoDB hashes the partition key to pick a physical partition; the sort key orders every item that shares that partition-key value.
- Uniqueness is the pair. Two items can share a partition key value as long as their sort keys differ, which is how one partition-key value holds many items.
- The sort key enables ranges. A
Querycan return a sorted range (>=,BETWEEN,begins_with) under one partition key, with noScan. - Keys must be scalars. Partition and sort keys can only be string, number, or binary: no maps, lists or sets (AWS docs).
Simple key vs composite key
A simple primary key is just a partition key. It identifies one item, and
you read it back with GetItem; a Query on it returns at most that one item.
There's no range to read and no "give me the newest N".
A composite key adds the sort key, and that one addition turns a key-value lookup into ordered range reads.
| Simple key | Composite key | |
|---|---|---|
| Attributes | Partition key only | Partition key + sort key |
| Uniqueness | Partition key value | The pair of values |
| Items per partition-key value | One | Many |
Query a range | No (at most one item back) | Yes (begins_with, BETWEEN, >) |
| Natural fit | Lookup by id | Time series, one-to-many, history |
Model a sensor-readings table
Say you collect temperature samples from a fleet of field sensors. The access pattern is "get the readings for one device, newest first, within a time window". That's a textbook composite key.
Use the device id as the partition key and the reading timestamp as the sort key:
| deviceId | readingTs | tempC | humidity |
|---|---|---|---|
| DEV#a1b2 | 2026-06-23T08:00:00Z | 21.4 | 48 |
| DEV#a1b2 | 2026-06-23T08:05:00Z | 21.7 | 47 |
| DEV#a1b2 | 2026-06-23T08:10:00Z | 22.1 | 46 |
| DEV#c9d8 | 2026-06-23T08:00:00Z | 19.8 | 55 |
All three DEV#a1b2 readings share one partition-key value, so DynamoDB stores
them together, sorted by readingTs.
AWS calls the sort key the range attribute, a name that "derives from the way DynamoDB stores items with the same partition key physically close together, in sorted order by the sort key value" (AWS docs).
The items under one partition key form an item collection. This page is about choosing the key; item collections covers reading a collection as a unit and the size cap an LSI adds.
One Query against the partition key reads that device's readings already in
timestamp order, so the client does no sorting.
Each response page stops at 1 MB. A device that reports every five minutes
builds about 105,000 readings a year, so follow LastEvaluatedKey for the rest
(pagination).
What that window costs
Suppose each reading carries about 2 KB, and the window holds ten of them:
20 KB in all. A Query adds up the sizes of the items it reads and rounds the
total up to the next 4 KB once.
So an eventually consistent Query on that window costs 2.5 read units
(five 4 KB blocks × 0.5), and a strongly consistent one costs 5. Provisioned
tables count these as RCUs, on-demand tables as read request units.
Ten separate GetItem calls round up per item instead: each 2 KB reading is a
whole 4 KB block, so 5 units eventually consistent and 10 strongly
consistent, plus ten round trips.
| Read pattern | Items | Data touched | EC read units |
|---|---|---|---|
One Query, readingTs between start and end | 10 | 20 KB | 2.5 |
10 × GetItem on full composite key | 10 | 20 KB | 5 |
Query partition only, filter in app | ~105,000 (a year) | ~205 MB | ~26,000 |
Scan table, filter deviceId + time window | all | whole table | table-sized |
A filter doesn't cut that third row's bill. Without a sort-key condition the Query
reads the whole collection: a year of 2 KB readings is about 26,000 units over some 200
pages, kept or filtered.
Pass ReturnConsumedCapacity: TOTAL while prototyping; the
pricing calculator turns that unit count into
a monthly line item once you know requests per second.
Query the range, don't scan it
An ISO-8601 string sorts in time order only when every value uses one fixed
format: UTC with a Z, and the same precision on every item. This table uses
YYYY-MM-DDTHH:MM:SSZ everywhere. Mix formats and the order breaks:
| 2026-06-23T08:00:00.500Z | sorts first: "." comes before "Z" |
|---|---|
| 2026-06-23T08:00:00Z | |
| 2026-06-23T09:00:00+02:00 | 07:00 UTC, yet sorts last |
With one format, a time-window read is a key-condition range, not a filter:
Query
deviceId = "DEV#a1b2"
readingTs BETWEEN "2026-06-23T08:00:00Z" AND "2026-06-23T08:10:00Z"
That's a KeyConditionExpression. It narrows the read before DynamoDB
returns data, so you pay only for the items in the window. A FilterExpression
runs after the read and bills you for every item it read: the
Scan footgun in miniature.
The expression itself, with placeholders and typed values, is fiddly to write
by hand. Build it visually with the
DynamoDB Expression Builder and copy the
exact KeyConditionExpression into your SDK call.
For that read, add a GSI keyed on a time bucket. Write
readingDay = "2026-06-23" on each reading, index it with readingTs as the
sort key, and Query the index with readingDay = :day AND readingTs > :eightAm,
once per day the window spans.
At fleet scale, shard that bucket from the start. One readingDay key takes every
write of the day: at the 10,000 readings a second used below, each 2 KB, that's
20,000 write units, twenty times the 1,000 a partition serves.
Because readingTs only grows, a split can't help. Use comfortably more than write
units ÷ 1,000 shards (2026-06-23#0 to #31 here, about 625 each), query every
shard and merge the results. Hot partitions covers the sharding.
A throttled GSI throttles the base table too: a table write succeeds only when every GSI has the write capacity for it.
Design the sort key on purpose
Only the sort key supports range conditions, so shape it to your queries.
- Use a sortable timestamp. ISO-8601 strings in one fixed UTC format, or zero-padded epoch numbers, sort correctly; raw localized dates don't.
- Prefix it for one-to-many overloading. A sort key like
READING#2026-06-23T08:00:00Zlets you mix entity types under one partition and slice them withbegins_with. That's the seam into single-table design. - Put the high-cardinality dimension in the partition key. Device id has
thousands of values, so it spreads writes evenly. A low-cardinality partition
key (say,
region) creates a hot partition.
Say region has five values and the fleet writes 10,000 readings per second,
each about 2 KB. That's about 4,000 write units per second on each region
key, four times the 1,000 a single partition serves.
Because readingTs only grows, every new write lands at the tail of the
collection, where a split can't spread it
(physical partitions). Keyed on 5,000
device ids, the same stream is about 2 writes per second per key.
When a composite key bites you
Composite keys are a commitment. You pick a partition key, ship, then discover an access pattern that needs a different grouping: "all readings above 30°C across the whole fleet".
The base table can't answer that, because the partition key is fixed. Use a
sparse GSI: write alertBucket = "HOT" only on readings above
30°C and key the GSI on alertBucket plus readingTs.
Readings without alertBucket never enter the index, so a Query on
alertBucket = "HOT" returns only the hot readings, in time order. Shard the
bucket if alerts are frequent. See sparse indexes.
Enumerate your reads before you commit the key schema, because a table's primary key can't change. A new key means a new table: create it, backfill it, dual-write during the cutover, then move reads over.
To backfill, export to S3 and import into a new table, which works when the new
key attributes already exist on every item (the import creates the table, without
LSIs). Otherwise Scan the old table and write each item with its new key.
Migrations walks through the cutover.
In DynoTable, a table's Overview lists the primary key and every secondary
index. Pick an index in the filter builder and run a Query: rows come back in
sort-key order, so a timestamp format that mis-sorts shows up before production.
Next steps
Composite keys lead straight into item collections, where the items under one key are read as a unit. Then read single-table design and GSI vs LSI.
Sketch your KeyConditionExpression in the
DynamoDB Expression Builder, emit the full
paginated Query in the query builder, then
try DynoTable to run these queries against your own tables and
watch the sort order line up.