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/attributevalueattributevalue.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 BuilderConditionExpression を組み立て、コードをコピーします。

GUI でアイテムを追加・編集するには(属性ごとのフォーム、型ピッカー、コードとしてコピー)、DynoTable をダウンロードしてください。

References

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

Console なしで DynamoDB を扱う

DynoTable は DynamoDB 向けの高速なデスクトップクライアントです — テーブルを閲覧し、SQL スタイルのクエリを実行し、アイテムをローカルで編集できます。