Secondary Indexes

A DynamoDB table's primary key supports one access pattern. When you need to query data by different attributes, you create secondary indexes. DynamoDB supports two types: Global Secondary Indexes (GSI) and Local Secondary Indexes (LSI).

---

Why Secondary Indexes?

Consider a table with a primary key of UserId:

Table: Users (PK = UserId)

UserId     Name      Email                 Country
user-001   Alice     alice@example.com     UK
user-002   Bob       bob@example.com       US
user-003   Charlie   charlie@example.com   UK

You can efficiently look up a user by UserId, but what if you need to:

• Find all users in a specific country?
• Look up a user by email?
• List users sorted by name?

Without indexes, you would need a Scan (reading every item). Secondary indexes let you Query efficiently by different attributes.

---

Global Secondary Index (GSI)

A GSI has its own partition key and sort key, which can be any attributes from the table:

Feature	Description
Partition key	Any attribute (different from table PK)
Sort key	Optional; any attribute
Consistency	Eventually consistent only
Capacity	Has its own provisioned or on-demand capacity
Creation	Can be added or removed at any time
Limit	Up to 20 GSIs per table

Creating a GSI (AWS CLI)

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

Querying a GSI

aws dynamodb query \
  --table-name Users \
  --index-name Country-Name-index \
  --key-condition-expression "Country = :c" \
  --expression-attribute-values '{":c": {"S": "UK"}}'

---

Local Secondary Index (LSI)

An LSI shares the table's partition key but uses a different sort key:

Feature	Description
Partition key	Same as the table's partition key
Sort key	A different attribute from the table's sort key
Consistency	Supports both eventually and strongly consistent reads
Capacity	Shares the table's provisioned capacity
Creation	Must be created at table creation time — cannot be added later
Limit	Up to 5 LSIs per table
Item collection limit	10 GB per partition key value (across table + all LSIs)

Creating a Table with an LSI

aws dynamodb create-table \
  --table-name Orders \
  --attribute-definitions \
    AttributeName=CustomerId,AttributeType=S \
    AttributeName=OrderDate,AttributeType=S \
    AttributeName=Total,AttributeType=N \
  --key-schema \
    AttributeName=CustomerId,KeyType=HASH \
    AttributeName=OrderDate,KeyType=RANGE \
  --local-secondary-indexes '[
    {
      "IndexName": "CustomerId-Total-index",
      "KeySchema": [
        {"AttributeName": "CustomerId", "KeyType": "HASH"},
        {"AttributeName": "Total", "KeyType": "RANGE"}
      ],
      "Projection": {"ProjectionType": "ALL"}
    }
  ]' \
  --billing-mode PAY_PER_REQUEST

Now you can query a customer's orders sorted by total amount.

---

Projections

When you create an index, you choose which attributes to project (copy) into the index: