Global Secondary Index

AWS Developer: Global Secondary Indexes (GSIs)

AWS Developer

How Does a Global Secondary Index Work?

A Global Secondary Index operates much like a standard DynamoDB table. Think of it as a secondary table rather than the primary one. It maintains its own partition key and sort key, allowing you to query data from a different angle without affecting the original table’s structure.

1. A Global Secondary Index partition key requires uniform data distribution. This is critical when operating at high loads or with significant read and write capacities, as an uneven distribution can create hot partitions and degrade performance.
2. RCU/WCU capacity is defined separately on the index. Indexes have their own settings that can be tuned based on your specific use case, giving you granular control over performance and cost.
3. Throttling. This is more likely to occur on the Global Secondary Index than on the main table, since the Global Secondary Index has its own separate capacity settings and must handle its own read and write traffic independently.

Cost Associated with Global Secondary Indexes

1. Writes to the main table results in a write to the Global Secondary Index, effectively doubling the costs of writing.
2. Writes to the main table are eventually replicated to the Global Secondary Index, typically within milliseconds. However, there is no guaranteed SLA for this replication delay. It is strictly best-effort.
3. Race conditions can occur due to eventual consistency. A Global Secondary Index can potentially return stale data if a query is made before replication from the main table completes.

Reading from the Global Secondary Index and then attempting to update the main table using that record as the source is a significant risk. Because the GSI can return stale data, you may inadvertently write outdated information back into your primary table creating a dangerous feedback loop that corrupts your source of truth.

Keep your Write Capacity Units (WCU) on your Global Secondary Index greater than or equal to the WCU on your main table.

A write to your primary table results in a write to every Global Secondary Index attached to it. If your GSIs lack sufficient Write Capacity Units, this will eventually lead to throttled requests.

I recommend enabling Auto-Scaling on your Global Secondary Index and checking the box that says “Use the same settings as my primary table.” Apply this specifically to Write Capacity.

Monitor your Global Secondary Index with separate metrics, track them independently from your main table to catch throttling, latency, and capacity issues before they impact your application.

DynamoDB: Scan vs Query — GSI

Compare a Scan with a Query using a Global Secondary Index (GSI).

Scan the Users table

A Scan examines every item in the table.

Filter by Email No filter — return everything alice@example.com bob@example.com john@example.com

DynamoDB scans:

Users → Every item → Filter → Results

DynamoDB Scan

Returned data

Query the GSI

A Query uses the GSI partition key to locate matching items without scanning the entire base table.

Query this:

Partition Key

UserId

AND

Sort Key

CreatedAt

1

Find the partition

UserId =

2

Use the sort key

CreatedAt =

✓

Return the matching item

DynamoDB returns the matching item.

DynamoDB Query

Returned data

Users Table

Base DynamoDB table

Base Table

UserId Partition Key	CreatedAt Sort Key	Email	Name
user-123	2026-09-01	alice@example.com	Alice
user-456	2026-09-05	bob@example.com	Bob
user-789	2026-09-10	john@example.com	John

EmailIndex

GSI with Email as the partition key

Global Secondary Index

Email GSI Partition Key	CreatedAt GSI Sort Key	UserId	Name
alice@example.com	2026-09-01	user-123	Alice
bob@example.com	2026-09-05	user-456	Bob
john@example.com	2026-09-10	user-789	John

---