createGlobalSecondaryIndex

createGlobalSecondaryIndex is a Change Type in the Liquibase DynamoDB Pro extension that creates a new global secondary index on a table. For more information, see Using Global Secondary Indexes in DynamoDB.

Uses

A secondary index lets you query the data in the table using an alternate key, in addition to queries against the primary key. A global secondary index is an index with a partition key and sort key that can be different from those on the table. It is different from a local secondary index, which is an index with the same partition key as the table, but a different sort key. For more information, see Core components of Amazon DynamoDB.

Run createGlobalSecondaryIndex

To run this Change Type, follow these steps:

  1. Add the Change Type to your changeset, as shown in the examples on this page.
  2. Specify any required attributes. Use the table on this page to see which ones your database requires.
  3. Deploy your changeset by running the update command:
    4. liquibase update

Now, Liquibase deploys your change on your DynamoDB database. By default, read operations on DynamoDB are eventually consistent. When you look at your database immediately after running liquibase update, DynamoDB may display the status of an object as CREATING, UPDATING, or DELETING. When it finishes, it displays the status as ACTIVE.

Note: If your deployment fails because the DynamoDB waiter times out or reaches a retry limit, you can modify the waiter settings using Liquibase Parameters for Amazon DynamoDB Pro.

Available attributes

For more information, see DynamoDB API: CreateTable and DynamoDB API: CreateGlobalSecondaryIndexAction.

Tip: You must specify all top-level attributes marked as required. If you specify an optional attribute, you must also specify any nested attributes that it requires.

Name Type Description Requirement
tableName String

Name of the table for which to add the index

 Required

attributeDefinitions

Required.

An array of attributeDefinition objects that describe attributes from the key schema of a table or index.

You must specify all attributes you use in keySchema within individual attributeDefinition objects in the attributeDefinitions array. For example, if your key schema contains the hash attribute Artist, you must also specify Artist and its data type in an attributeDefinition. However, attributeDefinitions can contain additional non-key attributes that aren't in keySchema.

Individual attributeDefinition objects have the following nested attributes:

  • attributeName (string) (required): the name of the attribute.
  • attributeType (string) (required): the data type of the attribute. Valid values are S (string), N (number), and B (binary).

globalSecondaryIndex

Required.

An individual globalSecondaryIndex object to create on the table. You can specify between 1 and 20 global secondary indexes on a particular table.

Individual globalSecondaryIndex objects have the following nested attributes:

  • indexName (string) (required): the name of the local secondary index. The name must be unique among all other indexes on this table.
  • keySchema (required): the key schema for the local secondary index.
    • hashAttributeName (string) (required): the name of the partition key.
    • rangeAttributeName (string) (required): the name of the sort key.
  • projection (required): specifies attributes that are copied (projected) from the table into the index. These are in addition to the primary key attributes and index key attributes, which are automatically projected. Each attribute specification is composed of:
    • projectionType (string) (optional): specifies which kinds of attributes are projected into the index. Valid values are KEYS_ONLY (only project the index and primary keys), INCLUDE (project the index and primary keys as well as other non-key attributes), and ALL (project all table attributes). The default value is ALL.
    • nonKeyAttributes (optional): an array of non-key attributes which will be projected into the index. You can specify between 1 and 20 non-key attributes in a single secondary index. You can specify up to 100 non-key attributes across all local and global secondary indexes on a particular table (duplicate non-key attributes are counted multiple times).
      • attributeName (string) (optional): the name of this particular non-key attribute
  • provisionedThroughput (optional): specifies the provisioned throughput settings for the index.
    • readCapacityUnits (integer) (required): the maximum number of reads per second before throttling.
    • writeCapacityUnits (integer) (required): the maximum number of writes per second before throttling.

Examples

databaseChangeLog:
  - changeSet:
      id: 2
      author: your.name
      changes:
        - createGlobalSecondaryIndex:
            tableName: GlobalIndexTestYaml
            attributeDefinitions:
              - attributeDefinition:
                  attributeName: Artist
                  attributeType: S
              - attributeDefinition:
                  attributeName: AlbumTitle
                  attributeType: S
            globalSecondaryIndex:
              indexName: globalIndex2Yaml
              keySchema:
                hashAttributeName: Artist
                rangeAttributeName: AlbumTitle
              projection:
                projectionType: INCLUDE
                nonKeyAttributes:
                  - attributeName: SongTitle
              provisionedThroughput:
                readCapacityUnits: 9
                writeCapacityUnits: 9
      rollback:
        - deleteGlobalSecondaryIndex:
            tableName: GlobalIndexTestYaml
            indexName: globalIndex2Yaml
{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "2",
        "author": "your.name",
        "changes": [
          {
            "createGlobalSecondaryIndex": {
              "tableName": "GlobalIndexTestJson",
              "attributeDefinitions": [
                {
                  "attributeDefinition": {
                    "attributeName": "Artist",
                    "attributeType": "S"
                  }
                },
                {
                  "attributeDefinition": {
                    "attributeName": "AlbumTitle",
                    "attributeType": "S"
                  }
                }
              ],
              "globalSecondaryIndex": {
                "indexName": "globalIndex2Json",
                "keySchema": {
                  "hashAttributeName": "Artist",
                  "rangeAttributeName": "AlbumTitle"
                },
                "projection": {
                  "projectionType": "INCLUDE",
                  "nonKeyAttributes": [
                    {
                      "attributeName": "SongTitle"
                    }
                  ]
                },
                "provisionedThroughput": {
                  "readCapacityUnits": 9,
                  "writeCapacityUnits": 9
                }
              }
            }
          }
        ],
        "rollback": [
          {
            "deleteGlobalSecondaryIndex": {
              "tableName": "GlobalIndexTestJson",
              "indexName": "globalIndex2Json"
            }
          }
        ]
      }
    }
  ]
}
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:dynamodb="http://www.liquibase.org/xml/ns/pro-dynamodb"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/pro-dynamodb
        http://www.liquibase.org/xml/ns/pro-dynamodb/liquibase-pro-dynamodb-latest.xsd
        http://www.liquibase.org/xml/ns/pro
        http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">

    <changeSet id="2" author="your.name">
        <dynamodb-pro:createGlobalSecondaryIndex tableName="GlobalIndexTest">
            <dynamodb-pro:attributeDefinitions>
                <dynamodb-pro:attributeDefinition attributeName="Artist" attributeType="S"/>
                <dynamodb-pro:attributeDefinition attributeName="AlbumTitle" attributeType="S"/>
            </dynamodb-pro:attributeDefinitions>
            <dynamodb-pro:globalSecondaryIndex indexName="globalIndex2">
                <dynamodb-pro:keySchema hashAttributeName="Artist" rangeAttributeName="AlbumTitle"/>
                <dynamodb-pro:projection projectionType="INCLUDE">
                    <dynamodb-pro:nonKeyAttributes attributeName="SongTitle"/>
                </dynamodb-pro:projection>
                <dynamodb-pro:provisionedThroughput readCapacityUnits="9" writeCapacityUnits="9"/>
            </dynamodb-pro:globalSecondaryIndex>
        </dynamodb-pro:createGlobalSecondaryIndex>

        <rollback>
            <dynamodb-pro:deleteGlobalSecondaryIndex tableName="GlobalIndexTest" indexName="globalIndex2" />
        </rollback>
    </changeSet>

</databaseChangeLog>

Database support

This Change Type is only supported for Amazon DynamoDB. It does not support auto rollback.