DynamoDB Global Secondary Index (GSI) - The Ultimate Guide

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.

aws dynamodb update-table \
    --table-name Articles\
    --attribute-definitions AttributeName=name,AttributeType=S \
    --global-secondary-index-updates \
        "[{\"Create\":{\"IndexName\": \"name-index\",\"KeySchema\":[{\"AttributeName\":\"name\",\"KeyType\":\"HASH\"}], \
        \"ProvisionedThroughput\": {\"ReadCapacityUnits\": 10, \"WriteCapacityUnits\": 5},\"Projection\":{\"ProjectionType\":\"ALL\"}}}]"
aws dynamodb update-table \
    --table-name Articles\
    --attribute-definitions AttributeName=name,AttributeType=S \
    --global-secondary-index-updates \
        "[{\"Create\":{\"IndexName\": \"name-index\",\"KeySchema\":[{\"AttributeName\":\"name\",\"KeyType\":\"HASH\"}], \
        \"ProvisionedThroughput\": {\"ReadCapacityUnits\": 10, \"WriteCapacityUnits\": 5},\"Projection\":{\"ProjectionType\":\"ALL\"}}}]"

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".

aws dynamodb query \
    --table-name Articles \
    --index-name name-index \
    --key-condition-expression "name = :name" \
    --expression-attribute-values  '{":name":{"S":"DynamoDB"}}'
aws dynamodb query \
    --table-name Articles \
    --index-name name-index \
    --key-condition-expression "name = :name" \
    --expression-attribute-values  '{":name":{"S":"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:

1. 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.
2. Use Projections Wisely: Only project the attributes you need to minimize storage costs and improve query performance.
3. Design for Query Patterns: Design your GSIs based on the most common query patterns to ensure efficient data retrieval.
4. Avoid Hot Partitions: Distribute your data evenly across partitions to avoid hot partitions, which can lead to throttling and degraded performance.
5. Regularly Review and Optimize: Periodically review your GSIs and optimize them based on changing access patterns and application requirements.