在 Go（AWS SDK v2）中使用 DynamoDB Query

Query 讀取共用同一個 partition key 的每一個項目，並可選擇以 sort key 縮小範圍。在 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 — 必須包含對 partition key 的相等條件（#hashKey = :hashKeyValue），加上至多一個 sort-key 條件（=、<、<=、>、>=、BETWEEN 或 begins_with）。#hashKey/#rangeKey 別名透過 ExpressionAttributeNames 解析為 Artist/SongTitle（保留字安全）。
• ExpressionAttributeValues — :placeholder → 帶型別值的 map（&types.AttributeValueMemberS{...}）。
• 分頁 — 單次 Query 最多回傳 1 MB。dynamodb.NewQueryPaginator 包裝 client，並持續呼叫直到 LastEvaluatedKey 耗盡；HasMorePages() / NextPage(ctx) 迴圈是 SDK 的標準模式。
• 設定 ScanIndexForward: aws.Bool(false) 可反轉 sort-key 順序（預設為遞增）。
• 加上 IndexName: aws.String("...") 可查詢 secondary index。
• 偏好在程式碼中建立條件？expression 套件（github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression）會組合 expression.Key(...).Equal(...) builder 並產生 name/value map；attributevalue.UnmarshalListOfMaps 會把 page.Items 轉成 Go struct。

改用視覺化操作

DynamoDB Expression Builder 會組裝 key condition 並複製可執行的程式碼，讓你不用手寫 placeholder 與 value map。

想在 GUI 中對實際表格執行查詢 — key-condition 表單、分頁格線、複製為程式碼 — 下載 DynoTable。

相關範例

• 在 Java 中使用 DynamoDB Query — 以 AWS SDK for Java 2.x 執行相同的查詢。
• 在 Go 中使用 DynamoDB Scan — 當你無法以 key 切入某個 partition 時。
• Query vs. Scan — 為什麼 Query 是正確的預設。
• Key condition 運算式 — 每個合法的 partition/sort-key 運算子。
• "Query condition missed key schema element" — key condition 指名了錯誤的屬性，或略過了 partition key。
• "Query key condition not supported" — key condition 無法使用的運算子，例如 contains 或第二個 sort-key 條件。

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

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。