Querying GSI in DynamoDB - Step-by-Step Execution

Concept Flow - Querying GSI

Start Query

↓

Specify GSI Name

↓

Set KeyConditionExpression on GSI

↓

Send Query to DynamoDB

↓

DynamoDB Searches GSI

↓

Return Matching Items

↓

Process Results

The query starts by specifying the GSI name and key condition, then DynamoDB searches the GSI and returns matching items.

Execution Sample

DynamoDB

query_params = {
  'TableName': 'Orders',
  'IndexName': 'CustomerIndex',
  'KeyConditionExpression': 'CustomerId = :cid',
  'ExpressionAttributeValues': { ':cid': { 'S': 'C123' } }
}
result = dynamodb.query(query_params)

This code queries the 'Orders' table using the 'CustomerIndex' GSI to find orders for customer 'C123'.

Execution Table

Step	Action	Parameter/Value	DynamoDB Internal Process	Result
1	Start Query	TableName='Orders'	Prepare to query 'Orders' table	Ready to query
2	Specify GSI	IndexName='CustomerIndex'	Use GSI 'CustomerIndex' instead of main table index	GSI selected
3	Set KeyConditionExpression	CustomerId = :cid	Filter items where CustomerId equals 'C123'	Condition set
4	Set ExpressionAttributeValues	:cid = 'C123'	Bind value 'C123' to :cid	Value bound
5	Send Query	Execute query with parameters	DynamoDB searches GSI for matching items	Query sent
6	DynamoDB Search	Search GSI for CustomerId='C123'	Scan GSI partitions for matching keys	Matching items found
7	Return Results	Return matching items	Send items back to client	Items received
8	Process Results	Client processes returned items	Display or use data	Query complete

💡 Query completes after DynamoDB returns all matching items from the specified GSI.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	After Step 5	Final
query_params	{}	{ 'TableName': 'Orders', 'IndexName': 'CustomerIndex' }	{ 'TableName': 'Orders', 'IndexName': 'CustomerIndex', 'KeyConditionExpression': 'CustomerId = :cid' }	{ 'TableName': 'Orders', 'IndexName': 'CustomerIndex', 'KeyConditionExpression': 'CustomerId = :cid', 'ExpressionAttributeValues': { ':cid': { 'S': 'C123' } } }	Sent to DynamoDB for query	Sent to DynamoDB for query

Key Moments - 3 Insights

Why do we need to specify the IndexName when querying a GSI?

Because without specifying IndexName, DynamoDB queries the main table's primary key. Specifying IndexName tells DynamoDB to use the GSI instead, as shown in execution_table step 2.

Can we use the main table's primary key attributes in the KeyConditionExpression when querying a GSI?

No, the KeyConditionExpression must use the GSI's key attributes. This is shown in step 3 where the condition uses 'CustomerId', which is the GSI partition key.

What happens if no items match the KeyConditionExpression in the GSI?

DynamoDB returns an empty result set. The query still completes successfully as shown in step 7, but with zero items.

Visual Quiz - 3 Questions

Look at the execution_table, at which step is the GSI specified for the query?

A Step 2

B Step 3

C Step 5

D Step 7

💡 Hint

Check the 'Action' and 'Parameter/Value' columns in execution_table row for step 2.

According to variable_tracker, what is the value of query_params after step 4?

A { TableName: 'Orders', IndexName: 'CustomerIndex' }

B { 'TableName': 'Orders', 'IndexName': 'CustomerIndex', 'KeyConditionExpression': 'CustomerId = :cid', 'ExpressionAttributeValues': { ':cid': { 'S': 'C123' } } }

C { TableName: 'Orders', IndexName: 'CustomerIndex', KeyConditionExpression: 'CustomerId = :cid' }

D {}

💡 Hint

Look at the 'After Step 4' column in variable_tracker for query_params.

If we omit the IndexName parameter, what will DynamoDB query according to the concept_flow?

A The specified GSI

B An error is thrown

C The main table's primary key

D All indexes are queried

💡 Hint

Refer to concept_flow where specifying GSI is a separate step before querying.

Concept Snapshot

Querying a GSI in DynamoDB:
- Use 'IndexName' to specify the GSI.
- KeyConditionExpression must use GSI keys.
- ExpressionAttributeValues bind values.
- DynamoDB returns matching items from the GSI.
- Without IndexName, main table is queried.

Full Transcript

This visual execution trace shows how to query a Global Secondary Index (GSI) in DynamoDB. First, you prepare query parameters including the table name and specify the GSI name using 'IndexName'. Then, you set a KeyConditionExpression using the GSI's key attributes and bind values with ExpressionAttributeValues. When the query is sent, DynamoDB searches the GSI for matching items and returns them. The variable tracker shows how the query parameters build up step-by-step. Key moments clarify why specifying the GSI is necessary and how the query behaves if no items match. The quiz questions test understanding of these steps and parameters.