Help Center/ Key-Value Storage Service/ FAQs/ KVS Concepts/ What Are the Differences Between Local and Global Secondary Indexes?
Updated on 2025-04-14 GMT+08:00
View PDF
Share

What Are the Differences Between Local and Global Secondary Indexes?

Table 1 compares the local secondary index and the global secondary index.

Each index belongs to a table, which is called its base table.

Table 1 Comparison between the local secondary index and the global secondary index

Dimension

Local Secondary Index

Global Secondary Index

Definition

A local secondary index has the same shard key as its base table, but a different sort key. It is supported for tables with a composite primary key (shard key and sort key) and helps accelerate queries through the specified sort key.

A global secondary index has a different shard key from the base table. Each index item stores only the index data. Other data in the corresponding KV item is not included.

Scenario

Suppose a user exercise table has the following fields: username, city, duration, date, and calories burned.

In the primary index of this table, the shard key is username, and the sort key is duration. In its local secondary index, the sort key is date. Using these indexes together, you can quickly determine which user exercised the longest or shortest on a particular day.

Suppose a user exercise table has the following fields: username, city, duration, date, and calories burned.

In the primary index of this table, the shard key is username, and the sort key is duration. In its global secondary index, the shard key is city, and the sort key is calories burned. Because the primary key fields (username and duration in this example) are projected into the global secondary index, you can use all these indexes together to quickly determine which user burned the most or least calories in a specific city.

Key structure

Composite primary key (shard key and sort key)

Simple primary key (shard key) or composite primary key (shard key and sort key)

Feature

A local secondary index has the same shard key as its base table, but a different sort key.

A global secondary index has a different shard key from the base table.

Consistency

When a KV item is written, a local secondary index item is automatically generated and stored with strong consistency.

When a KV item is written, an index item is automatically generated and then asynchronously written to the global secondary index with eventual consistency.

Quantity limits

Each table can have up to five local secondary indexes.

Each table can have up to 20 global secondary indexes.
Parent topic: KVS Concepts