Beginner9 min read

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 Query can return a sorted range (>=, BETWEEN, begins_with) under one partition key, with no Scan.
  • 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 keyComposite key
AttributesPartition key onlyPartition key + sort key
UniquenessPartition key valueThe pair of values
Items per partition-key valueOneMany
Query a rangeNo (at most one item back)Yes (begins_with, BETWEEN, >)
Natural fitLookup by idTime 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:

deviceIdreadingTstempChumidity
DEV#a1b22026-06-23T08:00:00Z21.448
DEV#a1b22026-06-23T08:05:00Z21.747
DEV#a1b22026-06-23T08:10:00Z22.146
DEV#c9d82026-06-23T08:00:00Z19.855

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 . This page is about choosing the key; item collections covers reading a collection as a unit and the size cap an LSI adds.

Collection: DEV#a1b2readingTs 08:00readingTs 08:05readingTs 08:10Query deviceId = DEV#a1b2

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).

Run the access patterns
Query deviceId = "DEV#a1b2"
ScanIndexForward = true

4 of 5 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
#deviceIdreadingTsAttributes
1DEV#a1b22026-06-23T08:00:00ZtempC=21.4, humidity=48
2DEV#a1b22026-06-23T08:05:00ZtempC=21.7, humidity=47
3DEV#a1b22026-06-23T08:10:00ZtempC=22.1, humidity=46
4DEV#a1b22026-06-23T08:15:00ZtempC=22.4, humidity=46
DEV#c9d82026-06-23T08:00:00ZtempC=19.8, humidity=55

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.

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 patternItemsData touchedEC read units
One Query, readingTs between start and end1020 KB2.5
10 × GetItem on full composite key1020 KB5
Query partition only, filter in app~105,000 (a year)~205 MB~26,000
Scan table, filter deviceId + time windowallwhole tabletable-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.500Zsorts first: "." comes before "Z"
2026-06-23T08:00:00Z
2026-06-23T09:00:00+02:0007: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 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 epoch numbers, sort correctly; raw localized dates don't.
  • Prefix it for one-to-many . A sort key like READING#2026-06-23T08:00:00Z lets you mix entity types under one partition and slice them with begins_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 .

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 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.

By Dmitriy · Updated