Composite Sort Keys in DynamoDB
A composite primary key is a partition key plus a sort key. What
you put in the sort key decides which reads are cheap: encode a hierarchy as one
delimited string, and a single Query reads an entire subtree in sort order.
How do composite sort keys work in DynamoDB?
A composite sort key packs a hierarchy into one delimited string, such as root/photos/2026/. Items under a partition key are kept in sort-key order, so begins_with(SK, "root/photos/") reads one contiguous slice: the subtree, in path order.
- Treat the sort key as a sortable address. Pack a path into it and the partition's items line up as the tree.
- A delimiter turns prefix matches into subtree reads.
begins_with(SK, "root/photos/")returns every descendant of that folder in one query. - Sort keys support range conditions, not arbitrary filters. You get
=,<,<=,>,>=,betweenandbegins_with, so design the key so the read you need is a prefix or a range. - The delimiter decides correctness. Pick one that can't appear in a path segment, and end every query prefix with it.
Why the sort key does the work
Coming from SQL, you'd model a folder tree with a parent_id self-join and walk it
recursively, one query per level. Against a key-value store with no joins, that is an
N+1 footgun.
DynamoDB stores the items under a partition key sorted by sort key, in UTF-8 byte order for strings (AWS: Query key conditions). If your sort key is the path, the stored order already matches the tree, and a subtree is one contiguous range.
Model a file-system tree
Say you're storing per-account file trees. One drive per account is the natural partition; the path inside it is the sort key.
| PK | SK | node_type | bytes |
|---|---|---|---|
| DRIVE#a91 | root/ | folder | - |
| DRIVE#a91 | root/docs/ | folder | - |
| DRIVE#a91 | root/docs/taxes.pdf | file | 88210 |
| DRIVE#a91 | root/photos/ | folder | - |
| DRIVE#a91 | root/photos/2026/ | folder | - |
| DRIVE#a91 | root/photos/2026/beach.jpg | file | 284910 |
| DRIVE#a91 | root/photos/2026/sunset.jpg | file | 512004 |
| DRIVE#a91 | root/photos/cover.jpg | file | 140228 |
Two conventions do the work:
PK = DRIVE#<account>keeps one account's whole tree in a single item collection, so any subtree read is a single-partitionQuery.SKis the full path with a trailing/on folders. That keeps the folderroot/photos/distinct from a file namedroot/photos, and it is the delimiter your query prefixes end with.
Read a subtree in one query
List everything under root/photos/: the folder, subfolders, and files, recursively:
Query
KeyConditionExpression = PK = :drive AND begins_with(SK, :prefix)
:drive = "DRIVE#a91"
:prefix = "root/photos/"
That returns root/photos/, root/photos/2026/, beach.jpg, sunset.jpg and
cover.jpg, in path order (2 sorts before c).
You pay only for the items in that slice, not the whole drive. A large subtree comes
back in 1 MB pages; follow LastEvaluatedKey for the rest.
Keep the trailing / in the prefix. begins_with(SK, "root/photos") also matches
root/photos-old/…, root/photos.zip and root/photos 2/.
In DynoTable, you run exactly this begins_with query against the path sort key and the
folder plus its descendants come back in path order, with no placeholder syntax to hand-write.
Need the raw KeyConditionExpression (names, values, and begins_with) for your own
code? Build and copy it in the
DynamoDB Expression Builder.

List one level, not the whole subtree
begins_with gives you the recursive read. "Direct children only" is a different
question, so model it with its own key. A FilterExpression runs after the read,
and you pay for every item it discards.
Add a GSI whose partition key is the drive and the parent folder, composed into
one string. Each item gets GSI1PK = DRIVE#<account>#<parent path> and
GSI1SK = <its own path>:
| PK | SK | GSI1PK | GSI1SK |
|---|---|---|---|
| DRIVE#a91 | root/photos/2026/ | DRIVE#a91#root/photos/ | root/photos/2026/ |
| DRIVE#a91 | root/photos/cover.jpg | DRIVE#a91#root/photos/ | root/photos/cover.jpg |
| DRIVE#a91 | root/photos/2026/beach.jpg | DRIVE#a91#root/photos/2026/ | root/photos/2026/beach.jpg |
Query GSI1 WHERE GSI1PK = "DRIVE#a91#root/photos/" returns 2026/ and cover.jpg,
and nothing deeper.
The drive has to be in that key. A GSI keyed on the parent path alone puts every
account's root/photos/ in one partition, and the listing returns other accounts'
files.
DynamoDB also supports
multi-attribute keys
on a GSI: up to four attributes each for the partition and sort key, so the index can
take PK and a parent attribute as they are, without a composed string.
It can also replace the packed path, on an index: store each level (up to four) in its own attribute and query them left to right. An item missing one of them stays out of the index, so that fits fixed-depth hierarchies only.
A variable-depth tree like this one, and any base-table sort key (always a single attribute), still uses the packed string.
Pick the delimiter carefully
The delimiter is part of your data contract. Two rules:
- It must never appear inside a path segment. If filenames can contain
/, a file nameda/bis indistinguishable from a folderaholdingb. Pick a reserved byte, such as#or a control character, and forbid it in segments. - Mind the sort order at boundaries.
/(0x2F) sorts before digits and letters, but space (0x20),-(0x2D) and.(0x2E) sort before it, sophotos-old/lists ahead ofphotos/. Subtrees stay contiguous; sibling order isn't a file explorer's.
Composite sort key vs. a parent pointer
Composite sort key (root/photos/2026/x) | Plain ID sort key + parent attribute | |
|---|---|---|
| Subtree read | One begins_with query | Recursive queries (N+1) or a GSI walk |
| Ordering | Path order, free | Must add an explicit sort attribute |
| Move / rename | Rewrite all descendants | Update one parent pointer |
| Direct-children list | Needs a children GSI | A GSI on parent |
Composite keys win when reads are subtree-shaped and ordering matters; the flat-ID model wins when the tree mutates constantly. Most read-heavy hierarchies, such as file trees, category trees and org charts, lean composite.
Pitfalls and next steps
- Don't over-stuff the key. Everything you encode is immutable and indexed by prefix only. Attributes you query by equality belong in their own fields or a GSI, not jammed into the sort key.
- A sort key can't do arbitrary
WHERE. Onlybegins_with,between, and comparisons. If you find yourself reaching for aFilterExpression, you've probably modeled the key wrong; see Query vs. Scan. - Going deeper on key design lives in single-table design; for when a subtree read needs an index instead of the base table, see GSI vs. LSI.
Build the begins_with key condition with the
Expression Builder, then
download DynoTable to run these prefix queries against your own
tables and watch a subtree come back in path order.


