Key Overloading in DynamoDB
Coming from SQL, a column means one thing forever: tickets.created_at is always a
date, users.email is always an email. Key overloading throws that out. You
give the partition and sort key generic names (pk, sk) and let each
item type pour a different meaning into them.
Many entity types then share one table and one key shape.
What is key overloading in DynamoDB?
Key overloading is storing many entity types in one table under generic key names like pk/sk, encoding the type in the value (USER#u_3001, INVOICE#2026-0014). Users, invoices, and events can then share one partition, and a sort-key prefix lets one Query slice each entity via begins_with.
- Generic key names, typed values: name your keys
pk/skand put the entity type in the value, e.g.pk = "TENANT#acme",sk = "USER#u_3001". begins_withis the payoff: a type prefix on the sort key lets oneQuerypull a whole entity, or one slice of it, with noScanand no filter.- Readability is the cost: a raw
pk/skdump is hard to read. Write an explicitentityTypeattribute on every item so exports, Streams consumers and filters can branch on it without parsing prefixes.
Why generic names beat specific ones
DynamoDB gives you at most two key attributes per table, and a Query can only target a
single partition key. So if you name your key userId, only user items can live in
that table cleanly; everything else has to fake a userId or move to its own table.
A neutral name like pk doesn't commit to any entity, so a user, an invoice, and an
audit event can all share the same key attribute and the same table. This is what
makes single-table design queryable.
A multi-tenant example
Say you run a SaaS billing product. Each tenant has members, invoices, and an audit trail. Instead of three tables, put all of it in one and overload the keys:
| pk | sk | attributes |
|---|---|---|
| TENANT#acme | EVENT#2026-06-23T09:12Z | actor="u_3001", action="invite" |
| TENANT#acme | INVOICE#2026-0014 | amount_cents, status="paid" |
| TENANT#acme | INVOICE#2026-0015 | amount_cents, status="open" |
| TENANT#acme | META | name="Acme Inc", plan="team" |
| TENANT#acme | USER#u_3001 | email, role="admin" |
| TENANT#acme | USER#u_3002 | email, role="member" |
Every row shares pk = "TENANT#acme", so they form one item collection:
stored together and readable with one key condition. Rows come back in sort-key
order, which is why META lands between the invoices and the users. Name it #META
if you want it first.
The sort-key prefix groups entities and orders them.
Query the overloaded collection
Because the type lives in the sort-key prefix, begins_with slices the partition by
entity without scanning anything:
Query pk = "TENANT#acme" -- the entire tenant, every type
Query pk = "TENANT#acme" AND begins_with(sk, "USER#") -- just members
Query pk = "TENANT#acme" AND begins_with(sk, "INVOICE#") -- just invoices
You pay only for the items the condition matches, not the whole partition. A
filtered Scan is the opposite: you pay to read rows
you then throw away. AWS calls this a key condition; it runs on the keys before
any data leaves the partition.
Say the tenant has 200 users (2 KB each) and 5,000 audit events (1 KB each). The
USER# query reads ~400 KB: 100 read units strongly consistent, 50 eventually
consistent. A Scan to find users would meter every item in every tenant.
Each Query call returns at most 1 MB, so the whole-tenant read (~5.4 MB here)
takes several calls: pass each response's LastEvaluatedKey as the next
ExclusiveStartKey until it's absent.
Always include the delimiter in the prefix you query: begins_with(sk, "USER#")
skips USERGROUP# items, while begins_with(sk, "USER") matches both. A typo such
as USERS# returns nothing, with no error.
The
expression builder generates the
KeyConditionExpression and values map, and the
query builder emits the pagination loop.
Overload the index too
The same trick applies to a GSI. Give it generic key names (gsi1pk,
gsi1sk) and let each entity write whatever it needs. One index then answers
patterns the base table can't.
| pk | sk | gsi1pk | gsi1sk |
|---|---|---|---|
| TENANT#acme | INVOICE#2026-0015 | STATUS#open | 2026-06-30 |
| TENANT#acme | INVOICE#2026-0014 | STATUS#paid | 2026-06-12 |
| TENANT#beta | INVOICE#2026-0099 | STATUS#open | 2026-06-25 |
Now Query gsi1 WHERE gsi1pk = "STATUS#open" lists every open invoice across all
tenants, ordered by due date: a cross-partition view the base table's
tenant-scoped keys can't serve.
A different entity can reuse gsi1 with its own meaning (say
gsi1pk = "ROLE#admin"), so one index covers several reads.
Since November 2025 a GSI key can also be built from up to four partition-key and
four sort-key attributes, so status and dueDate could be typed key attributes
instead of a STATUS#open string. Overloading still earns its place when several
entity types share one index.
Two catches. First, STATUS#open is one key value for every tenant, so every
invoice create, status change and dashboard read lands on one GSI partition. Past
a few hundred writes a second, shard it (STATUS#open#0 to #9); see
hot partitions.
Second, the GSI is eventually consistent.
When a read must see a write you just made, read the base table with
ConsistentRead: true (a GetItem on pk/sk, or a Query on the tenant).
Design with the single-table tool
Enter the entities (Tenant, User, Invoice, Event) and their access patterns into the single-table design tool before you commit any keys. It's rule-based, and it shows the overloaded shape for your own patterns.
A "List items under a parent" pattern, such as users per tenant, moves the child
into the parent's partition: pk = TENANT#<tenantId>, sk = USER#… (the tool names
the attributes PK and SK). Each pattern
the base table can't serve becomes a GSI suggestion on generic GSI1PK/GSI1SK
keys, so "open invoices across tenants", entered as "Find by another attribute" on
status, comes back as INVOICE#STATUS#<status>.
Treat the output as a starting point. It gives the tenant's own item
sk = TENANT#<tenantId> where this page uses META, and it doesn't shard a hot
status key; apply the sharding above before launch.
Do it in DynoTable
Raw overloaded keys are hard to read: INVOICE#2026-0015 and
EVENT#2026-06-23T09:12Z blur together in a flat list. DynoTable decodes composite
keys into their segments, and you can right-click a prefix to filter the view to
that entity type.

Pitfalls
- Pick delimiters once.
#is the convention. Mixing#and:across entities breaksbegins_withwith no warning. To migrate, you can'tUpdateItema base-table key: rewrite each item with aTransactWriteItemsthatPuts the new key (withattribute_not_exists(pk)) andDeletes the old one. GSI key attributes such asgsi1pkare ordinary attributes, soUpdateItemcan change them in place. Switch readers to the new prefix once the sweep is done. - Don't overload values that need range math. A sort key of
INVOICE#2026-0015sorts lexically, not numerically; zero-pad ids and use ISO-8601 dates so string order matches the order you mean. - Plan the read before the keys. Overloading serves access patterns you've enumerated. Run them through the design tool above first, and see single-table design if you don't know your reads yet.
- Reserve the prefix namespace. Keep a short registry of prefixes, like the
one below for this example, so a new entity type can't collide with an existing
one under
begins_with.
| Entity | Sort prefix | Example SK | Query slice |
|---|---|---|---|
| Event | EVENT# | EVENT#2026-06-23T09:12Z | time-ordered tail with descending read |
| Invoice | INVOICE# | INVOICE#2026-0015 | begins_with(sk, "INVOICE#") |
| Tenant meta | META | META | Single-item get |
| User | USER# | USER#u_3001 | begins_with(sk, "USER#") |
Size representative items with the item-size calculator, then download DynoTable to browse a whole tenant's collection with its overloaded keys decoded.


