Golang DynamoDB: AWS SDK v2 Cheat Sheet

Use the AWS SDK for Go v2 to query DynamoDB with dynamodb.NewFromConfig, typed request structs and context-aware methods. Use attributevalue to convert Go structs to DynamoDB items, expression to build expressions, and Query or Scan paginators to read every page. These examples require Go 1.24 or later and cover table management, CRUD, batches, indexes and transactions.

Table of contents

• Setup
• Create table
• Delete table
• List tables
• Get all items / Scan in DynamoDB
• Get item
• Batch get item
• Put item
• Batch write / put item
• Query for a set of items
• Query an index
• Simple transaction
• Read transaction
• Query with sorting
• Query and Scan pagination
• Update item
• Conditionally update item
• Increment an item attribute
• Delete item
• Delete all items
• Run DynamoDB Local

Setup

Start a Go module and add the SDK packages. Each SDK module has its own version; the v2 in the import path identifies the SDK generation.

go mod init example.com/dynamodb-guide
go get github.com/aws/aws-sdk-go-v2/config \
  github.com/aws/aws-sdk-go-v2/credentials \
  github.com/aws/aws-sdk-go-v2/service/dynamodb \
  github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue \
  github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression
go mod init example.com/dynamodb-guide
go get github.com/aws/aws-sdk-go-v2/config \
  github.com/aws/aws-sdk-go-v2/credentials \
  github.com/aws/aws-sdk-go-v2/service/dynamodb \
  github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue \
  github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression

Put this setup in main.go. The remaining Go blocks are functions to add to the same file, outside main. The import block covers the complete collection; remove imports for functions you do not copy. Call only the operations you intend to run. The default main creates a client without writing data.

Credentials come from the SDK's default chain, including a configured profile or the runtime's IAM role. Keep real credentials out of source code. Set AWS_PROFILE for local development and use the Region where your table exists.

package main

import (
    "context"
    "errors"
    "fmt"
    "math/rand/v2"
    "time"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
    "github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression"
    "github.com/aws/aws-sdk-go-v2/service/dynamodb"
    "github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)

const tableName = "my-table"

type Item struct {
    ID        string `dynamodbav:"id"`
    Date      int    `dynamodbav:"date"`
    FirstName string `dynamodbav:"firstName"`
    Company   string `dynamodbav:"company"`
    Score     int    `dynamodbav:"score"`
    GSI1PK    string `dynamodbav:"gsi1pk,omitempty"`
    GSI1SK    int    `dynamodbav:"gsi1sk,omitempty"`
}

func itemKey(id string, date int) map[string]types.AttributeValue {
    return map[string]types.AttributeValue{
        "id": &types.AttributeValueMemberS{Value: id},
        "date": &types.AttributeValueMemberN{Value: fmt.Sprint(date)},
    }
}

func main() {
    ctx := context.Background()
    cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-east-1"))
    if err != nil {
        panic(err)
    }
    client := dynamodb.NewFromConfig(cfg)
    fmt.Printf("DynamoDB client ready: %T\n", client)
}
package main

import (
    "context"
    "errors"
    "fmt"
    "math/rand/v2"
    "time"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
    "github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression"
    "github.com/aws/aws-sdk-go-v2/service/dynamodb"
    "github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)

const tableName = "my-table"

type Item struct {
    ID        string `dynamodbav:"id"`
    Date      int    `dynamodbav:"date"`
    FirstName string `dynamodbav:"firstName"`
    Company   string `dynamodbav:"company"`
    Score     int    `dynamodbav:"score"`
    GSI1PK    string `dynamodbav:"gsi1pk,omitempty"`
    GSI1SK    int    `dynamodbav:"gsi1sk,omitempty"`
}

func itemKey(id string, date int) map[string]types.AttributeValue {
    return map[string]types.AttributeValue{
        "id": &types.AttributeValueMemberS{Value: id},
        "date": &types.AttributeValueMemberN{Value: fmt.Sprint(date)},
    }
}

func main() {
    ctx := context.Background()
    cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-east-1"))
    if err != nil {
        panic(err)
    }
    client := dynamodb.NewFromConfig(cfg)
    fmt.Printf("DynamoDB client ready: %T\n", client)
}

All item examples use my-table with String partition key id and Number sort key date. The optional GSI1 index uses String gsi1pk and Number gsi1sk. Both key attributes are required for a single-item operation. The date values below are numeric YYYYMMDD examples, not Unix timestamps.

The Go SDK examples, attributevalue reference and expression reference describe the APIs used here. Go SDK v1 reached end of support on July 31, 2025; do not mix its dynamodbattribute package with v2 types.

Create table

Define only the table and index key attributes in AttributeDefinitions. Other fields are schemaless. This creates an on-demand table and the index used later; it then waits for the table to become active. The two-minute wait is an application timeout, not a service guarantee.

func createTable(ctx context.Context, client *dynamodb.Client) error {
    _, err := client.CreateTable(ctx, &dynamodb.CreateTableInput{
        TableName: aws.String(tableName),
        BillingMode: types.BillingModePayPerRequest,
        AttributeDefinitions: []types.AttributeDefinition{
            {AttributeName: aws.String("id"), AttributeType: types.ScalarAttributeTypeS},
            {AttributeName: aws.String("date"), AttributeType: types.ScalarAttributeTypeN},
            {AttributeName: aws.String("gsi1pk"), AttributeType: types.ScalarAttributeTypeS},
            {AttributeName: aws.String("gsi1sk"), AttributeType: types.ScalarAttributeTypeN},
        },
        KeySchema: []types.KeySchemaElement{
            {AttributeName: aws.String("id"), KeyType: types.KeyTypeHash},
            {AttributeName: aws.String("date"), KeyType: types.KeyTypeRange},
        },
        GlobalSecondaryIndexes: []types.GlobalSecondaryIndex{{
            IndexName: aws.String("GSI1"),
            KeySchema: []types.KeySchemaElement{
                {AttributeName: aws.String("gsi1pk"), KeyType: types.KeyTypeHash},
                {AttributeName: aws.String("gsi1sk"), KeyType: types.KeyTypeRange},
            },
            Projection: &types.Projection{ProjectionType: types.ProjectionTypeAll},
        }},
    })
    if err != nil { return err }
    return dynamodb.NewTableExistsWaiter(client).Wait(ctx,
        &dynamodb.DescribeTableInput{TableName: aws.String(tableName)},
        2*time.Minute)
}
func createTable(ctx context.Context, client *dynamodb.Client) error {
    _, err := client.CreateTable(ctx, &dynamodb.CreateTableInput{
        TableName: aws.String(tableName),
        BillingMode: types.BillingModePayPerRequest,
        AttributeDefinitions: []types.AttributeDefinition{
            {AttributeName: aws.String("id"), AttributeType: types.ScalarAttributeTypeS},
            {AttributeName: aws.String("date"), AttributeType: types.ScalarAttributeTypeN},
            {AttributeName: aws.String("gsi1pk"), AttributeType: types.ScalarAttributeTypeS},
            {AttributeName: aws.String("gsi1sk"), AttributeType: types.ScalarAttributeTypeN},
        },
        KeySchema: []types.KeySchemaElement{
            {AttributeName: aws.String("id"), KeyType: types.KeyTypeHash},
            {AttributeName: aws.String("date"), KeyType: types.KeyTypeRange},
        },
        GlobalSecondaryIndexes: []types.GlobalSecondaryIndex{{
            IndexName: aws.String("GSI1"),
            KeySchema: []types.KeySchemaElement{
                {AttributeName: aws.String("gsi1pk"), KeyType: types.KeyTypeHash},
                {AttributeName: aws.String("gsi1sk"), KeyType: types.KeyTypeRange},
            },
            Projection: &types.Projection{ProjectionType: types.ProjectionTypeAll},
        }},
    })
    if err != nil { return err }
    return dynamodb.NewTableExistsWaiter(client).Wait(ctx,
        &dynamodb.DescribeTableInput{TableName: aws.String(tableName)},
        2*time.Minute)
}

Delete table

DeleteTable removes the whole table, including its indexes and items. The waiter completes when the table no longer exists. Do not run this as part of ordinary application startup.

func deleteTable(ctx context.Context, client *dynamodb.Client) error {
    _, err := client.DeleteTable(ctx, &dynamodb.DeleteTableInput{
        TableName: aws.String(tableName),
    })
    if err != nil { return err }
    return dynamodb.NewTableNotExistsWaiter(client).Wait(ctx,
        &dynamodb.DescribeTableInput{TableName: aws.String(tableName)},
        2*time.Minute)
}
func deleteTable(ctx context.Context, client *dynamodb.Client) error {
    _, err := client.DeleteTable(ctx, &dynamodb.DeleteTableInput{
        TableName: aws.String(tableName),
    })
    if err != nil { return err }
    return dynamodb.NewTableNotExistsWaiter(client).Wait(ctx,
        &dynamodb.DescribeTableInput{TableName: aws.String(tableName)},
        2*time.Minute)
}

List tables

List tables in the client's account and Region. Use the list paginator instead of assuming that one response contains every name.

func listTables(ctx context.Context, client *dynamodb.Client) error {
    pages := dynamodb.NewListTablesPaginator(client, &dynamodb.ListTablesInput{})
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        for _, name := range page.TableNames { fmt.Println(name) }
    }
    return nil
}
func listTables(ctx context.Context, client *dynamodb.Client) error {
    pages := dynamodb.NewListTablesPaginator(client, &dynamodb.ListTablesInput{})
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        for _, name := range page.TableNames { fmt.Println(name) }
    }
    return nil
}

Get all items / Scan in DynamoDB

A Scan evaluates every item in the table or index. Process one page at a time to keep memory bounded. UnmarshalListOfMaps decodes a page into typed Go values, using the dynamodbav struct tags.

func scanItems(ctx context.Context, client *dynamodb.Client) error {
    pages := dynamodb.NewScanPaginator(client, &dynamodb.ScanInput{
        TableName: aws.String(tableName),
    })
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        var items []Item
        if err := attributevalue.UnmarshalListOfMaps(page.Items, &items); err != nil {
            return err
        }
        for _, item := range items { fmt.Println(item) }
    }
    return nil
}
func scanItems(ctx context.Context, client *dynamodb.Client) error {
    pages := dynamodb.NewScanPaginator(client, &dynamodb.ScanInput{
        TableName: aws.String(tableName),
    })
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        var items []Item
        if err := attributevalue.UnmarshalListOfMaps(page.Items, &items); err != nil {
            return err
        }
        for _, item := range items { fmt.Println(item) }
    }
    return nil
}

A filter reduces returned results after DynamoDB reads the items. It does not reduce the read capacity for those items. Here are equivalent manual and builder-based filters for items without deletedAt whose firstName contains John. Both return inputs for NewScanPaginator:

func manualScanInput() *dynamodb.ScanInput {
    return &dynamodb.ScanInput{
        TableName: aws.String(tableName),
        FilterExpression: aws.String("attribute_not_exists(#deleted) AND contains(#name, :name)"),
        ExpressionAttributeNames: map[string]string{
            "#deleted": "deletedAt", "#name": "firstName",
        },
        ExpressionAttributeValues: map[string]types.AttributeValue{
            ":name": &types.AttributeValueMemberS{Value: "John"},
        },
    }
}

func filteredScanInput() (*dynamodb.ScanInput, error) {
    filter := expression.Name("deletedAt").AttributeNotExists().And(
        expression.Name("firstName").Contains("John"))
    expr, err := expression.NewBuilder().WithFilter(filter).Build()
    if err != nil { return nil, err }
    return &dynamodb.ScanInput{
        TableName: aws.String(tableName),
        FilterExpression: expr.Filter(),
        ExpressionAttributeNames: expr.Names(),
        ExpressionAttributeValues: expr.Values(),
    }, nil
}
func manualScanInput() *dynamodb.ScanInput {
    return &dynamodb.ScanInput{
        TableName: aws.String(tableName),
        FilterExpression: aws.String("attribute_not_exists(#deleted) AND contains(#name, :name)"),
        ExpressionAttributeNames: map[string]string{
            "#deleted": "deletedAt", "#name": "firstName",
        },
        ExpressionAttributeValues: map[string]types.AttributeValue{
            ":name": &types.AttributeValueMemberS{Value: "John"},
        },
    }
}

func filteredScanInput() (*dynamodb.ScanInput, error) {
    filter := expression.Name("deletedAt").AttributeNotExists().And(
        expression.Name("firstName").Contains("John"))
    expr, err := expression.NewBuilder().WithFilter(filter).Build()
    if err != nil { return nil, err }
    return &dynamodb.ScanInput{
        TableName: aws.String(tableName),
        FilterExpression: expr.Filter(),
        ExpressionAttributeNames: expr.Names(),
        ExpressionAttributeValues: expr.Values(),
    }, nil
}

Use either input instead of the unfiltered ScanInput in scanItems. Continue even when a filtered page is empty. The paginator, not the number of returned items, determines when the scan is finished.

Dynobase's query workspace lets you inspect filters and save parameterized queries before putting them into application code.

The screenshot shows the Dynobase 3.0 query workspace with demo data. The Go SDK v2 examples above are the application-code reference.

Get item

Get an item by its complete primary key. ConsistentRead requests a strongly consistent base-table read. A missing item is a successful response with an empty Item, not a ResourceNotFoundException.

func getItem(ctx context.Context, client *dynamodb.Client) (*Item, error) {
    out, err := client.GetItem(ctx, &dynamodb.GetItemInput{
        TableName: aws.String(tableName),
        Key: itemKey("123", 20261023),
        ConsistentRead: aws.Bool(true),
    })
    if err != nil { return nil, err }
    if len(out.Item) == 0 { return nil, nil }
    var item Item
    if err := attributevalue.UnmarshalMap(out.Item, &item); err != nil {
        return nil, err
    }
    return &item, nil
}
func getItem(ctx context.Context, client *dynamodb.Client) (*Item, error) {
    out, err := client.GetItem(ctx, &dynamodb.GetItemInput{
        TableName: aws.String(tableName),
        Key: itemKey("123", 20261023),
        ConsistentRead: aws.Bool(true),
    })
    if err != nil { return nil, err }
    if len(out.Item) == 0 { return nil, nil }
    var item Item
    if err := attributevalue.UnmarshalMap(out.Item, &item); err != nil {
        return nil, err
    }
    return &item, nil
}

For a struct-based key, attributevalue.MarshalMap is equivalent to itemKey. Marshal only the key fields, not the full item:

func marshaledKey() (map[string]types.AttributeValue, error) {
    return attributevalue.MarshalMap(struct {
        ID string `dynamodbav:"id"`
        Date int `dynamodbav:"date"`
    }{ID: "123", Date: 20261023})
}
func marshaledKey() (map[string]types.AttributeValue, error) {
    return attributevalue.MarshalMap(struct {
        ID string `dynamodbav:"id"`
        Date int `dynamodbav:"date"`
    }{ID: "123", Date: 20261023})
}

Batch get item

BatchGetItem retrieves known keys, including keys from multiple tables. It accepts up to 100 items and a 16 MB response. Do not repeat a key in one batch. Results are unordered; missing items are omitted.

A successful response can still contain UnprocessedKeys. Retry only those keys with bounded exponential backoff and jitter. This helper also supports the batch-write example. The retry count and delay are example application choices.

func backoff(ctx context.Context, attempt int) error {
    capDelay := 50 * time.Millisecond * time.Duration(1<<min(attempt, 6))
    timer := time.NewTimer(time.Duration(rand.Int64N(int64(capDelay))))
    defer timer.Stop()
    select {
    case <-ctx.Done(): return ctx.Err()
    case <-timer.C: return nil
    }
}

func batchGet(ctx context.Context, client *dynamodb.Client) ([]Item, error) {
    pending := map[string]types.KeysAndAttributes{
        tableName: {Keys: []map[string]types.AttributeValue{
            itemKey("123", 20261023), itemKey("234", 20261023),
        }},
    }
    var items []Item
    for attempt := 0; len(pending) > 0; attempt++ {
        if attempt == 8 { return items, fmt.Errorf("batch get incomplete: %v", pending) }
        if attempt > 0 {
            if err := backoff(ctx, attempt-1); err != nil { return items, err }
        }
        out, err := client.BatchGetItem(ctx, &dynamodb.BatchGetItemInput{RequestItems: pending})
        if err != nil { return items, err }
        var batch []Item
        if err := attributevalue.UnmarshalListOfMaps(out.Responses[tableName], &batch); err != nil {
            return items, err
        }
        items = append(items, batch...)
        pending = out.UnprocessedKeys
    }
    return items, nil
}
func backoff(ctx context.Context, attempt int) error {
    capDelay := 50 * time.Millisecond * time.Duration(1<<min(attempt, 6))
    timer := time.NewTimer(time.Duration(rand.Int64N(int64(capDelay))))
    defer timer.Stop()
    select {
    case <-ctx.Done(): return ctx.Err()
    case <-timer.C: return nil
    }
}

func batchGet(ctx context.Context, client *dynamodb.Client) ([]Item, error) {
    pending := map[string]types.KeysAndAttributes{
        tableName: {Keys: []map[string]types.AttributeValue{
            itemKey("123", 20261023), itemKey("234", 20261023),
        }},
    }
    var items []Item
    for attempt := 0; len(pending) > 0; attempt++ {
        if attempt == 8 { return items, fmt.Errorf("batch get incomplete: %v", pending) }
        if attempt > 0 {
            if err := backoff(ctx, attempt-1); err != nil { return items, err }
        }
        out, err := client.BatchGetItem(ctx, &dynamodb.BatchGetItemInput{RequestItems: pending})
        if err != nil { return items, err }
        var batch []Item
        if err := attributevalue.UnmarshalListOfMaps(out.Responses[tableName], &batch); err != nil {
            return items, err
        }
        items = append(items, batch...)
        pending = out.UnprocessedKeys
    }
    return items, nil
}

Put item

PutItem replaces an existing item with the same complete key. Here MarshalMap encodes the struct, including the GSI attributes. Add ConditionExpression: aws.String("attribute_not_exists(id)") if overwriting that item should fail.

func putItem(ctx context.Context, client *dynamodb.Client) error {
    item, err := attributevalue.MarshalMap(Item{
        ID: "123", Date: 20261023, FirstName: "John", Company: "Apple",
        Score: 0, GSI1PK: "company#Apple", GSI1SK: 20261023,
    })
    if err != nil { return err }
    _, err = client.PutItem(ctx, &dynamodb.PutItemInput{
        TableName: aws.String(tableName), Item: item,
    })
    return err
}
func putItem(ctx context.Context, client *dynamodb.Client) error {
    item, err := attributevalue.MarshalMap(Item{
        ID: "123", Date: 20261023, FirstName: "John", Company: "Apple",
        Score: 0, GSI1PK: "company#Apple", GSI1SK: 20261023,
    })
    if err != nil { return err }
    _, err = client.PutItem(ctx, &dynamodb.PutItemInput{
        TableName: aws.String(tableName), Item: item,
    })
    return err
}

Batch write / put item

A batch accepts up to 25 puts or deletes and a 16 MB request. It does not support partial updates or per-item conditions, and the batch is not atomic. A put replaces the complete item. Retry UnprocessedItems even when the SDK returns no error.

func writeBatch(ctx context.Context, client *dynamodb.Client,
    pending map[string][]types.WriteRequest) error {
    for attempt := 0; len(pending) > 0; attempt++ {
        if attempt == 8 { return fmt.Errorf("batch write incomplete: %v", pending) }
        if attempt > 0 {
            if err := backoff(ctx, attempt-1); err != nil { return err }
        }
        out, err := client.BatchWriteItem(ctx, &dynamodb.BatchWriteItemInput{RequestItems: pending})
        if err != nil { return err }
        pending = out.UnprocessedItems
    }
    return nil
}

func batchWrite(ctx context.Context, client *dynamodb.Client) error {
    item, err := attributevalue.MarshalMap(Item{
        ID: "234", Date: 20261023, FirstName: "Jane", Company: "Apple",
    })
    if err != nil { return err }
    return writeBatch(ctx, client, map[string][]types.WriteRequest{
        tableName: {
            {DeleteRequest: &types.DeleteRequest{Key: itemKey("123", 20261023)}},
            {PutRequest: &types.PutRequest{Item: item}},
        },
    })
}
func writeBatch(ctx context.Context, client *dynamodb.Client,
    pending map[string][]types.WriteRequest) error {
    for attempt := 0; len(pending) > 0; attempt++ {
        if attempt == 8 { return fmt.Errorf("batch write incomplete: %v", pending) }
        if attempt > 0 {
            if err := backoff(ctx, attempt-1); err != nil { return err }
        }
        out, err := client.BatchWriteItem(ctx, &dynamodb.BatchWriteItemInput{RequestItems: pending})
        if err != nil { return err }
        pending = out.UnprocessedItems
    }
    return nil
}

func batchWrite(ctx context.Context, client *dynamodb.Client) error {
    item, err := attributevalue.MarshalMap(Item{
        ID: "234", Date: 20261023, FirstName: "Jane", Company: "Apple",
    })
    if err != nil { return err }
    return writeBatch(ctx, client, map[string][]types.WriteRequest{
        tableName: {
            {DeleteRequest: &types.DeleteRequest{Key: itemKey("123", 20261023)}},
            {PutRequest: &types.PutRequest{Item: item}},
        },
    })
}

For multiple tables, add another table-name entry to RequestItems and keep the operation total within the batch limit. If retries are exhausted, retain the outstanding requests for recovery. Do not log sensitive item contents in production.

Query for a set of items

A Query needs equality on the partition key and can add a sort-key condition. This example reads dates after a lower bound for one id. The expression builder creates aliases and typed values together; pass all three expression fields to the request.

func queryInput(id string, after int) (*dynamodb.QueryInput, error) {
    condition := expression.Key("id").Equal(expression.Value(id)).And(
        expression.Key("date").GreaterThan(expression.Value(after)))
    expr, err := expression.NewBuilder().WithKeyCondition(condition).Build()
    if err != nil { return nil, err }
    return &dynamodb.QueryInput{
        TableName: aws.String(tableName),
        KeyConditionExpression: expr.KeyCondition(),
        ExpressionAttributeNames: expr.Names(),
        ExpressionAttributeValues: expr.Values(),
    }, nil
}

func queryItems(ctx context.Context, client *dynamodb.Client) error {
    input, err := queryInput("123", 20261001)
    if err != nil { return err }
    pages := dynamodb.NewQueryPaginator(client, input)
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        var items []Item
        if err := attributevalue.UnmarshalListOfMaps(page.Items, &items); err != nil {
            return err
        }
        for _, item := range items { fmt.Println(item) }
    }
    return nil
}
func queryInput(id string, after int) (*dynamodb.QueryInput, error) {
    condition := expression.Key("id").Equal(expression.Value(id)).And(
        expression.Key("date").GreaterThan(expression.Value(after)))
    expr, err := expression.NewBuilder().WithKeyCondition(condition).Build()
    if err != nil { return nil, err }
    return &dynamodb.QueryInput{
        TableName: aws.String(tableName),
        KeyConditionExpression: expr.KeyCondition(),
        ExpressionAttributeNames: expr.Names(),
        ExpressionAttributeValues: expr.Values(),
    }, nil
}

func queryItems(ctx context.Context, client *dynamodb.Client) error {
    input, err := queryInput("123", 20261001)
    if err != nil { return err }
    pages := dynamodb.NewQueryPaginator(client, input)
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        var items []Item
        if err := attributevalue.UnmarshalListOfMaps(page.Items, &items); err != nil {
            return err
        }
        for _, item := range items { fmt.Println(item) }
    }
    return nil
}

Use a filter only for non-key conditions after the key selection. A Query filter cannot contain the queried partition or sort key. The Query vs. Scan comparison explains why a key-based access pattern usually reads less data.

Query an index

Set IndexName and use the index's key attributes. This GSI query finds company records by date, independently of the base-table id. It uses the same paginator as a table query. GSIs support eventual consistency only; do not set ConsistentRead to true.

func queryIndex(ctx context.Context, client *dynamodb.Client) error {
    pages := dynamodb.NewQueryPaginator(client, &dynamodb.QueryInput{
        TableName: aws.String(tableName), IndexName: aws.String("GSI1"),
        KeyConditionExpression: aws.String("#pk = :pk AND #sk > :date"),
        ExpressionAttributeNames: map[string]string{"#pk": "gsi1pk", "#sk": "gsi1sk"},
        ExpressionAttributeValues: map[string]types.AttributeValue{
            ":pk": &types.AttributeValueMemberS{Value: "company#Apple"},
            ":date": &types.AttributeValueMemberN{Value: "20261001"},
        },
    })
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        fmt.Println(page.Items)
    }
    return nil
}
func queryIndex(ctx context.Context, client *dynamodb.Client) error {
    pages := dynamodb.NewQueryPaginator(client, &dynamodb.QueryInput{
        TableName: aws.String(tableName), IndexName: aws.String("GSI1"),
        KeyConditionExpression: aws.String("#pk = :pk AND #sk > :date"),
        ExpressionAttributeNames: map[string]string{"#pk": "gsi1pk", "#sk": "gsi1sk"},
        ExpressionAttributeValues: map[string]types.AttributeValue{
            ":pk": &types.AttributeValueMemberS{Value: "company#Apple"},
            ":date": &types.AttributeValueMemberN{Value: "20261001"},
        },
    })
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        fmt.Println(page.Items)
    }
    return nil
}

A GSI query returns only projected attributes. This example's index projects all attributes. A local secondary index uses the table's partition key and a different sort key; specify its name in the same way, but construct the condition for that index's schema.

Simple transaction

Transactions make several writes succeed or fail together. The following cart example uses two items in my-table: an existing stock item with key stock#123 / 0 and a unique cart entry with key cart#456#product#123 / 20261023. Seed the stock item's Number count before calling it. The stock condition prevents decrementing below zero; the cart condition prevents reserving the same cart entry twice.

func reserveStock(ctx context.Context, client *dynamodb.Client, token string) error {
    cart := itemKey("cart#456#product#123", 20261023)
    cart["count"] = &types.AttributeValueMemberN{Value: "1"}
    _, err := client.TransactWriteItems(ctx, &dynamodb.TransactWriteItemsInput{
        ClientRequestToken: aws.String(token),
        TransactItems: []types.TransactWriteItem{
            {Put: &types.Put{
                TableName: aws.String(tableName), Item: cart,
                ConditionExpression: aws.String("attribute_not_exists(id)"),
            }},
            {Update: &types.Update{
                TableName: aws.String(tableName), Key: itemKey("stock#123", 0),
                UpdateExpression: aws.String("SET #count = #count - :one"),
                ConditionExpression: aws.String("#count >= :one"),
                ExpressionAttributeNames: map[string]string{"#count": "count"},
                ExpressionAttributeValues: map[string]types.AttributeValue{
                    ":one": &types.AttributeValueMemberN{Value: "1"},
                },
            }},
        },
    })
    return err
}
func reserveStock(ctx context.Context, client *dynamodb.Client, token string) error {
    cart := itemKey("cart#456#product#123", 20261023)
    cart["count"] = &types.AttributeValueMemberN{Value: "1"}
    _, err := client.TransactWriteItems(ctx, &dynamodb.TransactWriteItemsInput{
        ClientRequestToken: aws.String(token),
        TransactItems: []types.TransactWriteItem{
            {Put: &types.Put{
                TableName: aws.String(tableName), Item: cart,
                ConditionExpression: aws.String("attribute_not_exists(id)"),
            }},
            {Update: &types.Update{
                TableName: aws.String(tableName), Key: itemKey("stock#123", 0),
                UpdateExpression: aws.String("SET #count = #count - :one"),
                ConditionExpression: aws.String("#count >= :one"),
                ExpressionAttributeNames: map[string]string{"#count": "count"},
                ExpressionAttributeValues: map[string]types.AttributeValue{
                    ":one": &types.AttributeValueMemberN{Value: "1"},
                },
            }},
        },
    })
    return err
}

Supply a unique request token for each logical reservation and reuse it only for retries of the identical transaction. Transactions support up to 100 unique items and 4 MB in one account and Region, with at most one action on each item. They are unavailable on MRSC global tables. The token's idempotency window is 10 minutes after the request completes.

Read transaction

TransactGetItems reads specified items as a transaction, including across tables in the same account and Region. Responses correspond to the request order. It is not a transactional Query or Scan.

func readTransaction(ctx context.Context, client *dynamodb.Client) error {
    out, err := client.TransactGetItems(ctx, &dynamodb.TransactGetItemsInput{
        TransactItems: []types.TransactGetItem{
            {Get: &types.Get{TableName: aws.String(tableName), Key: itemKey("123", 20261023)}},
            {Get: &types.Get{TableName: aws.String(tableName), Key: itemKey("234", 20261023)}},
        },
    })
    if err != nil { return err }
    for _, response := range out.Responses { fmt.Println(response.Item) }
    return nil
}
func readTransaction(ctx context.Context, client *dynamodb.Client) error {
    out, err := client.TransactGetItems(ctx, &dynamodb.TransactGetItemsInput{
        TransactItems: []types.TransactGetItem{
            {Get: &types.Get{TableName: aws.String(tableName), Key: itemKey("123", 20261023)}},
            {Get: &types.Get{TableName: aws.String(tableName), Key: itemKey("234", 20261023)}},
        },
    })
    if err != nil { return err }
    for _, response := range out.Responses { fmt.Println(response.Item) }
    return nil
}

Query with sorting

Query results are ordered by the queried sort key. Numbers sort numerically; strings sort by UTF-8 bytes. ScanIndexForward: false reverses the order. A Scan has no sort-order guarantee; a different sort attribute needs an index or application-side sorting.

func descendingQueryInput() (*dynamodb.QueryInput, error) {
    input, err := queryInput("123", 20261001)
    if err != nil { return nil, err }
    input.ScanIndexForward = aws.Bool(false)
    return input, nil
}
func descendingQueryInput() (*dynamodb.QueryInput, error) {
    input, err := queryInput("123", 20261001)
    if err != nil { return nil, err }
    input.ScanIndexForward = aws.Bool(false)
    return input, nil
}

Query and Scan pagination

Query and Scan evaluate up to 1 MB per service call before applying filters. Limit also counts evaluated items, not matching results. The paginators above keep requesting pages automatically; a limit on the input is a per-call limit, not a total limit across the paginator.

For a user-facing page, make one call and return its LastEvaluatedKey as a cursor. Pass the complete key map back as ExclusiveStartKey, including index-key components for index queries. Validate that a cursor belongs to the same authorized query before using it. See DynamoDB pagination for cursor semantics.

func queryPage(ctx context.Context, client *dynamodb.Client,
    cursor map[string]types.AttributeValue) (*dynamodb.QueryOutput, error) {
    input, err := queryInput("123", 20261001)
    if err != nil { return nil, err }
    input.Limit = aws.Int32(25)
    input.ExclusiveStartKey = cursor
    return client.Query(ctx, input)
}
func queryPage(ctx context.Context, client *dynamodb.Client,
    cursor map[string]types.AttributeValue) (*dynamodb.QueryOutput, error) {
    input, err := queryInput("123", 20261001)
    if err != nil { return nil, err }
    input.Limit = aws.Int32(25)
    input.ExclusiveStartKey = cursor
    return client.Query(ctx, input)
}

Update item

UpdateItem changes selected attributes and can create an item if its key is absent. Use ReturnValuesAllNew when you need the resulting attributes; without it, Attributes is normally empty. Alias attribute names to avoid reserved-word conflicts.

func updateItem(ctx context.Context, client *dynamodb.Client) error {
    out, err := client.UpdateItem(ctx, &dynamodb.UpdateItemInput{
        TableName: aws.String(tableName), Key: itemKey("123", 20261023),
        UpdateExpression: aws.String("SET #name = :name"),
        ExpressionAttributeNames: map[string]string{"#name": "firstName"},
        ExpressionAttributeValues: map[string]types.AttributeValue{
            ":name": &types.AttributeValueMemberS{Value: "John McNewname"},
        },
        ReturnValues: types.ReturnValueAllNew,
    })
    if err != nil { return err }
    fmt.Println(out.Attributes)
    return nil
}
func updateItem(ctx context.Context, client *dynamodb.Client) error {
    out, err := client.UpdateItem(ctx, &dynamodb.UpdateItemInput{
        TableName: aws.String(tableName), Key: itemKey("123", 20261023),
        UpdateExpression: aws.String("SET #name = :name"),
        ExpressionAttributeNames: map[string]string{"#name": "firstName"},
        ExpressionAttributeValues: map[string]types.AttributeValue{
            ":name": &types.AttributeValueMemberS{Value: "John McNewname"},
        },
        ReturnValues: types.ReturnValueAllNew,
    })
    if err != nil { return err }
    fmt.Println(out.Attributes)
    return nil
}

Conditionally update item

A conditional write checks the current item atomically with the update. This changes the name only if the item belongs to Apple and has no deletedAt. Build the update and condition together so their generated aliases do not collide.

func conditionalUpdate(ctx context.Context, client *dynamodb.Client) error {
    condition := expression.Name("deletedAt").AttributeNotExists().And(
        expression.Name("company").Equal(expression.Value("Apple")))
    expr, err := expression.NewBuilder().
        WithUpdate(expression.Set(expression.Name("firstName"), expression.Value("John McNewname"))).
        WithCondition(condition).Build()
    if err != nil { return err }
    _, err = client.UpdateItem(ctx, &dynamodb.UpdateItemInput{
        TableName: aws.String(tableName), Key: itemKey("123", 20261023),
        UpdateExpression: expr.Update(), ConditionExpression: expr.Condition(),
        ExpressionAttributeNames: expr.Names(), ExpressionAttributeValues: expr.Values(),
    })
    return err
}
func conditionalUpdate(ctx context.Context, client *dynamodb.Client) error {
    condition := expression.Name("deletedAt").AttributeNotExists().And(
        expression.Name("company").Equal(expression.Value("Apple")))
    expr, err := expression.NewBuilder().
        WithUpdate(expression.Set(expression.Name("firstName"), expression.Value("John McNewname"))).
        WithCondition(condition).Build()
    if err != nil { return err }
    _, err = client.UpdateItem(ctx, &dynamodb.UpdateItemInput{
        TableName: aws.String(tableName), Key: itemKey("123", 20261023),
        UpdateExpression: expr.Update(), ConditionExpression: expr.Condition(),
        ExpressionAttributeNames: expr.Names(), ExpressionAttributeValues: expr.Values(),
    })
    return err
}

The equivalent manual condition is attribute_not_exists(#deleted) AND #company = :company, with name aliases for deletedAt and company and a String value of Apple. A failed condition is an expected application outcome, not a reason to retry the same write indefinitely.

Use the standard library's errors.As to inspect wrapped SDK errors. AWS's error-handling guide explains why a direct type assertion can miss the underlying service exception.

func describeError(err error) string {
    if err == nil { return "success" }
    var condition *types.ConditionalCheckFailedException
    var missing *types.ResourceNotFoundException
    var throttled *types.ProvisionedThroughputExceededException
    var canceled *types.TransactionCanceledException
    switch {
    case errors.As(err, &condition): return "condition did not match"
    case errors.As(err, &missing): return "table or index was not found"
    case errors.As(err, &throttled): return "capacity exceeded after SDK retries"
    case errors.As(err, &canceled): return "transaction canceled: inspect cancellation reasons"
    default: return err.Error()
    }
}
func describeError(err error) string {
    if err == nil { return "success" }
    var condition *types.ConditionalCheckFailedException
    var missing *types.ResourceNotFoundException
    var throttled *types.ProvisionedThroughputExceededException
    var canceled *types.TransactionCanceledException
    switch {
    case errors.As(err, &condition): return "condition did not match"
    case errors.As(err, &missing): return "table or index was not found"
    case errors.As(err, &throttled): return "capacity exceeded after SDK retries"
    case errors.As(err, &canceled): return "transaction canceled: inspect cancellation reasons"
    default: return err.Error()
    }
}

The SDK also models throttling errors such as types.ThrottlingException and types.RequestLimitExceeded. SDK retries do not replace handling a final failure, and successful batch responses require the separate unprocessed-item loops above.

Increment an item attribute

Use an atomic update instead of a read-modify-write cycle, which can lose concurrent changes. if_not_exists initializes a missing counter. This operation is atomic but not idempotent: retrying an uncertain application request can increment twice.

func incrementScore(ctx context.Context, client *dynamodb.Client) error {
    _, err := client.UpdateItem(ctx, &dynamodb.UpdateItemInput{
        TableName: aws.String(tableName), Key: itemKey("123", 20261023),
        UpdateExpression: aws.String("SET #score = if_not_exists(#score, :zero) + :one"),
        ExpressionAttributeNames: map[string]string{"#score": "score"},
        ExpressionAttributeValues: map[string]types.AttributeValue{
            ":zero": &types.AttributeValueMemberN{Value: "0"},
            ":one": &types.AttributeValueMemberN{Value: "1"},
        },
    })
    return err
}
func incrementScore(ctx context.Context, client *dynamodb.Client) error {
    _, err := client.UpdateItem(ctx, &dynamodb.UpdateItemInput{
        TableName: aws.String(tableName), Key: itemKey("123", 20261023),
        UpdateExpression: aws.String("SET #score = if_not_exists(#score, :zero) + :one"),
        ExpressionAttributeNames: map[string]string{"#score": "score"},
        ExpressionAttributeValues: map[string]types.AttributeValue{
            ":zero": &types.AttributeValueMemberN{Value: "0"},
            ":one": &types.AttributeValueMemberN{Value: "1"},
        },
    })
    return err
}

Delete item

Delete by the complete key. Deleting an absent item succeeds. Add a condition when deletion must depend on the current state, or request ReturnValuesAllOld to inspect the removed item.

func deleteItem(ctx context.Context, client *dynamodb.Client) error {
    _, err := client.DeleteItem(ctx, &dynamodb.DeleteItemInput{
        TableName: aws.String(tableName), Key: itemKey("123", 20261023),
    })
    return err
}
func deleteItem(ctx context.Context, client *dynamodb.Client) error {
    _, err := client.DeleteItem(ctx, &dynamodb.DeleteItemInput{
        TableName: aws.String(tableName), Key: itemKey("123", 20261023),
    })
    return err
}

Delete all items

There is no table-wide SQL-style delete. Scan the keys and delete each item, or batch those keys in groups of up to 25 with the retry helper. This sequential version keeps the schema and error handling explicit. Stop other writers first if the table must end empty: a scan is not a point-in-time snapshot, and concurrent writes can survive or be deleted unexpectedly.

func deleteAllItems(ctx context.Context, client *dynamodb.Client) error {
    pages := dynamodb.NewScanPaginator(client, &dynamodb.ScanInput{
        TableName: aws.String(tableName), ProjectionExpression: aws.String("#id, #date"),
        ExpressionAttributeNames: map[string]string{"#id": "id", "#date": "date"},
    })
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        for _, key := range page.Items {
            _, err := client.DeleteItem(ctx, &dynamodb.DeleteItemInput{
                TableName: aws.String(tableName), Key: key,
            })
            if err != nil { return err }
        }
    }
    return nil
}
func deleteAllItems(ctx context.Context, client *dynamodb.Client) error {
    pages := dynamodb.NewScanPaginator(client, &dynamodb.ScanInput{
        TableName: aws.String(tableName), ProjectionExpression: aws.String("#id, #date"),
        ExpressionAttributeNames: map[string]string{"#id": "id", "#date": "date"},
    })
    for pages.HasMorePages() {
        page, err := pages.NextPage(ctx)
        if err != nil { return err }
        for _, key := range page.Items {
            _, err := client.DeleteItem(ctx, &dynamodb.DeleteItemInput{
                TableName: aws.String(tableName), Key: key,
            })
            if err != nil { return err }
        }
    }
    return nil
}

Run DynamoDB Local

For a local DynamoDB instance, configure BaseEndpoint and dummy credentials. A local client still needs a Region for signing. These dummy values are only for local emulation. AWS's endpoint guide recommends the newer endpoint configuration instead of the legacy EndpointResolver.

func localClient(ctx context.Context) (*dynamodb.Client, error) {
    cfg, err := config.LoadDefaultConfig(ctx,
        config.WithRegion("us-east-1"),
        config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("local", "local", "")))
    if err != nil { return nil, err }
    return dynamodb.NewFromConfig(cfg, func(options *dynamodb.Options) {
        options.BaseEndpoint = aws.String("http://localhost:8000")
    }), nil
}
func localClient(ctx context.Context) (*dynamodb.Client, error) {
    cfg, err := config.LoadDefaultConfig(ctx,
        config.WithRegion("us-east-1"),
        config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("local", "local", "")))
    if err != nil { return nil, err }
    return dynamodb.NewFromConfig(cfg, func(options *dynamodb.Options) {
        options.BaseEndpoint = aws.String("http://localhost:8000")
    }), nil
}

Use the returned client with the same functions. Local emulation is useful for request shape and key-schema checks; it does not reproduce production throttling or every managed-service feature.