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, GISs support non-unique attributes, increasing query flexibility by allowing to run 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.

How to Create a DynamoDB GSI?

Creating a global secondary index is pretty 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 GSIs since it can cause some critical issues in your applications. So the only solution is to create a new GSI using the latest requirements.

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.

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.