Python（boto3）中查询 DynamoDB GSI

查询一个全局二级索引就是一次普通的 query 加上一个参数：IndexName。键条件随即针对索引的键，而非表的键——这里 AlbumTitle-index 让我们能按专辑获取歌曲，而基表（Artist + SongTitle）不做扫描就无法服务这种访问模式。

Code

import boto3

client = boto3.client("dynamodb")

paginator = client.get_paginator("query")

items = []
for page in paginator.paginate(
    TableName="Music",
    IndexName="AlbumTitle-index",
    KeyConditionExpression="#hashKey = :hashKeyValue",
    ExpressionAttributeNames={"#hashKey": "AlbumTitle"},
    ExpressionAttributeValues={":hashKeyValue": {"S": "Danzon"}},
):
    items.extend(page["Items"])

print(f"Found {len(items)} songs on the album")

说明

IndexName — 指定要查询的 GSI（TableName 仍然必需）。KeyConditionExpression 使用索引的分区键（以及可选的排序键）——这里是 AlbumTitle——运算符与表查询相同。
仅最终一致性 — GSI 从基表异步复制。在 GSI 查询上传入 ConsistentRead=True 并不会将其升级；它会引发 ValidationException。（本地二级索引确实支持强一致性。）
你只得到被投影的属性 — 一次 GSI 查询返回索引所投影的内容（ALL、KEYS_ONLY 或 INCLUDE 列出的属性），且不能从基表获取其余部分。需要一个未被投影的属性？请对表键后续做一次 get_item，或加宽投影。
GSI 中的键不唯一 — 许多项目可以共享同一个索引键，而缺少该索引键属性的项目根本不会出现（这就是稀疏索引模式）。
分页 — client.get_paginator("query") 会像在表查询上一样跨页跟随 LastEvaluatedKey；每个 page 携带一个 Items 列表。
在 resource API 上，同样的查询是 table.query(IndexName="AlbumTitle-index", KeyConditionExpression=Key("AlbumTitle").eq("Danzon"))，使用原生 Python 值。

可视化操作

DynamoDB Expression Builder 会为索引查询构建键条件 + 名称/值映射并复制可运行的 boto3 代码。

想浏览一张表的索引并用表单运行 GSI 查询——分页网格、复制为代码——请下载 DynoTable。

References

Last verified 2026-07-13 against the official AWS documentation linked above.

Python（boto3）中查询 DynamoDB GSI

Code

说明

可视化操作

相关示例

References

可视化构建此请求