Global Secondary Index (GSI)

A table is restricted to a maximum of 20 Global Secondary Indexes

Replication

Duplication of attributes from base table to GSI is asynchronous.

GSI-replication

Query/Scan scope

A Global Secondary Index is considered “global” because queries on the index can span all of the data in the base table, across all partitions. Let me explain this with an example

Let’s say there is a base table with Partition Key = base_pk , Sort Key = base_sk, and a non-key attribute X. As you can see in the illustration X = 1 is appearing multiple partition and it is ok as it is a non-key attribute in the base table.

Think of a query to get all items where x = 1, this query will not work as the query span for the base table is partition. In order to address this query we will need to create a GSI with X as the Partition key-attribute. So Lets create a GSI with X as the Partition Key, and base_SK as the Sort Key. Now in the query we can use this GSI with Partition Key x = 1, to get all the items in which x = 1

The GSI query can span across all base table partitions and hence the index is referred to as Global.

GSI-scope

GSI Creation

GSI may be managed independent of the table.

Example is using a JSON file for index definition.

aws dynamodb update-table \
    --table-name Orders \
    --cli-input-json file://dynamodb/indexes/gsi_OrderDate.json

JSON

{
    "AttributeDefinitions": [
      {
        "AttributeName": "OrderDate",
        "AttributeType": "S"
      },
      {
        "AttributeName": "OrderId",
        "AttributeType": "S"
      },
      {
        "AttributeName": "Customer",
        "AttributeType": "S"
      },
      {
        "AttributeName": "OrderStatus",
        "AttributeType": "S"
      }
    ],
    "GlobalSecondaryIndexUpdates": [
      {
        "Create": {
          "IndexName": "GSI_OrderDate",
          "KeySchema": [
            {
              "AttributeName": "OrderDate",
              "KeyType": "HASH"
            },
            {
                "AttributeName": "OrderId",
                "KeyType": "Range"
            }
          ],
          "Projection": {
            "ProjectionType": "ALL"
          },
          "ProvisionedThroughput": {
            "ReadCapacityUnits": 5,
            "WriteCapacityUnits": 5
          }
        }
      }
    ]
  }