Intermediate8 min read

The Type Attribute in DynamoDB

In SQL, a row's table is its type: a row in documents is a document. A DynamoDB single table mixes every entity under one schema, so an item carries no built-in answer to "what is this?". The Type attribute puts that answer back.

What is the Type attribute in DynamoDB?

The Type attribute is a plain string you stamp on every item, like EntityType: "Document", naming the entity that item represents. A single table mixes many entities under one schema, so items carry no built-in type until you add one.

  • Stamp a Type on every write. One attribute, EntityType: "Document", on every item, no exceptions. It costs a few bytes.
  • It identifies entities in a mixed partition. A Query returns workspaces, documents, and comments together; the Type tells your code which is which without parsing key prefixes.
  • It decides who joins a . Your writer uses the Type to pick which items get a sparse index's key, or you filter an overloaded index on it.
  • It's the column you split on when you re-model. Export the table and the Type tells you which rows go where.

Why a mixed table loses the type

Single-table design stores every entity in one table behind generic keys like PK and SK, so one Query returns a parent and its children together. That means a partition is heterogeneous.

Take a SaaS doc-collaboration app. One workspace partition holds the workspace record, its documents, and the comments on those documents:

PKSKattributes
WS#acmeMETAname, plan, seats
WS#acmeDOC#a1#METAtitle, owner, wordCount, updatedAt
WS#acmeDOC#a1#CMT#0007author, body, updatedAt
WS#acmeDOC#a1#CMT#0008author, body, updatedAt

Query PK = "WS#acme" hands back all four items in one billed read. Now your code has a list of raw items and no reliable way to say which is a document and which is a comment, short of string-matching the SK, which breaks the moment your key format changes.

Stamp the Type on every item

The fix is one attribute on every write, naming the entity:

PKSKEntityTypetitle
WS#acmeMETAWorkspace—
WS#acmeDOC#a1#METADocumentQ3 Roadmap
WS#acmeDOC#a1#CMT#0007Comment—

Branching on item.EntityType === "Document" is a stable equality check. Parsing SK.startsWith("DOC#") && SK.includes("#CMT#") is a guess that breaks when you rev the key. The Type decouples your read logic from your key encoding.

Query PK = 'WS#acme'Mixed partitionEntityType: 'Workspace'EntityType: 'Document'EntityType: 'Comment'Route by Type

One read returns three entity types; the Type attribute routes each item to the right handler without touching the keys.

Filter a GSI down to one entity

The Type matters most on indexes. Say you add a GSI keyed on GSI1PK = WS#acme, GSI1SK = updatedAt to list "everything recently changed in this workspace, newest first". An overloaded index sweeps in documents and comments, and a feed UI may want documents only.

Two ways to narrow it, and the difference is money:

ApproachWhat it costsWhen to use
FilterExpression on TypeReads all matching items, bills for all of them, drops non-matches after readMixed entities are rare in the result; quick to ship
Sparse index (GSI1PK written only on the target entity)Only the entity you want ever lands in the indexOne entity dominates; you want zero waste

A GSI Query returning 100 mixed items at 2 KB each reads 200 KB. DynamoDB sums the sizes and rounds once to 4 KB blocks: 50 blocks × 0.5 = 25 read units, eventually consistent (GSI reads always are).

A FilterExpression on EntityType still bills all 25 before it drops the comments. A that never indexes comments bills only the document rows.

A FilterExpression runs after items are read and after capacity is consumed; AWS is explicit that filtering doesn't reduce read cost (DynamoDB Developer Guide: FilterExpression). A filter on the Type still bills for every comment it discards.

To narrow the feed to documents, the query carries a condition on the Type attribute. Assemble the FilterExpression, names, and values with the DynamoDB expression builder; it emits numbered placeholders (#filter0 = :filterValue0) so you don't trip over a reserved word.

KeyConditionExpression     GSI1PK = :ws
FilterExpression           #t = :doc
ExpressionAttributeNames   { "#t": "EntityType" }
ExpressionAttributeValues  { ":ws": "WS#acme", ":doc": "Document" }

Want the index to carry only documents and skip the filter entirely? Write GSI1PK only on document items, a sparse index.

Items without the GSI key never replicate into the index, so the read touches documents alone, and the Type attribute tells your writer which items qualify.

The trade: that index no longer serves the mixed "everything changed" feed. If you need both, keep GSI1 for the feed and add a second, sparse GSI for documents, at one more write per document.

Keep the value stable and singular

Pick the value once and treat it as an enum. Document, never sometimes Doc and sometimes document. A drifting value is worse than no value, because your equality checks pass on one casing and silently miss the other.

One Type per item. If an item feels like two entities, that's usually a modeling smell: it should be two items, each in its own collection or sort-key range.

The migration payoff

The reason to stamp the Type before you need it: re-modeling. One re-model path is export, transform, import. Export to S3 needs point-in-time recovery turned on and consumes no read capacity (Exporting DynamoDB to S3).

Import from S3 always creates a new table (Importing from S3), and the old table keeps taking writes while it loads. Import can't read the catch-up data: an incremental export records each change as Keys plus a NewImage (no NewImage for a delete), not as importable Item rows (export output format).

So replay it with your own writer, transformed the same way: PutItem each new image, DeleteItem each key that has none. Repeat until the gap is small, then pause writes (or dual-write to both tables) for the last pass and switch reads. DynamoDB migrations covers dual-writing.

When that day comes, the Type is the column you GROUP BY. Want to lift comments into their own table, or split the export into per-entity files for an analytics warehouse? You split the dump on EntityType. Without it, you're back to reverse-engineering keys across millions of rows.

Next steps

Stamp the Type on every write from day one. If your table is already live without one, backfill it: deploy the code that stamps new writes first, then run a parallel Scan that derives each item's type from its SK prefix once.

Write it with UpdateItem SET EntityType = :t and ConditionExpression attribute_exists(PK) AND attribute_not_exists(EntityType). A rerun is then safe, never overwrites a newer write, and never recreates an item deleted after the Scan read it (UpdateItem upserts a missing key). Throttle it with Limit; DynamoDB migrations covers the sweep.

Related reading: single-table design for the mixed-partition pattern this serves, GSI vs LSI for choosing the index shape behind a sparse index, and Query vs Scan for why a FilterExpression never saves you read cost.

Build the filter on the Type with the DynamoDB expression builder, and try DynoTable to browse a real mixed-entity table and see the Type column line up across every item.

By Dmitriy · Updated