Indexes & GSIs

Tablyne shows a table’s secondary indexes, lets you declare them at creation, and adds or drops Global Secondary Indexes (GSIs) on existing tables.

Viewing indexes

Open a table and look at its schema view. Under Secondary indexes each index is listed with:

• its name and kind — GSI (Global) or LSI (Local)
• its partition key (and sort key, if any)
• its projection — ALL, KEYS_ONLY or INCLUDE

The schema view also shows the base table keys, billing mode, item count, size, TTL status and stream status. Indexes are read from DescribeTable, so the list always reflects the live table.

Creating GSIs at table-creation time

The simplest place to add indexes is when you create the table — see Creating a table. The table starts empty, so there’s no backfill: the index keys populate as you write items. You can declare multiple GSIs there, each with its own keys, projection and (for provisioned tables) throughput.

Adding a GSI to an existing table

You can add a GSI to a populated table. DynamoDB backfills it asynchronously from the existing items, so Tablyne treats this as a guided operation through the GSI migration wizard:

1. Pre-flight — Tablyne checks the table is ACTIVE (you can’t add a GSI while the table is UPDATING), counts existing GSIs against the 20-per-table limit, and collects existing index names to prevent duplicates.
2. Define the index — name, partition key (+ type), optional sort key (+ type), and projection (ALL or KEYS_ONLY). For provisioned tables you also set per-index RCU/WCU.
3. Create — Tablyne declares the index’s key attributes and issues the UpdateTable create-GSI action.
4. Backfill poll — after the request, the index goes through CREATING → backfilling → ACTIVE. The wizard polls status and shows progress (state, whether it’s still backfilling, and item count) until the index is ready.

This flow is part of the GSI migration tooling under the Single-Table Design features.

Deleting a GSI

Dropping a GSI is a single UpdateTable delete action — the rollback for a create. In the wizard, removing an index you just created reverts the table to its prior shape. Deleting a GSI does not delete table items; it only removes the index and its storage.

Index facts worth knowing

Fact	Detail
GSI limit	20 GSIs per table
Backfill	Adding a GSI to a non-empty table backfills asynchronously
Projection	ALL copies every attribute; KEYS_ONLY only keys; INCLUDE keys + chosen attributes
LSIs	Local Secondary Indexes are shown but must be defined at table creation — they can’t be added later
Key types	S (string), N (number), B (binary)
Throughput	Per-index RCU/WCU apply only to provisioned tables; on-demand tables ignore them

What you can’t change

You cannot alter an existing index’s keys or projection in place — drop it and recreate it with the new shape. Base-table key schema is likewise immutable; restructuring requires a new table and a data migration. For querying through an index once it’s active, see Search & query and PartiQL.

Background: the indexes learn guide.