Why a DynamoDB GSI Is Eventually Consistent
You write an item, immediately query a Global Secondary Index for it, and get
nothing back, even though the write succeeded and a base-table GetItem
returns the item fine.
Nothing is broken. You've hit the GSI consistency rule: every read of a GSI is eventually consistent, and for a short window after a write the index hasn't caught up yet.
Are DynamoDB GSIs eventually consistent?
Yes. Every read of a Global Secondary Index is eventually consistent, with no
way to opt out. Your write commits to the base table first, then propagates
asynchronously to the index, so a query issued right after a write can
return stale or missing rows. DynamoDB rejects ConsistentRead: true on a GSI.
- Read your own writes from the base table. You already hold the primary key right after a write, and the base table supports strongly consistent reads.
- Enforce uniqueness with a conditional write. A GSI "is this taken?" check races; a condition on a guard item doesn't.
- Re-read before you write back. A value you got from a GSI can be stale, so
confirm it with a consistent
GetItemand make the write conditional on it.
The symptom: a sign-up that "can't find itself"
Take a Members table for a user-accounts service. The base table is keyed by an
internal id, but users log in by email, so there's an email-lookup GSI:
| PK | SK | displayName | |
|---|---|---|---|
| ACC#a1f9c | PROFILE | ada@northwind.test | Ada L. |
| GSI1PK | GSI1SK |
|---|---|
| ada@northwind.test | ACC#a1f9c |
The sign-up flow does two things back to back: PutItem the new member, then
Query EmailIndex WHERE GSI1PK = "ada@northwind.test" to check no one else
claimed that address and to load the profile.
Run those two calls a few milliseconds apart and the Query can return zero
items. Do it again a second later and the row is there. The write didn't fail;
the index just hadn't been updated yet.
Why this happens: GSIs are replicated asynchronously
A GSI is a separate, internally managed table with its own partitions and its own key schema. DynamoDB doesn't update it inside the same operation as your base-table write.
When you PutItem, DynamoDB commits to the base table, acknowledges your write,
and then propagates the change to each GSI asynchronously. The AWS
GSI documentation
says changes arrive "within a fraction of a second, under normal conditions".
The same page warns that "in some unlikely failure scenarios, longer propagation delays might occur." So don't design as if the delay were bounded.
Asynchronous doesn't mean independent. If a GSI can't absorb its share of the writes, DynamoDB throttles the base-table write; see why a GSI throttles base-table writes.
The gap between the 200 OK and "replicate change" is the window where your index
read is stale. On the base table you close it by passing ConsistentRead: true to a
strongly consistent GetItem or Query.
On a GSI the same flag fails with ValidationException: Consistent reads are not supported on global secondary indexes. An LSI can be read strongly because it
shares the base table's partitions; see GSI vs LSI.
Read cost on a GSI
A GSI query bills like any eventually consistent read: 0.5 read units per 4 KB, summed over the returned index entries and rounded up once per request. That is read capacity units on a provisioned table, read request units on on-demand.
There is no strongly consistent rate to pay, because the option doesn't exist on a GSI. Price eventually consistent reads for your item size in the pricing calculator.
A subtler trap: stale old values, not just missing new ones
The missing-row case is the obvious one. The quieter bug is reading a stale previous value.
Say Ada changes her email from ada@northwind.test to ada.l@northwind.test. The
base table updates atomically, but for a moment the GSI can still return the
old index entry. A lookup against the new value misses, while the abandoned
value still resolves.
If you query the GSI and write back based on what you read, you can act on a value
that no longer exists. Every GSI entry carries the base table's primary key, so
take PK and SK from the result and re-read the item with GetItem and
ConsistentRead: true.
Then make the write conditional on what you just read, for example
ConditionExpression: "email = :seen" or a version attribute you increment. If
the item changed in between, the write fails with
ConditionalCheckFailedException instead of overwriting it.
Design around the lag
Four patterns, roughly in order of preference:
Read your own writes from the base table. Right after a write you already hold the primary key (
PK = ACC#a1f9c,SK = PROFILE), so do a strongly consistentGetItemon the base table instead of querying the GSI.The GSI is for the other access pattern ("I have an email, find the account"), not for confirming the write you just made.
Enforce uniqueness with a guard item, not the GSI. A GSI query can't prove an email is unclaimed: two simultaneous sign-ups can both see an empty index and both succeed.
Instead, write a dedicated uniqueness item keyed on the email itself (
PK = "EMAIL#ada@northwind.test",SK = "EMAIL") inside aTransactWriteItems, with aConditionExpressionofattribute_not_exists(PK).TransactWriteItems: - Put member item (PK = ACC#a1f9c, SK = PROFILE) - Put uniqueness item (PK = EMAIL#ada@northwind.test, SK = EMAIL, accountId = ACC#a1f9c) ConditionExpression: attribute_not_exists(PK)If a second sign-up races for the same address, its condition fails and the whole transaction is rejected. The condition is checked against the base table, so only one sign-up can win.
Store the
accountIdon the guard item and it doubles as a strongly consistent email lookup:GetItemit withConsistentRead: true. When Ada changes her email, delete the old guard and put the new one in the same transaction.Build and preview that
attribute_not_existscondition with the DynamoDB Expression Builder before you wire it into code.Tolerate the lag in the UX. Where a GSI read is still the cheaper path (one
Queryreturns the projected profile, while the guard item needs a secondGetItembyaccountId), the lag only matters in the moments after a write, and most accounts propagated long ago.Reserve the strongly consistent base-table path for the read-after-write moment only.
Re-query with a budget. If a workflow must observe a brand-new item through the GSI, treat an empty result as "not yet visible", not "does not exist".
Retry a few times with exponential backoff (100 ms, 200 ms, 400 ms) and stop after about a second. Then fall back to a strongly consistent
GetItemon the key you wrote, which tells you whether the item exists.
Check propagation in DynoTable
In DynoTable the filter builder's index picker runs the same filter against the base table or a GSI. Results update when you run the query, not live, so you won't usually catch a sub-second lag by hand.
What you can check is the outcome: after a write, query the GSI and confirm the item arrived with the projected attributes you expect. An empty result right after a write is the lag, not a failed write.
Pitfalls and next steps
- Don't gate logic on a GSI read-after-write. Uniqueness checks, "did my write land" confirmations, and read-modify-write loops belong on the strongly consistent base table.
- Don't model an access pattern as a GSI when the base key already answers it. Serve a read from the primary key and you skip the propagation window entirely.
Key shape decides most of this; see
single-table design. Knowing when a Query
beats a Scan keeps you off the index in the first place
(Query vs Scan).
Build and test your uniqueness ConditionExpression in the
DynamoDB Expression Builder. Then
try DynoTable to query your base table and its GSIs from the same
filter builder, and design your keys so the eventual-consistency window never
bites you.