Advanced9 min read

How a DynamoDB GSI Is Stored Internally

A keeps its own copy of the attributes you choose, in partitions of its own, and DynamoDB updates that copy asynchronously after each base-table write.

How is a DynamoDB GSI stored?

AWS says the data in a GSI "is stored separately from the data in its base table", in partitions that "behave in much the same way as table partitions".

Each entry holds the GSI keys, the base table keys and any attributes, and DynamoDB updates the index after the base write.

Coming from SQL, an index is a B-tree on the same table, updated inside the same transaction. A GSI breaks both assumptions:

  • A GSI works like its own table. Its partitions are keyed by the GSI's partition key, not the base table's.
  • Updates are asynchronous. Your write commits to the base table first, then DynamoDB applies it to each GSI.
  • Only projected attributes are stored. The index holds the GSI keys, the base keys, plus whatever attributes you projected.
  • The GSI key need not be unique. Several base items can share one GSI partition/sort key; the base stored with each entry keeps them distinct.

Start with one base item

Take a SaaS audit log. Every privileged action in a workspace becomes an immutable event. The base table, WorkspaceEvents, is keyed so all of a workspace's events live in one , ordered by time:

WorkspaceEvents (base table)
EventPKEventSKactorIdverbtargetRef
WS#orbit-9TS#2026-06-23T14:02:11ZUSR#kpROLE_GRANTEDUSR#mara

EventPK = "WS#orbit-9" partitions by workspace; EventSK is an ISO timestamp so a Query returns one workspace's events in chronological order. That serves "show me this workspace's timeline" perfectly.

It serves nothing else. You can't ask "what did USR#kp do across every workspace?" because actorId isn't a key, so the only way to answer it on the base table is a full Scan. That is the access pattern a GSI exists to add.

Add a GSI and watch a second table appear

Define a GSI, ByActor, that re-partitions the same events by who performed them:

ByActor (GSI)
partition key = actorId   ("USR#kp")
sort key      = EventSK   ("TS#2026-06-23T14:02:11Z")

DynamoDB now maintains a second physical structure. The same logical event is stored twice: once in the base table's WS#orbit-9 partition, and again in the GSI's USR#kp partition:

ByActor (GSI) — its own partition space
actorIdEventSKEventPKverb
USR#kpTS#2026-06-23T14:02:11ZWS#orbit-9ROLE_GRANTED

Note what rode along: the base table's keys (EventPK, EventSK) are stored in every GSI item automatically. That's how a GSI hit can point you back to the full item, and why even a KEYS_ONLY index costs storage.

What lives in the GSI

The index does not copy the whole item. Each GSI entry holds exactly three things, and you control only the third:

Stored in the GSIWhere it comes fromOptional?
GSI partition + sort keyThe attributes you named as GSI keysNo
Base table key(s)Copied from every base itemNo
Projected attributesYour Projection choiceYes

Projection is KEYS_ONLY, INCLUDE (a named list), or ALL. A Query on the GSI can only return attributes that are in the index.

Ask for one that isn't projected and the Query fails with a ValidationException ("Global secondary index ByActor does not project [targetRef]"); Select: ALL_ATTRIBUTES on a non-ALL index fails the same way.

AWS: "Global secondary index queries cannot fetch attributes from the parent table." (Query API reference)

SQL would join back to the heap for the missing column. A GSI Query doesn't, so project what you read, or fetch the full item from the base table by the carried keys.

How a write reaches the index

A base write and its index update are not one atomic operation.

When you PutItem, DynamoDB commits to the base table, acknowledges your write, and then updates each GSI. The acknowledgment does not wait for the index.

Order of events for our audit write, top to bottom:

PutItemWS#orbit-9 eventCommit tobase partition200 OKto callerAsync path:extract GSI keysRoute to ByActorpartition USR#kpWrite projectedattributes

The caller gets its 200 OK at step three, before steps four through six finish, so a Query on ByActor in the gap can miss a brand-new event.

That asynchrony is documented behavior: AWS says GSIs are updated "asynchronously, using an eventually consistent model", usually "within a fraction of a second". The full consequences live in why a GSI is eventually consistent.

The GSI key is not a unique key

In SQL, a non-unique secondary index is the default and a unique one is a constraint you opt into. A GSI has no uniqueness guarantee at all.

Two events by the same actor at the same instant in two workspaces would share the same actorId and EventSK.

DynamoDB stores both, each entry carrying its own base primary key, and AWS says items that share a GSI key come back "in no particular order".

So a GSI Query for one actor at one instant can legitimately return several items. If you assumed one-row-per-key the way a SQL unique index would give you, that's the footgun.

When you need a unique value (an email, a handle), enforce it on the base table: in one TransactWriteItems, put the real item plus a marker item keyed on the value (EMAIL#<value>), each Put guarded by attribute_not_exists.

A duplicate cancels the whole transaction. Uniqueness on multiple attributes has the full pattern.

Capacity lives with the index, not the table

On a provisioned table, the GSI has its own read and write capacity, throttled separately from the base table. A read off ByActor consumes the GSI's read units, never the table's.

Writes couple the two. Every base-table write that touches the index also writes it, and if the GSI can't absorb that, base-table writes are throttled. That mechanism gets its own guide: when a GSI throttles base-table writes.

This is also why a GSI's partition key matters as much as the base table's. A low-cardinality GSI key clumps writes onto one index partition even when base writes are spread, a hot partition you created by re-keying.

The way out is a composite GSI key with a high-cardinality part (ACTIVE#customer123 rather than ACTIVE), or write-sharding the attribute the GSI keys on and querying each shard. Hot partitions covers the sharding.

GSI write amplification

Every base-table write that changes a GSI costs base write units + index write units, in either capacity mode (write capacity units on provisioned, write request units on on-demand).

A 1 KB item in a table with one GSI, whose index entry also fits in 1 KB, costs 2 write units: one for the table, one for the index entry.

  • An update that changes the GSI key costs two index writes: a delete of the old entry and a put of the new one.
  • An update that touches only attributes the index neither keys on nor projects costs no index write at all.
  • Projection changes the cost only past 1 KB. An index entry up to 1 KB costs one write unit whatever the projection; KEYS_ONLY saves write units on larger items, and storage on every item. ALL can double your storage.

Model item size and projection in the pricing calculator.

Pitfalls and next steps

  • Don't request un-projected attributes. A GSI Query that names one fails. If you need the full item, project it or fetch it from the base table by the carried-along keys.
  • Don't treat a GSI key as unique. Plan for a Query to return more than one item per key; the base primary key is the only real identity.
  • Don't read a GSI right after the write that fed it. The async path means the index may not show your write yet. Read the base table with ConsistentRead: true (GetItem or Query on the base key) when you need read-your-own-writes.
  • Give the GSI enough write capacity. On provisioned tables, AWS says the GSI's write capacity "should be equal or greater than the write capacity of the base table". On on-demand, the GSI inherits the table's mode, and the per-partition limits still apply.

The whole game is choosing key shapes that serve your patterns: single-table design overloads one GSI across many of them; GSI vs LSI covers when a local index fits instead.

Build and preview your GSI KeyConditionExpression in the DynamoDB Expression Builder, which escapes names and values for you. For example, matching one actor since a cutoff:

KeyConditionExpression: "#a = :actor AND #ts > :since"
ExpressionAttributeNames:  { "#a": "actorId", "#ts": "EventSK" }
ExpressionAttributeValues: {
  ":actor": { "S": "USR#kp" },
  ":since": { "S": "TS#2026-06-01T00:00:00Z" }
}

Then try DynoTable: the Table indexes section of a table's Settings shows each index's keys and projection, and you can query the GSI next to the base table.

By Dmitriy · Updated