Go(AWS SDK v2)中的 DynamoDB Query
Query 读取共享同一个分区键的每个项目,并可选地按排序键收窄。在 AWS SDK for Go v2 中,你在一个 dynamodb.QueryInput 上写一个 KeyConditionExpression,内置的 QueryPaginator 会替你跨每个结果页跟随 LastEvaluatedKey。
Code
package main
import (
"context"
"fmt"
"log"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
func main() {
ctx := context.TODO()
cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-east-1"))
if err != nil {
log.Fatalf("load config: %v", err)
}
client := dynamodb.NewFromConfig(cfg)
paginator := dynamodb.NewQueryPaginator(client, &dynamodb.QueryInput{
TableName: aws.String("Music"),
KeyConditionExpression: aws.String(
"#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)"),
ExpressionAttributeNames: map[string]string{
"#hashKey": "Artist",
"#rangeKey": "SongTitle",
},
ExpressionAttributeValues: map[string]types.AttributeValue{
":hashKeyValue": &types.AttributeValueMemberS{Value: "Arturo Sandoval"},
":rangeKeyValue": &types.AttributeValueMemberS{Value: "C"},
},
})
var items []map[string]types.AttributeValue
for paginator.HasMorePages() {
page, err := paginator.NextPage(ctx)
if err != nil {
log.Fatalf("query: %v", err)
}
items = append(items, page.Items...)
}
fmt.Printf("Found %d items\n", len(items))
}说明
KeyConditionExpression— 必须包含分区键上的相等条件(#hashKey = :hashKeyValue),外加至多一个排序键条件(=、<、<=、>、>=、BETWEEN或begins_with)。#hashKey/#rangeKey别名通过ExpressionAttributeNames解析为Artist/SongTitle(保留字安全)。ExpressionAttributeValues—:placeholder→ 带类型值映射(&types.AttributeValueMemberS{...})。- 分页 — 单次
Query最多返回 1 MB。dynamodb.NewQueryPaginator包装了客户端,并不断调用直到LastEvaluatedKey被耗尽;HasMorePages()/NextPage(ctx)循环是 SDK 的规范模式。 - 设置
ScanIndexForward: aws.Bool(false)可反转排序键顺序(升序是默认值)。 - 通过添加
IndexName: aws.String("...")来查询二级索引。 - 更想用代码构建条件?
expression包(github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression)会组合expression.Key(...).Equal(...)构建器并生成名称/值映射;attributevalue.UnmarshalListOfMaps会把page.Items转成 Go 结构体。
可视化操作
DynamoDB Expression Builder 会组装键条件并复制可运行代码,让你无需手写占位符和值映射。
想在 GUI 中针对真实表运行查询——键条件表单、分页网格、复制为代码——请下载 DynoTable。
相关示例
- Java 中的 DynamoDB Query — 用 AWS SDK for Java 2.x 完成同样的查询。
- Go 中的 DynamoDB Scan — 当你无法按键落入某个分区时。
- Query vs. Scan — 为什么
Query是正确的默认选择。 - 键条件表达式 — 每个合法的分区/排序键运算符。
- "Query condition missed key schema element" — 键条件命名了错误的属性或跳过了分区键。
- "Query key condition not supported" — 键条件无法使用的运算符,例如 contains 或第二个排序键条件。
References
- Query — Amazon DynamoDB API Reference
- Use Query with an AWS SDK or CLI — Amazon DynamoDB Developer Guide
- dynamodb package — AWS SDK for Go v2 (pkg.go.dev)
- expression package — AWS SDK for Go v2 (pkg.go.dev)
- Querying tables — Amazon DynamoDB Developer Guide
Last verified 2026-07-13 against the official AWS documentation linked above.