In this lesson, you will learn how to efficiently query distributed data by attributes that are not part of your primary partitioning strategy using Global Secondary Indexes (GSIs).
The Challenge of Partitioning
When you implement Hash-Based or Range-Based Sharding, you optimize your database for lookups based on the shard key. For example, if your Users table is partitioned by user_id, a query like SELECT * FROM users WHERE email = 'alice@example.com' becomes a nightmare. Since the email isn't the shard key, the system has no idea which node holds that record, forcing a "scatter-gather" operation where every shard must be queried. This destroys performance as the cluster grows.
Global Secondary Indexes (GSI)
A Global Secondary Index solves this by decoupling the index from the base table's partition key. Think of a GSI as a separate, hidden table managed by the database engine. If you create an index on email, the database maintains a map where the index key is email and the value is a reference (or pointer) to the original user_id and the physical shard location.
Because the GSI itself must also be distributed, it is usually partitioned independently of the base table. A write to the base table triggers an asynchronous update to the GSI:
-- Conceptual Schema
CREATE TABLE Users (
user_id UUID PRIMARY KEY,
email TEXT,
name TEXT
) PARTITION BY HASH(user_id);
-- The GSI is a separate distributed structure
CREATE INDEX idx_user_email ON Users(email);
Consistency Trade-offs
Because the index exists across different nodes than the base record, updating both the data and the index is not atomic unless you involve a Distributed Transaction Coordinator or a Two-Phase Commit (2PC). Most high-scale systems opt for eventual consistency between the base table and the GSI. When you perform an insert, the record is committed to the primary shard, and the GSI is updated shortly thereafter using background replication. This ensures your primary writes remain fast while enabling sub-millisecond lookups on non-primary fields.
Key Takeaway: Global Secondary Indexes allow you to bypass primary partitioning constraints by maintaining a separate, distributed mapping that enables fast lookups on arbitrary attributes at the cost of slight write amplification and eventual consistency.