What are Secondary Indexes?
A secondary index in DynamoDB allows you to query data using an alternate key, in addition to the table's primary key. They are essential for supporting multiple different query patterns against your data without having to perform inefficient, full-table Scan operations.
Local Secondary Index (LSI)
An LSI provides a different sort order for your data, but only for items that have the same partition key. It is "local" because every partition in an LSI is scoped to a base table partition with the same partition key value.
Key Characteristics of an LSI:
- Key Structure: Must have the same partition key as the base table, but a different sort key.
- Creation Time: Can only be created when the table is created. You cannot add or remove an LSI from an existing table.
- Throughput: Shares throughput with the base table. When you read or write items, any updates to an LSI consume Read Capacity Units (RCUs) and Write Capacity Units (WCUs) from the base table.
- Read Consistency: Supports both eventually consistent and strongly consistent reads.
- Item Collection Size Limit: There is a strict 10 GB limit on the total size of all items (base table + LSI data) that share the same partition key.
Global Secondary Index (GSI)
A GSI acts like a separate table that contains a copy of some or all of your data, but organized by a different primary key. It is "global" because it spans the entire base table, across all partitions.
Key Characteristics of a GSI:
- Key Structure: Can have a partition key and sort key that are completely different from the base table's keys. This is its primary advantage.
- Creation Time: Can be created at any time, even on a pre-existing table. You can also delete a GSI whenever you want.
- Throughput: Has its own separate provisioned throughput settings for reads and writes. You provision and pay for a GSI's RCUs and WCUs independently of the base table.
- Read Consistency: Only supports eventually consistent reads. There can be a small replication lag between the base table and the GSI.
- Item Collection Size Limit: There is no item collection size limit.
Detailed Comparison Table
| Feature | Local Secondary Index (LSI) | Global Secondary Index (GSI) |
|---|---|---|
| Partition Key | Must be the same as the base table. | Can be different from the base table. |
| Sort Key | Must be different from the base table. | Can be any attribute (scalar type). |
| Primary Use Case | Provide a different sort order for items with the same partition key. | Query the entire table on attributes other than the primary key. |
| Creation | Only at table creation. Cannot be added or removed later. | Flexible. Can be created on an existing table and deleted anytime. |
| Provisioned Throughput | Shares RCUs/WCUs with the base table. | Has its own, separate RCUs/WCUs. |
| Read Consistency | Supports Strongly Consistent & Eventually Consistent reads. | Supports Only Eventually Consistent reads. |
| Size Limit | 10 GB limit per item collection (all items with the same partition key). | No limit. |
| Flexibility | Low | High |
Key Takeaway: When to Choose Which
-
Choose a Local Secondary Index (LSI) when:
- You need to query items with the same partition key but sort them in a different order.
- You absolutely require the ability to perform strongly consistent reads on the index.
-
Choose a Global Secondary Index (GSI) for:
- Almost all other scenarios. GSIs are far more flexible and are the standard solution for enabling secondary query patterns.
- When you need to query your data using a completely different partition key.
- When you need to add a new query pattern to an existing table.
Sources