Useful APIs for Working with Secondary Indexes in DynamoDB

These are notes on some useful APIs to work with GSI and LSI.

Query API (GSI/LSI)

GSI support Query and Scan.

In addition to the common query parameters, a Query command explicitly includes the name of the index to operate against.

A query can use only one index.

A Query operation only searches index key attribute values and supports a subset of comparison operators.

Because GSIs are updated asynchronously, you cannot use the ConsistentRead parameter with the query. For a GSI, with a partition-only key schema there is no ordering. For GSI with partition-sort key schema the ordering of the results for the same partition key is based on the sort key attribute.

UpdateTable API (GSI)

You can add/delete GSI through the console or through API call: UpdateTable API call with the GlobalSecondaryIndexes parameter. You can only add or delete one index per API call.

At any time there can be only one active add or delete index operation on a table. If you submit multiple requests, only the first add request is accepted and all subsequent add requests will fail till the first is finished.

The length of time to add a GSI depends on the size of the table and the amount of additional provisioned write throughput for Global Secondary Index creation. The process of adding or deleting an index could vary from a few minutes to a few hours.

When a GSI is being added or deleted, the table and existing indexes are still available. However, the new index becomes available only after the index creation process is finished. Once index creation starts, the index creation process cannot be canceled. Deleting an index will typically finish in a few minutes. Once a Global Secondary Index has been deleted, that index name can be used again when a new index is added.

To change your GSI’s provisioned throughput capacity, you can use the DynamoDB Console or the UpdateTable API or the PutScalingPolicy API for updating Auto Scaling policy settings.

DescribeTable API (GSI)

You can use the DynamoDB console or DescribeTable API to check the status of all indexes associated with the table. While the index is being created, the status will be “CREATING”. Once the creation is finished, the index state will be “ACTIVE”. For a delete index operation, when the request is complete, the deleted index will cease to exist.

The DescribeTable API will return detailed information about GSIs on a table.

Scan API (GSI/LSI)

GSIs can be scanned via the Console or the Scan API. To scan a GSI, explicitly reference the index in addition to the name of the table. You must specify the index partition attribute name and value. You can optionally specify a condition against the index key sort attribute.

Scan on GSIs will not support fetching of non-projected attributes. Parallel scan will be supported for indexes and the semantics are the same as that for the main table.

To scan LSI, explicitly reference the index in addition to the name of the table. Must specify index partition attribute name and value. You can optionally specify a condition against the index key sort attribute.

Scan on LSIs will support fetching of non-projected attributes. For LSI, the ordering within a collection will be the based on the order of the indexed attribute.

Open Questions

At one place of the AWS DynamoDB FAQ it says Local secondary indexes can only be queried via the Query API. However there is also a topic related to using Scan with LSI.