DynamoDB Query em Go (AWS SDK v2)

Query lê todos os itens que compartilham uma chave de partição, opcionalmente restringindo pela chave de classificação. No AWS SDK for Go v2 você escreve uma KeyConditionExpression em um dynamodb.QueryInput, e o QueryPaginator embutido segue o LastEvaluatedKey por todas as páginas de resultados por você.

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))
}

Explicação

KeyConditionExpression — deve incluir uma igualdade na chave de partição (#hashKey = :hashKeyValue) mais no máximo uma condição de chave de classificação (=, <, <=, >, >=, BETWEEN ou begins_with). Os aliases #hashKey/#rangeKey resolvem para Artist/SongTitle via ExpressionAttributeNames (seguro contra palavras reservadas).
ExpressionAttributeValues — o mapa :placeholder → valor tipado (&types.AttributeValueMemberS{...}).
Paginação — um Query retorna no máximo 1 MB. dynamodb.NewQueryPaginator envolve o client e continua chamando até o LastEvaluatedKey se esgotar; o loop HasMorePages() / NextPage(ctx) é o padrão canônico do SDK.
Defina ScanIndexForward: aws.Bool(false) para inverter a ordem da chave de classificação (crescente é o padrão).
Consulte um índice secundário adicionando IndexName: aws.String("...").
Prefere construir condições em código? O pacote expression (github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression) compõe builders expression.Key(...).Equal(...) e gera os mapas de nome/valor; attributevalue.UnmarshalListOfMaps transforma page.Items em structs Go.

Faça visualmente

O DynamoDB Expression Builder monta a key condition e copia código executável, para que você não escreva à mão os mapas de placeholder e valor.

Para executar queries contra tabelas reais numa GUI — formulário de key-condition, grade paginada, copiar como código — baixe o DynoTable.

Exemplos relacionados

DynamoDB Query em Java — a mesma query com o AWS SDK for Java 2.x.
DynamoDB Scan em Go — quando você não consegue entrar em uma partição pela chave.
Query vs. Scan — por que Query é o padrão certo.
Key condition expressions — todos os operadores válidos de chave de partição/classificação.
"Query condition missed key schema element" — a key condition nomeia o atributo errado ou pula a chave de partição.
"Query key condition not supported" — um operador que a key condition não pode usar, como contains ou uma segunda condição de chave de classificação.

References

Última verificação em 2026-07-13 contra a documentação oficial da AWS vinculada acima.