Design the GSI key schema before issuing CreateTable or UpdateTable — once created, a GSI's key attributes cannot be changed; new GSIs can be added but cannot be removed and re-added atomically
To add a GSI to an existing table: aws dynamodb update-table --table-name Orders --attribute-definitions ... --global-secondary-index-updates '[{"Create":{...}}]'; DynamoDB begins an asynchronous backfill
Monitor GSI backfill progress via describe-table: check GlobalSecondaryIndexes[].IndexStatus (CREATING → BACKFILLING → ACTIVE) and ProvisionedThroughput.NumberOfDecreasesToday
For provisioned-capacity tables, temporarily increase both the table's write capacity and the GSI's write capacity before initiating the backfill to avoid throttling; set auto scaling policies to adjust capacity as the backfill drives write traffic to the GSI
For on-demand tables, DynamoDB also creates the GSI in on-demand mode and scales automatically — no manual capacity adjustment is needed but the table is subject to per-account and per-table throughput limits
After the GSI reaches ACTIVE status, update queries and scans to use the new index; validate results against the base table for consistency
Known gotchas
GSI throttling on writes causes back-pressure to the table's writes — if the GSI cannot keep up, item puts to the base table are throttled even if the table has sufficient capacity; monitor GSI ConsumedWriteCapacityUnits separately
Items that do not include the GSI key attributes are not projected into the GSI; verify that existing items contain the new GSI partition key attribute before relying on GSI query completeness
DynamoDB does not guarantee that a newly active GSI contains all items written during the backfill window; use a read-after-write validation pass or a conditional query after backfill completes before deprecating the old access pattern
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp