Skip to content

Synchronous secondary indexes

DynamoDB updates global secondary indexes asynchronously. fdyno writes active GSI and LSI entries in the same FoundationDB transaction as the base item.

Write transaction

A normal item write includes all active index changes:

putItem(tr, baseKey, item)             // base item
putIndexEntries(tr, dir, tbl, item)    // GSI and LSI entries
// stream record and idempotency token when required
// one FoundationDB commit

The transaction removes old index entries and writes new projected entries before one commit. Readers see either the old committed state or the new committed state.

After a successful write:

  • an active index does not lag behind the base item;
  • another fdyno process sees the same committed index state; and
  • a process restart cannot lose queued index work because no queue is used.

This differs from DynamoDB GSI propagation. fdyno still rejects ConsistentRead=true on a GSI because that request is invalid in the DynamoDB API.

New index backfill

Adding a GSI to a table with existing data requires multiple transactions. fdyno first registers the index as CREATING. Live writes maintain the registered index, while bounded backfill transactions copy older rows. The index becomes ACTIVE only after backfill completes.

A CREATING index can be incomplete. Applications must wait for ACTIVE before using it.

Write cost and limits

Synchronous index maintenance adds work to each item write:

  • An item in N indexes writes the base item plus N index entries.
  • Index keys and projected values count toward the FoundationDB transaction limit.
  • Index writes add conflict ranges and can increase retries on hot keys.
  • The caller waits for all index writes to commit.
  • An index cannot be provisioned or throttled separately from the base table.

Project only the attributes that an access pattern needs. Test writes with realistic item sizes, index counts, and stream images. A valid DynamoDB item can still exceed the physical FoundationDB transaction limit after index and stream data are added.

See Data model, Guarantees, and Limits for the exact behavior.