DynamoDB Global Secondary Index (GSI) - The Ultimate Guide
Written by Chameera Dulanga
Published on September 25th, 2022
Time to 10x your DynamoDB productivity with Dynobase [learn more]
There are two types of secondary indexes in DynamoDB: Global Secondary Index (GSI) and Local Secondary Index (LSI). This article will provide an in-depth view of DynamoDB GSI with examples, a comparison with LSI, and answers to some of the most asked questions related to GSI.
What is Global Secondary Index (GSI) in DynamoDB?
DynamoDB global secondary index is a type of index containing a partition key and a sort key different from the base table's primary key. It is known as the "global" secondary index since the queries on the index can access data from multiple partitions of the base table.
A single DynamoDB table can have multiple GSIs. Applications can largely benefit from this since having multiple secondary keys improve access to data with attributes other than the primary key. In addition, GSIs support non-unique attributes, increasing query flexibility by allowing queries against non-key attributes.
The throughput of DynamoDB GSIs is independent of the base table. You need to define the provisioned throughput for the table and each associated GSI when you create them. However, throttling on a GSI can affect the base table when the GSI has an insufficient write capacity. It's important to monitor and adjust the provisioned throughput settings to ensure optimal performance.
How to Create a DynamoDB GSI?
Creating a global secondary index is straightforward. You can either define it at the table creation or add it to an existing table.
Defining a GSI for a New Table
When you use the AWS management console to create a new DynamoDB table, you will see an option to customize the table settings.
When you change the option to Customize settings, a new section will appear at the bottom to create secondary indexes.
There, click the Create global index button. It will open a new modal, and you can define a new global secondary index by entering the partition key, sort key, index name, and attribute projections.
Defining a GSI for an Existing Table
You can update the GSI of an existing DynamoDB table using the AWS management console or AWS CLI.
If you are using the AWS management console, select the DynamoDB table from the tables list and navigate to the Indexes tab.
Click the Create Index button, which will navigate you to the GSI creation wizard.
There, you can fill in the required details and create the GSI.
If you are using the AWS CLI, you can run the below command to update the GSI. The below command will create a global secondary index named name-index in the Articles table.
DynamoDB GSI Query Examples
You can run GSI queries using the AWS management console or AWS CLI.
GSI Queries Using AWS Management Console
Select your DynamoDB table from the table list and click on Explore table items button.
There, choose the Query option and select the GSI from the dropdown.
Finally, enter the value you need to query and click the Run button.
GSI Queries Using AWS CLI
You can use the below AWS CLI command, which shows an example of querying the global secondary index through the DynamoDB API. It queries the Articles table using the GSI named name-index to get articles with the name "DynamoDB".
Updating DynamoDB GSI
DynamoDB does not allow updating the key schema of existing GSIs since it can cause some critical issues in your applications. However, you can update the provisioned throughput and projection settings. If you need to change the key schema, the only solution is to create a new GSI with the latest requirements and delete the old one.
DynamoDB GSI vs LSI
As mentioned, two types of secondary indexes are available in DynamoDB: GSI and LSI. As a developer, it is essential to understand the differences between these two to maximize the performance of your DynamoDB tables. The below table will give an overview of some of the vital features of GSI and LSI.
Best Practices for Using DynamoDB GSI
When using GSIs, it's crucial to follow best practices to ensure optimal performance and cost-efficiency. Here are some tips:
- Monitor and Adjust Throughput: Regularly monitor the read and write capacity units of your GSIs and adjust them based on the workload to avoid throttling.
- Use Projections Wisely: Only project the attributes you need to minimize storage costs and improve query performance.
- Design for Query Patterns: Design your GSIs based on the most common query patterns to ensure efficient data retrieval.
- Avoid Hot Partitions: Distribute your data evenly across partitions to avoid hot partitions, which can lead to throttling and degraded performance.
- Regularly Review and Optimize: Periodically review your GSIs and optimize them based on changing access patterns and application requirements.
Frequently Asked Questions
How many GSIs can be created in DynamoDB?
A single DynamoDB table supports a maximum of 20 global secondary indexes.
Can a DynamoDB range key be a GSI key?
Yes. You can use a range key as a GSI.
Why is the DynamoDB GSI not showing the item count?
Usually, DynamoDB takes around 6 hours to update the item count of a GSI. So, you will not see the item count get updated immediately.
Does DynamoDB GSI have to be unique?
No. DynamoDB global secondary indexes do not need to be unique.
Can you add a GSI to an existing DynamoDB table?
Yes. Unlike LSI, you can add a GSI to an existing DynamoDB table.
How many DynamoDB GSIs are allowed per table?
You can have up to 20 global secondary indexes per a DynamoDB table.
How long does it take to create a DynamoDB GSI?
Creating a GSI in DynamoDB only takes a few minutes. Usually, a new GSI should be created within 5 minutes. But the time duration can increase when adding a GSI to an existing table since DynamoDB needs to backfill all the existing database records.