Intermediate6 min read

Composite Sort Keys in DynamoDB

A 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 : 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 =, <, <=, >, >=, between and begins_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.

PKSKnode_typebytes
DRIVE#a91root/folder-
DRIVE#a91root/docs/folder-
DRIVE#a91root/docs/taxes.pdffile88210
DRIVE#a91root/photos/folder-
DRIVE#a91root/photos/2026/folder-
DRIVE#a91root/photos/2026/beach.jpgfile284910
DRIVE#a91root/photos/2026/sunset.jpgfile512004
DRIVE#a91root/photos/cover.jpgfile140228

Two conventions do the work:

  • PK = DRIVE#<account> keeps one account's whole tree in a single , so any subtree read is a single-partition Query.
  • SK is the full path with a trailing / on folders. That keeps the folder root/photos/ distinct from a file named root/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.

Running a begins_with query on the path sort key in DynoTable, returning a folder and its descendants in path order.
Running a begins_with query on the path sort key in DynoTable, returning a folder and its descendants in path order.

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

PKSKGSI1PKGSI1SK
DRIVE#a91root/photos/2026/DRIVE#a91#root/photos/root/photos/2026/
DRIVE#a91root/photos/cover.jpgDRIVE#a91#root/photos/root/photos/cover.jpg
DRIVE#a91root/photos/2026/beach.jpgDRIVE#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 named a/b is indistinguishable from a folder a holding b. 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, so photos-old/ lists ahead of photos/. 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 readOne begins_with queryRecursive queries (N+1) or a GSI walk
OrderingPath order, freeMust add an explicit sort attribute
Move / renameRewrite all descendantsUpdate one parent pointer
Direct-children listNeeds a children GSIA 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. Only begins_with, between, and comparisons. If you find yourself reaching for a FilterExpression, 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.

By Dmitriy · Updated

Try this design interactively

Sketch your entities and access patterns in the free DynamoDB Single-Table Design tool — it suggests PK/SK key templates, previews the item collections, and shows which patterns need a GSI.

Open the Single-Table Design tool