Why secondary indexes
The base table can only be queried efficiently by its primary key. Secondary indexes give you additional access patterns by indexing other attributes.
Local secondary index
A Local Secondary Index (LSI) shares the same partition key as the base table but uses a different sort key.
- Must be created at table creation time and cannot be added later.
- Reads can be strongly consistent because the index lives in the same partition.
- Counts against the partition size limit, since item collections share a partition.
Global secondary index
A Global Secondary Index (GSI) can use a completely different partition key and sort key.
- Can be added or removed at any time.
- Always eventually consistent and maintained asynchronously.
- Has its own provisioned or on demand capacity, separate from the base table.
Projections
Both index types let you choose which attributes are projected into the index: keys only, a chosen subset, or all attributes. Projecting more avoids extra fetches but costs storage.
Diagram
Key idea
Use an LSI for alternate sort orders within the same partition, and a GSI for entirely new query patterns with its own keys and capacity.