Lab · Task 3.3 · about 35 minutes
Keys, Sparse Indexes and Read Consistency
Services in this lab
- Amazon DynamoDBin scope
Lesson for this lab: High-Performing Databases
Goal
Build a DynamoDB table keyed by customer and order, add a sparse global secondary index on open orders, query it, and see a strongly consistent read against the index get rejected.
Before you start
- An AWS account you can experiment in, ideally a sandbox account with a budget alert. Don't use the root user; sign in with an IAM Identity Center user or an IAM role that can manage DynamoDB tables.
- AWS CLI v2 configured for that identity, and one Region chosen for the whole lab (for example
us-east-1). Run every command in one terminal session so the shell variables carry over. - No network access to the table is needed beyond the CLI itself. The lab creates no VPC, instance or endpoint.
Resources this lab creates (the clean-up list): one DynamoDB table with one global secondary index, and a local JSON file.
Steps
0 of 6 steps done
The base table uses
CustomerIdas the partition key andOrderIdas the sort key. The indexOpenOrdersIndexusesOrderStatusas its partition key andOrderDateas its sort key. Both are declared as attributes, and the table uses on-demand capacity so you don't pick a throughput.aws dynamodb create-table \ --table-name lab33-orders \ --attribute-definitions \ AttributeName=CustomerId,AttributeType=S \ AttributeName=OrderId,AttributeType=S \ AttributeName=OrderStatus,AttributeType=S \ AttributeName=OrderDate,AttributeType=S \ --key-schema AttributeName=CustomerId,KeyType=HASH AttributeName=OrderId,KeyType=RANGE \ --billing-mode PAY_PER_REQUEST \ --global-secondary-indexes '[{"IndexName":"OpenOrdersIndex","KeySchema":[{"AttributeName":"OrderStatus","KeyType":"HASH"},{"AttributeName":"OrderDate","KeyType":"RANGE"}],"Projection":{"ProjectionType":"ALL"}}]' aws dynamodb wait table-exists --table-name lab33-ordersConsole: DynamoDB > Tables > Create table, name
lab33-orders, partition keyCustomerId(String), sort keyOrderId(String), and under Table settings choose on-demand. Then open the Indexes tab and createOpenOrdersIndexwith partition keyOrderStatusand sort keyOrderDate, both String.Only items that carry
OrderStatusare written to the index. Two of the five orders have no status attribute on purpose, so they stay out ofOpenOrdersIndex.cat > items.json <<'EOF' { "lab33-orders": [ {"PutRequest": {"Item": {"CustomerId": {"S": "cust-001"}, "OrderId": {"S": "o-1001"}, "OrderDate": {"S": "2026-11-01"}, "OrderStatus": {"S": "open"}}}}, {"PutRequest": {"Item": {"CustomerId": {"S": "cust-001"}, "OrderId": {"S": "o-1002"}, "OrderDate": {"S": "2026-10-03"}}}}, {"PutRequest": {"Item": {"CustomerId": {"S": "cust-002"}, "OrderId": {"S": "o-2001"}, "OrderDate": {"S": "2026-11-09"}, "OrderStatus": {"S": "open"}}}}, {"PutRequest": {"Item": {"CustomerId": {"S": "cust-002"}, "OrderId": {"S": "o-2002"}, "OrderDate": {"S": "2026-09-20"}, "OrderStatus": {"S": "shipped"}}}}, {"PutRequest": {"Item": {"CustomerId": {"S": "cust-003"}, "OrderId": {"S": "o-3001"}, "OrderDate": {"S": "2026-11-12"}}}} ] } EOF aws dynamodb batch-write-item --request-items file://items.jsonThe output should list no
UnprocessedItems. If it does, run the same command again with the returned items.A Query needs the partition key. Read one customer's orders from the base table, which returns both of that customer's orders, including the one with no status.
aws dynamodb query --table-name lab33-orders \ --key-condition-expression "CustomerId = :c" \ --expression-attribute-values '{":c":{"S":"cust-001"}}' \ --query 'Items[].OrderId.S'Console: DynamoDB > Explore items, choose
lab33-orders, set the partition key tocust-001, and run the query.The index returns only the items that have an
OrderStatusattribute. The two orders without a status are absent, which is the sparse behavior the lesson describes.aws dynamodb query --table-name lab33-orders --index-name OpenOrdersIndex \ --key-condition-expression "OrderStatus = :s" \ --expression-attribute-values '{":s":{"S":"open"}}' \ --query 'Items[].[OrderId.S,OrderDate.S]' --output tableConsole: open the table's Indexes tab, choose
OpenOrdersIndex, and queryOrderStatusequal toopen.EXPECTED FAILURE. Add
--consistent-readto the index query. DynamoDB rejects the request, because strongly consistent reads are not supported on global secondary indexes, and nothing is returned.aws dynamodb query --table-name lab33-orders --index-name OpenOrdersIndex \ --key-condition-expression "OrderStatus = :s" \ --expression-attribute-values '{":s":{"S":"open"}}' \ --consistent-readThis is the trap from the lesson. A global secondary index is eventually consistent, so a read that must reflect a write you just made goes to the base table instead. The error comes from the DynamoDB service. The docs don't quote the error text, so judge the outcome: the request is refused and returns no items.
The same guarantee works when the read goes to the base table. Read the order you just loaded by its full key with
--consistent-read.aws dynamodb get-item --table-name lab33-orders --consistent-read \ --key '{"CustomerId":{"S":"cust-003"},"OrderId":{"S":"o-3001"}}' \ --query 'Item.OrderId.S' --output textThe output is
o-3001.
Verify
aws dynamodb describe-table --table-name lab33-orders --query 'Table.[BillingModeSummary.BillingMode,GlobalSecondaryIndexes[0].IndexName,GlobalSecondaryIndexes[0].IndexStatus]' --output textreturnsPAY_PER_REQUEST,OpenOrdersIndexandACTIVE.- The base-table query for
cust-001returnso-1001ando-1002. - The index query for
openreturnso-1001ando-2001only.o-1002ando-3001are missing because they have noOrderStatus. - The index query with
--consistent-readfails and returns no items.
Clean up
Delete everything in this order.
-
Delete the table. Deleting a table also deletes its indexes, so there is no separate index step.
aws dynamodb delete-table --table-name lab33-orders aws dynamodb wait table-not-exists --table-name lab33-ordersConsole: DynamoDB > Tables, select
lab33-orders, Delete, and confirm. -
Remove the local file:
rm items.json. -
Check that nothing remains. The first command should return an empty list, and the second should not list
lab33-orders:aws dynamodb list-tables --query 'TableNames[?starts_with(@, `lab33`)]' aws dynamodb describe-table --table-name lab33-orders 2>&1 | grep -c ResourceNotFoundExceptionThe second command should print
1, which means the table no longer exists.
Sources
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-design.html
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Constraints.html
- https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/on-demand-capacity-mode.html
Last reviewed