Go (AWS SDK v2) での DynamoDB PutItem
PutItem はアイテム全体を書き込み、新規作成するか、同じプライマリキーを持つ既存アイテムを置き換えます。AWS SDK for Go v2 では、Item マップに types パッケージの型付き値としてすべての属性を持つ dynamodb.PutItemInput を指定して client.PutItem を呼び出します。
Code
package main
import (
"context"
"errors"
"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)
_, err = client.PutItem(ctx, &dynamodb.PutItemInput{
TableName: aws.String("Music"),
Item: map[string]types.AttributeValue{
"Artist": &types.AttributeValueMemberS{Value: "Arturo Sandoval"},
"SongTitle": &types.AttributeValueMemberS{Value: "Cubano Chant"},
"AlbumTitle": &types.AttributeValueMemberS{Value: "Danzon"},
"Year": &types.AttributeValueMemberN{Value: "1994"},
"Awards": &types.AttributeValueMemberN{Value: "0"},
},
ConditionExpression: aws.String("attribute_not_exists(#cond0) AND attribute_not_exists(#cond1)"),
ExpressionAttributeNames: map[string]string{
"#cond0": "Artist",
"#cond1": "SongTitle",
},
})
if err != nil {
var ccf *types.ConditionalCheckFailedException
if errors.As(err, &ccf) {
fmt.Println("A song with that key already exists — not overwritten")
return
}
log.Fatalf("put item: %v", err)
}
fmt.Println("Song written")
}代わりに素の Go の構造体から Item マップを構築するには、github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue の attributevalue.MarshalMap を使いましょう。
Explanation
Item— テーブルの完全なプライマリキーと、その他の任意の属性を含める必要があります。数値はAttributeValueMemberNの中では文字列です({Value: "1994"})。- Put は置き換える — 条件がなければ、
PutItemは同じキーを持つ既存アイテムを黙って上書きします。残りを壊さずに一部の属性だけ変更するにはUpdateItemを使いましょう。 ConditionExpression— キー属性に対するattribute_not_exists(...)により、書き込みは作成のみの挿入になります。アイテムが既に存在する場合、書き込みはConditionalCheckFailedExceptionで失敗します。これは DynamoDB の楽観的ロックのプリミティブです。#cond0/#cond1エイリアスはExpressionAttributeNamesを介してArtist/SongTitleに解決されます(予約語に安全)。errors.As— Go SDK はサービスエラーをラップするため、文字列比較ではなくerrors.Asで型付きの*types.ConditionalCheckFailedExceptionを照合します。- 上書きされたアイテムを取得するには、
ReturnValues: types.ReturnValueAllOldを設定します。
Do it visually
条件付きの put を手作業で書いていますか?DynamoDB Expression Builder が ConditionExpression を組み立て、コードをコピーします。
GUI でアイテムを追加・編集するには(属性ごとのフォーム、型ピッカー、コードとしてコピー)、DynoTable をダウンロードしてください。
Related examples
- DynamoDB PutItem in Java — AWS SDK for Java 2.x による同じ条件付き書き込み。
- DynamoDB UpdateItem in Go — アイテムを置き換える代わりに特定の属性を変更する。
- DynamoDB condition expressions —
attribute_not_exists、楽観的ロックなど。 - DynamoDB ConditionalCheckFailedException — アイテムが既に存在するときに作成のみ条件が投げるもの。
- DynamoDB ValidationException — 不正なアイテムや式に対する包括的なエラー。
References
- PutItem — Amazon DynamoDB API Reference
- Use PutItem with an AWS SDK or CLI — Amazon DynamoDB Developer Guide
- dynamodb package — AWS SDK for Go v2 (pkg.go.dev)
- dynamodb/types package — AWS SDK for Go v2 (pkg.go.dev)
- Handling errors — AWS SDK for Go v2 Developer Guide
- Condition expressions — Amazon DynamoDB Developer Guide
最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。