Intermediate8 min read

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 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 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 GetItem and 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:

Members (base table)
PKSKemaildisplayName
ACC#a1f9cPROFILEada@northwind.testAda L.
EmailIndex (GSI)
GSI1PKGSI1SK
ada@northwind.testACC#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.

EmailIndexBase tableAppEmailIndexBase tableAppasync propagationPutItem (new member)200 OKQuery by email0 items (stale)replicate changeQuery by email1 item (caught up)

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

The GSI propagation race

Write v2 commits to the base table at 0 ms; the index only shows it after propagation. Drop your Query anywhere on the timeline and see what comes back.

0 ms — Write v21,000 ms
Write v2 (0 ms)GSI caught up (120 ms)your read (100 ms)
100 ms

Strongly consistent is disabled for a reason: a GSI rejects ConsistentRead. No flag closes the window — wait it out, or read the base table.

Your read at 100 ms returns v1 — the old value. It landed on the GSI, which only catches up at 120 ms. Cost: 1× RCU.

Read atRead typeReturnsServed byRCU cost
50 msEventually consistentv1 (stale)the GSI1×
50 msStrongly consistentRejected — ValidationException——
200 msEventually consistentv2 (fresh)the GSI1×
200 msStrongly consistentRejected — ValidationException——
600 msEventually consistentv2 (fresh)the GSI1×
600 msStrongly consistentRejected — ValidationException——

A teaching model: the lag is drawn long enough to see. Real GSI propagation is usually a fraction of a second, but it is not guaranteed and not bounded under load — and no ConsistentRead flag exists to close the window. For read-after-write, query the base table.

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:

  1. 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 consistent GetItem on 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.

  2. 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 a TransactWriteItems, with a ConditionExpression of attribute_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 is rejected. The condition is checked against the base table, so only one sign-up can win.

    Store the accountId on the guard item and it doubles as a strongly consistent email lookup: GetItem it with ConsistentRead: 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_exists condition with the DynamoDB Expression Builder before you wire it into code.

  3. Tolerate the lag in the UX. Where a GSI read is still the cheaper path (one Query returns the projected profile, while the guard item needs a second GetItem by accountId), 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.

  4. 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 GetItem on 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.

By Dmitriy · Updated