Global Secondary Index in DynamoDB: What It Is and How It Works

A Global Secondary Index (GSI) in DynamoDB is an index with a partition key and optional sort key that can be different from the table's primary key. It allows you to query data efficiently using alternate keys without affecting the main table's performance.

How It Works

Think of a DynamoDB table as a big filing cabinet organized by a main key, like a person's ID. Sometimes, you want to find files by a different attribute, like their email or phone number. A Global Secondary Index (GSI) acts like a separate smaller filing cabinet that organizes the same data but by these alternate keys.

This index stores copies of selected attributes and lets you quickly search using keys that differ from the main table's keys. It works independently, so queries on the GSI do not slow down the main table. Updates to the main table automatically update the GSI behind the scenes.

Example

This example creates a DynamoDB table with a primary key and adds a Global Secondary Index to query by a different attribute.

python

import boto3

# Create DynamoDB client
client = boto3.client('dynamodb', region_name='us-west-2')

# Create table with a Global Secondary Index
response = client.create_table(
    TableName='Users',
    KeySchema=[
        {'AttributeName': 'UserID', 'KeyType': 'HASH'}  # Primary key
    ],
    AttributeDefinitions=[
        {'AttributeName': 'UserID', 'AttributeType': 'S'},
        {'AttributeName': 'Email', 'AttributeType': 'S'}  # Attribute for GSI
    ],
    ProvisionedThroughput={'ReadCapacityUnits': 5, 'WriteCapacityUnits': 5},
    GlobalSecondaryIndexes=[
        {
            'IndexName': 'EmailIndex',
            'KeySchema': [
                {'AttributeName': 'Email', 'KeyType': 'HASH'}  # GSI partition key
            ],
            'Projection': {'ProjectionType': 'ALL'},
            'ProvisionedThroughput': {'ReadCapacityUnits': 5, 'WriteCapacityUnits': 5}
        }
    ]
)

print('Table creation initiated:', response['TableDescription']['TableName'])

Output

Table creation initiated: Users

When to Use

Use a Global Secondary Index when you need to query your DynamoDB table using an attribute other than the primary key. For example, if your main key is UserID but you want to find users by their Email, a GSI lets you do this efficiently.

GSIs are helpful in real-world cases like searching customers by phone number, orders by status, or products by category. They improve query flexibility without redesigning your main table.

Key Points

• A GSI has its own partition key and optional sort key, different from the main table.
• It stores copies of data for fast queries on alternate keys.
• Updates to the main table automatically update the GSI.
• GSIs improve query options without slowing down the main table.
• They require additional throughput capacity and storage.

Key Takeaways

A Global Secondary Index lets you query DynamoDB tables using alternate keys efficiently.

GSIs work independently from the main table and update automatically.

Use GSIs when you need flexible queries on attributes other than the primary key.

Adding a GSI requires extra capacity and storage, so plan accordingly.

GSIs improve performance by avoiding full table scans for alternate queries.