Global Secondary Index (GSI) concept in DynamoDB

Introduction

A Global Secondary Index (GSI) helps you find data in a DynamoDB table using different keys than the main table keys.

You want to search your data by a different attribute than the main key.

You need faster queries on a specific column without scanning the whole table.

You want to sort or filter data using another attribute.

You want to create multiple ways to look up your data.

You want to improve read performance for specific queries.

Syntax

DynamoDB

CreateTable {
  TableName: string,
  KeySchema: [
    { AttributeName: string, KeyType: 'HASH' | 'RANGE' }
  ],
  AttributeDefinitions: [
    { AttributeName: string, AttributeType: 'S' | 'N' | 'B' }
  ],
  GlobalSecondaryIndexes: [
    {
      IndexName: string,
      KeySchema: [
        { AttributeName: string, KeyType: 'HASH' | 'RANGE' }
      ],
      Projection: {
        ProjectionType: 'ALL' | 'KEYS_ONLY' | 'INCLUDE',
        NonKeyAttributes?: [string]
      },
      ProvisionedThroughput: {
        ReadCapacityUnits: number,
        WriteCapacityUnits: number
      }
    }
  ]
}

The GSI has its own key schema, which can be different from the main table's keys.

Projection defines which attributes are copied to the GSI for faster access.

Examples

This example creates a GSI named 'GSI1' using 'Category' as the partition key and copies all attributes.

DynamoDB

GlobalSecondaryIndexes: [
  {
    IndexName: 'GSI1',
    KeySchema: [
      { AttributeName: 'Category', KeyType: 'HASH' }
    ],
    Projection: { ProjectionType: 'ALL' },
    ProvisionedThroughput: { ReadCapacityUnits: 5, WriteCapacityUnits: 5 }
  }
]

This GSI uses 'Status' as partition key and 'CreatedDate' as sort key, including only 'Title' and 'Description' attributes.

DynamoDB

GlobalSecondaryIndexes: [
  {
    IndexName: 'GSI2',
    KeySchema: [
      { AttributeName: 'Status', KeyType: 'HASH' },
      { AttributeName: 'CreatedDate', KeyType: 'RANGE' }
    ],
    Projection: { ProjectionType: 'INCLUDE', NonKeyAttributes: ['Title', 'Description'] },
    ProvisionedThroughput: { ReadCapacityUnits: 10, WriteCapacityUnits: 5 }
  }
]

Sample Program

This creates a 'Books' table with 'BookID' as the main key. It adds a GSI called 'AuthorIndex' to quickly find books by 'Author'.

DynamoDB

CreateTable {
  TableName: 'Books',
  KeySchema: [
    { AttributeName: 'BookID', KeyType: 'HASH' }
  ],
  AttributeDefinitions: [
    { AttributeName: 'BookID', AttributeType: 'S' },
    { AttributeName: 'Author', AttributeType: 'S' },
    { AttributeName: 'Genre', AttributeType: 'S' }
  ],
  ProvisionedThroughput: { ReadCapacityUnits: 5, WriteCapacityUnits: 5 },
  GlobalSecondaryIndexes: [
    {
      IndexName: 'AuthorIndex',
      KeySchema: [
        { AttributeName: 'Author', KeyType: 'HASH' }
      ],
      Projection: { ProjectionType: 'ALL' },
      ProvisionedThroughput: { ReadCapacityUnits: 5, WriteCapacityUnits: 5 }
    }
  ]
}

Important Notes

GSIs allow queries on non-primary key attributes without scanning the whole table.

GSIs have their own throughput settings, so monitor usage to avoid throttling.

Data in GSIs is eventually consistent with the main table.

Summary

Global Secondary Indexes let you search data using different keys.

They improve query speed for alternate access patterns.

GSIs have their own keys, projections, and throughput settings.