Advanced8 min read

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 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/sk and put the entity type in the value, e.g. pk = "TENANT#acme", sk = "USER#u_3001".
  • begins_with is the payoff: a type prefix on the sort key lets one Query pull a whole entity, or one slice of it, with no Scan and no filter.
  • Readability is the cost: a raw pk/sk dump is hard to read. Write an explicit entityType attribute 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:

pkskattributes
TENANT#acmeEVENT#2026-06-23T09:12Zactor="u_3001", action="invite"
TENANT#acmeINVOICE#2026-0014amount_cents, status="paid"
TENANT#acmeINVOICE#2026-0015amount_cents, status="open"
TENANT#acmeMETAname="Acme Inc", plan="team"
TENANT#acmeUSER#u_3001email, role="admin"
TENANT#acmeUSER#u_3002email, role="member"

Every row shares pk = "TENANT#acme", so they form one : 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.

Partition: TENANT#acmesk: EVENT#2026-06-23T09:12Zsk: INVOICE#2026-0015sk: METAsk: USER#u_3001One key condition

The sort-key prefix groups entities and orders them.

Run the access patterns
Query pk = "TENANT#acme"

6 of 7 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
#pkskgsi1pkgsi1skAttributes
1TENANT#acmeEVENT#2026-06-23T09:12Zactor="u_3001", action="invite"
2TENANT#acmeINVOICE#2026-0014STATUS#paid2026-06-12amount_cents, status="paid"
3TENANT#acmeINVOICE#2026-0015STATUS#open2026-06-30amount_cents, status="open"
4TENANT#acmeMETAname="Acme Inc", plan="team"
5TENANT#acmeUSER#u_3001email, role="admin"
6TENANT#acmeUSER#u_3002email, role="member"
TENANT#betaINVOICE#2026-0099STATUS#open2026-06-25amount_cents, status="open"

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.

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

pkskgsi1pkgsi1sk
TENANT#acmeINVOICE#2026-0015STATUS#open2026-06-30
TENANT#acmeINVOICE#2026-0014STATUS#paid2026-06-12
TENANT#betaINVOICE#2026-0099STATUS#open2026-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.

DynoTable showing one tenant's item collection, with the overloaded sort keys decoded into their EVENT, INVOICE, META and USER segments.
DynoTable showing one tenant's item collection, with the overloaded sort keys decoded into their EVENT, INVOICE, META and USER segments.

Pitfalls

  • Pick delimiters once. # is the convention. Mixing # and : across entities breaks begins_with with no warning. To migrate, you can't UpdateItem a base-table key: rewrite each item with a TransactWriteItems that Puts the new key (with attribute_not_exists(pk)) and Deletes the old one. GSI key attributes such as gsi1pk are ordinary attributes, so UpdateItem can 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-0015 sorts lexically, not numerically; 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.
EntitySort prefixExample SKQuery slice
EventEVENT#EVENT#2026-06-23T09:12Ztime-ordered tail with descending read
InvoiceINVOICE#INVOICE#2026-0015begins_with(sk, "INVOICE#")
Tenant metaMETAMETASingle-item get
UserUSER#USER#u_3001begins_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.

By Dmitriy · Updated