Amazon DocumentDB

Em um banco de documentos você agrupa no mesmo documento o que é lido junto (embedding) e usa referências para relações grandes, muito compartilhadas ou que crescem sem limite.

Tipos suportados: único campo, composto, multikey (arrays), TTL, sparse, parcial, unique, text, 2dsphere e vector. Índices são a principal alavanca de desempenho (e de custo de I/O).

// Índice composto criado em background (não bloqueia escritas)
db.pedidos.createIndex({ clienteId: 1, criadoEm: -1 }, { background: true })

// Listar e remover
db.pedidos.getIndexes()
db.pedidos.dropIndex("clienteId_1_criadoEm_-1")

// Reconstruir sem downtime (recupera espaço e melhora índices vindos de 3.6/4.0)
db.pedidos.reIndex()

Regras de ouro

• Seletividade: indexe campos em que cada valor aparece em no máximo ~1% dos documentos. Índices de baixa cardinalidade (booleanos, dia da semana) raramente são escolhidos pelo planner e só custam espaço e I/O.
• Quantidade: cada índice adiciona uma escrita por insert/update/delete. Como diretriz, mantenha cinco ou menos por coleção.
• Crie os índices antes de importar grandes volumes (a ferramenta index-tool do repositório amazon-documentdb-tools extrai e recria índices).
• Revise periodicamente índices não usados ($indexStats) e consultas sem índice (profiler).

Um índice TTL remove documentos automaticamente após um intervalo. A remoção é feita por um processo em background (ttl_monitor) e é best effort: não há garantia de quando o documento será apagado.

// Expira sessões 24h depois de criadoEm
db.sessoes.createIndex({ criadoEm: 1 }, { expireAfterSeconds: 86400 })

O DocumentDB suporta os principais estágios e operadores de aggregation; a lista cresce a cada versão (veja as listas de novidades da 4.0, 5.0 e 8.0). O limite é de 500 estágios por pipeline.

db.pedidos.aggregate([
  { $match: { status: "PAGO", criadoEm: { $gte: ISODate("2026-01-01") } } },  // primeiro: reduz o volume
  { $group: { _id: "$clienteId", total: { $sum: "$valor" } } },
  { $sort: { total: -1 } },
  { $limit: 10 }
])

• Coloque $match (e $limit quando possível) no início do pipeline para que as etapas seguintes processem menos documentos.
• Na 4.0+, $lookup consegue usar índice; garanta índice no campo de junção da coleção "from".
• Na 8.0, o planner v3 otimiza pipelines (pull-up de $match, coalescência de $lookup/$unwind); valide com explain depois do upgrade.
• Antes de migrar, rode a compat-tool do amazon-documentdb-tools para achar operadores não suportados.

A partir da 4.0 é possível executar transações ACID envolvendo vários documentos, instruções, coleções e bancos. O número de transações abertas é limitado por instância (por exemplo, 200 em uma large e 400 em uma xlarge).

const s = db.getMongo().startSession();
s.startTransaction();
try {
  const dbs = s.getDatabase("loja");
  dbs.contas.updateOne({ _id: 1 }, { $inc: { saldo: -100 } });
  dbs.contas.updateOne({ _id: 2 }, { $inc: { saldo: 100 } });
  s.commitTransaction();
} catch (e) {
  s.abortTransaction();
  throw e;
} finally {
  s.endSession();
}

Change streams entregam a sequência ordenada de eventos de uma coleção, banco ou cluster. São desabilitados por padrão e precisam ser habilitados por coleção (ou banco, ou cluster).

// Habilitar para uma coleção
db.adminCommand({ modifyChangeStreams: 1, database: "loja", collection: "pedidos", enable: true })

// Habilitar para todas as coleções de um banco
db.adminCommand({ modifyChangeStreams: 1, database: "loja", collection: "", enable: true })

// Consumir
const cur = db.getSiblingDB("loja").pedidos.watch([], { fullDocument: "updateLookup" })
while (cur.hasNext()) printjson(cur.next())

• Retenção: 3 horas por padrão, ajustável de 1 hora a 7 dias com o parâmetro change_stream_log_retention_duration.
• Réplicas: na 5.0+ é possível ler change streams de instâncias secundárias (use read preference secondary).
• Eventos grandes: eventos acima de 16 MB falham na leitura; na 8.0.2+ use $changeStreamSplitLargeEvent.
• Custo: o recurso gera I/O de leitura e escrita e armazenamento (ChangeStreamLogSize). Desligue se não usa.
• Para retomar, guarde o resumeToken ou o postBatchResumeToken.

Text index oferece busca de texto completa dentro do próprio cluster; na 8.0 existe o text index v2, com mais tokens. Vector search (5.0+) permite armazenar embeddings e buscar por similaridade para RAG, recomendação e busca semântica.

// Índice vetorial HNSW (até 2.000 dimensões indexadas)
db.produtos.createIndex(
  { embedding: "vector" },
  { name: "idx_embedding", vectorOptions: { type: "hnsw", dimensions: 1536, similarity: "cosine", m: 16, efConstruction: 64 } }
)

// Consulta clássica (5.0+)
db.produtos.aggregate([{ $search: { vectorSearch: { vector: consulta, path: "embedding", similarity: "cosine", k: 5, efSearch: 40 } } }])

// Operador $vectorSearch (8.0+)
db.produtos.aggregate([{ $vectorSearch: { index: "idx_embedding", path: "embedding", queryVector: consulta, limit: 5, numCandidates: 40, exact: false } }])

• HNSW é o indicado para a maioria dos casos (sem etapa de treinamento, melhor recall); IVFFlat usa lists e probes.
• Sem índice o DocumentDB faz busca exata (recall perfeito, mas lenta). Até 16.000 dimensões podem ser armazenadas sem índice.
• Ajuste efSearch (HNSW) ou probes (IVFFlat): valores maiores melhoram o recall e custam latência.
• Índices vetoriais não combinam com compound, sparse ou partial.

O DocumentDB faz backup contínuo e incremental do volume do cluster para um bucket S3 gerenciado pela AWS, sem impacto de desempenho e sem janela de bloqueio. Sobre esse mecanismo existem quatro formas de ter uma cópia dos seus dados:

Além do snapshot diário, o serviço registra continuamente as mudanças do volume durante todo o período de retenção. A combinação "snapshot completo mais registro incremental" é o que permite parar em qualquer segundo.

dia 1         dia 2         dia 3        ...      hoje
  |-- snapshot --|-- snapshot --|-- snapshot --|~~~ registro contínuo ~~~> (últimos ~5 min não restauráveis)
  <-------------- janela restaurável (retenção: 1 a 35 dias) ------------------->

Restore para 2026-10-12T14:55:00Z:  snapshot mais próximo anterior + replay das mudanças até 14:55:00

• Sem impacto no cluster: o backup contínuo roda na camada de armazenamento e não consome CPU nem I/O das suas instâncias.
• Atraso final: o último instante restaurável fica alguns minutos atrás do relógio (LatestRestorableTime); não dá para restaurar "agora" exato.
• Fora da retenção não há PITR: se o erro foi descoberto depois do vencimento, só restam snapshots manuais ou cópias.
• Exclusão do cluster apaga o contínuo: sem snapshot final ou manual, não há como restaurar depois que o cluster é apagado.
• Cópia entre versões: restaurar para outra versão major não é suportado (3.6 para 4.0, por exemplo); mudança de versão é migração ou upgrade in-place.

• Retenção: de 1 a 35 dias (um cluster novo começa com 1). Alinhe ao seu RPO e ao tempo que leva para descobrir um erro.
• Janela de backup: horário do dia em que os snapshots automáticos são criados; escolha um horário de menor carga.
• Nomes: snapshots automáticos seguem o padrão rds:NOME_DO_CLUSTER-aaaa-mm-dd-hh-mm.
• Exclusão: não é possível apagar um snapshot automático manualmente; eles somem com o cluster ou ao vencer a retenção.
• Janela restaurável: o intervalo entre EarliestRestorableTime e LatestRestorableTime do cluster.

# Ajustar a retenção e a janela de backup
aws docdb modify-db-cluster --db-cluster-identifier meu-cluster \
  --backup-retention-period 14 --preferred-backup-window 03:00-03:30 --apply-immediately

# Ver até onde é possível restaurar (UTC)
aws docdb describe-db-clusters --db-cluster-identifier meu-cluster \
  --query "DBClusters[0].[BackupRetentionPeriod,PreferredBackupWindow,EarliestRestorableTime,LatestRestorableTime]" --output table

Regras da janela de backup

• Se você não definir, o serviço atribui uma janela de 30 minutos escolhida ao acaso dentro de um bloco de 8 horas da região.
• Se o snapshot precisar de mais tempo que a janela, o processo continua até terminar.
• A janela de backup não pode se sobrepor à janela de manutenção semanal do cluster.
• O cluster precisa estar no estado available para o snapshot automático ser tirado; ele também não é tirado enquanto uma cópia de snapshot do mesmo cluster está em andamento na região.

O PITR cria um novo cluster com os dados exatamente como estavam no instante escolhido, dentro do período de retenção. Nunca restaura "por cima" do cluster original: ele continua intacto, o que permite comparar e recuperar dados com segurança.

Pelo console

1. Console do DocumentDB > Clusters > selecione o cluster.
2. Actions > Restore to point in time.
3. Escolha a data e a hora (entre o earliest e o latest restore time).
4. Defina identificador do cluster, classe e número de instâncias, tipo de armazenamento.
5. Em Show advanced settings, ajuste rede, porta, exportação de logs, tags e deletion protection.
6. Create cluster e aguarde o status available.

Pela CLI

# Para o último instante restaurável
aws docdb restore-db-cluster-to-point-in-time \
  --db-cluster-identifier meu-cluster-pitr \
  --source-db-cluster-identifier meu-cluster \
  --use-latest-restorable-time

# Para um instante específico (UTC)
aws docdb restore-db-cluster-to-point-in-time \
  --db-cluster-identifier meu-cluster-pitr \
  --source-db-cluster-identifier meu-cluster \
  --restore-to-time 2026-10-12T14:55:00Z

# Aguardar o cluster ficar disponível
until [ "$(aws docdb describe-db-clusters --db-cluster-identifier meu-cluster-pitr \
  --query 'DBClusters[0].Status' --output text)" = "available" ]; do sleep 30; done

# Criar as instâncias do cluster restaurado
aws docdb create-db-instance --db-instance-identifier meu-cluster-pitr-1 \
  --db-instance-class db.r6g.large --engine docdb \
  --db-cluster-identifier meu-cluster-pitr

Checklist depois do restore

• Associar o parameter group correto ao novo cluster (ele vem com o padrão) e reiniciar se houver parâmetros estáticos (por exemplo tls).
• Conferir security groups, subnet group, criptografia e deletion protection.
• Reativar exportação de logs de auditoria e profiler, e o Performance Insights nas instâncias.
• Validar os dados (contagens, amostras e índices) antes de redirecionar a aplicação.
• Ajustar a retenção de backup do novo cluster e criar alarmes (o cluster novo não herda os alarmes do CloudWatch).
• Recriar usuários e permissões só se o instante restaurado for anterior à criação deles.

• A restauração sempre cria um cluster novo; não é possível restaurar sobre um cluster existente.
• Pela CLI, só o cluster é criado: crie ao menos uma instância depois que ele estiver available.
• Snapshot criptografado exige acesso à chave KMS e só pode virar cluster criptografado. Um snapshot sem criptografia pode ser restaurado para um cluster criptografado informando --kms-key-id.
• Snapshot compartilhado: pela CLI/API informe o ARN do snapshot como identificador.
• O cluster restaurado recebe o parameter group padrão e as configurações de rede que você indicar.

aws docdb restore-db-cluster-from-snapshot \
  --db-cluster-identifier meu-cluster-restaurado \
  --snapshot-identifier meu-cluster-pre-deploy-20261013 \
  --engine docdb \
  --db-subnet-group-name meu-subnet-group \
  --vpc-security-group-ids sg-0abc123 \
  --storage-type standard

# Depois que o cluster estiver available
aws docdb create-db-instance --db-instance-identifier meu-cluster-restaurado-1 \
  --db-instance-class db.r6g.large --engine docdb --db-cluster-identifier meu-cluster-restaurado

O clone é um novo cluster que aponta para as mesmas páginas de armazenamento do original. Nenhum dado é copiado na criação: só quando o original ou o clone alteram uma página é que ela passa a existir em duas versões (copy-on-write). Por isso o clone é rápido e barato em comparação com restaurar um snapshot.

aws docdb restore-db-cluster-to-point-in-time \
  --source-db-cluster-identifier meu-cluster \
  --db-cluster-identifier meu-cluster-clone \
  --restore-type copy-on-write \
  --use-latest-restorable-time

# Quando o clone estiver available, crie a instância (pode ser menor que a de produção)
aws docdb create-db-instance --db-instance-identifier meu-cluster-clone-1 \
  --db-instance-class db.r6g.large --engine docdb \
  --db-cluster-identifier meu-cluster-clone

• Bons usos: testar upgrade de versão e mudança de parameter group, ensaiar migração de dados, rodar relatórios pesados ou exportações sem tocar a produção, criar ambientes de teste com dados reais.
• Não é backup: o clone compartilha o volume; ele não protege contra exclusão lógica já replicada nem contra perda do cluster inteiro. Use snapshots e PITR para recuperação.
• Dados reais: um clone de produção contém dados reais; aplique as mesmas regras de acesso, criptografia e mascaramento se o destino for desenvolvimento.
• Limpeza: apague clones quando terminar; o custo de instância continua enquanto existirem.

A matriz abaixo compara todas as formas de ter uma cópia dos dados. "Indicado" é o uso natural da técnica; "Possível" funciona com ressalvas; "Evite" é uma má escolha para aquele critério.

Quando evitar cada técnica

Copiar

• Cópia na mesma região ou entre regiões (cada cópia entre regiões é um snapshot completo).
• Copiar é também a forma de transformar um snapshot automático em manual (para guardar além da retenção ou compartilhar).
• Criptografia: snapshot criptografado só gera cópia criptografada; entre regiões é preciso informar uma chave KMS da região de destino. Não é possível criptografar a cópia de um snapshot sem criptografia.
• Parameter group: a cópia não leva o parameter group; crie um equivalente na região de destino e associe depois do restore.
• Limites: até 5 cópias em andamento por região de destino e por conta; cópias entre regiões podem levar horas e entrar em fila. Só apague o snapshot de origem quando o destino estiver available.

# Executar na região de DESTINO
aws docdb copy-db-cluster-snapshot --region sa-east-1 \
  --source-db-cluster-snapshot-identifier arn:aws:rds:us-east-1:123456789012:cluster-snapshot:meu-cluster-pre-deploy-20261013 \
  --target-db-cluster-snapshot-identifier meu-cluster-dr-20261013 \
  --source-region us-east-1 \
  --kms-key-id arn:aws:kms:sa-east-1:123456789012:key/CHAVE-DO-DESTINO \
  --copy-tags

Compartilhar

• Só snapshots manuais (copie o automático antes). Até 20 contas; snapshots sem criptografia podem ser públicos (evite: qualquer conta teria seus dados).
• Criptografado: não pode ser público e não pode usar a chave KMS padrão da conta; compartilhe também a chave (key policy com a conta de destino e a ação kms:CreateGrant).
• A conta de destino pode copiar o snapshot ou restaurar direto dele (informando o ARN).

aws docdb modify-db-cluster-snapshot-attribute \
  --db-cluster-snapshot-identifier meu-cluster-pre-deploy-20261013 \
  --attribute-name restore --values-to-add '["111122223333"]'

As ferramentas do MongoDB funcionam com o DocumentDB e são a opção quando você precisa de arquivos sob seu controle: migrar entre versões ou topologias, restaurar uma única coleção, enviar dados a outro ambiente ou guardar em outro destino.

# Dump de um banco (rode a partir de uma EC2 na VPC)
mongodump --ssl --host="meu-cluster.cluster-xxxx.us-east-1.docdb.amazonaws.com:27017" \
  --sslCAFile global-bundle.pem --username=USUARIO --password="$SENHA" \
  --db=loja --out=/backup/loja-20261013 --numParallelCollections 4

# Restore
mongorestore --ssl --host="meu-cluster-novo.cluster-xxxx.us-east-1.docdb.amazonaws.com:27017" \
  --sslCAFile global-bundle.pem --username=USUARIO --password="$SENHA" \
  --numParallelCollections 4 /backup/loja-20261013

Exemplo: cluster de 100 GiB, 1 dia de retenção e 1 snapshot manual fora da retenção: 100 GiB (contínuo) + 100 GiB (snapshot) - 100 GiB (gratuito) = 100 GiB faturados. As métricas são calculadas por cluster, de forma independente.

• Reduza a retenção ao mínimo que atenda ao RPO.
• Apague snapshots manuais que não são mais necessários (inclusive cópias entre regiões).
• Um snapshot manual dentro da retenção não aumenta a fatura de backup.
• Restaurar e dump/restore geram I/O; clones só geram custo quando divergem do original.

aws cloudwatch get-metric-statistics --namespace AWS/DocDB --metric-name TotalBackupStorageBilled \
  --dimensions Name=DBClusterIdentifier,Value=meu-cluster \
  --start-time $(date -u -d '-7 days' +%FT%TZ) --end-time $(date -u +%FT%TZ) \
  --period 86400 --statistics Average

Script: snapshot manual datado e limpeza dos antigos

#!/usr/bin/env bash
# Uso: ./docdb-snapshot-rotate.sh CLUSTER [DIAS_PARA_MANTER]
# Cria um snapshot manual datado e APAGA os manuais antigos que sigam o padrão CLUSTER-manual-*
set -euo pipefail

CLUSTER="${1:?informe o cluster}"
KEEP_DAYS="${2:-30}"
STAMP=$(date -u +%Y%m%d-%H%M)

aws docdb create-db-cluster-snapshot \
  --db-cluster-identifier "$CLUSTER" \
  --db-cluster-snapshot-identifier "${CLUSTER}-manual-${STAMP}" > /dev/null
echo "Snapshot criado: ${CLUSTER}-manual-${STAMP}"

# GNU date. No macOS use: date -u -v-${KEEP_DAYS}d +%Y-%m-%dT%H:%M:%SZ
CUTOFF=$(date -u -d "-${KEEP_DAYS} days" +%Y-%m-%dT%H:%M:%SZ)

aws docdb describe-db-cluster-snapshots --db-cluster-identifier "$CLUSTER" --snapshot-type manual \
  --query "DBClusterSnapshots[?starts_with(DBClusterSnapshotIdentifier, '${CLUSTER}-manual-') && SnapshotCreateTime<'${CUTOFF}'].DBClusterSnapshotIdentifier" \
  --output text | tr '\t' '\n' | while read -r SNAP; do
  [ -n "$SNAP" ] || continue
  echo "Apagando $SNAP"
  aws docdb delete-db-cluster-snapshot --db-cluster-snapshot-identifier "$SNAP" > /dev/null
done

Exercício de restore (roteiro)

1. Restaure o PITR ou o snapshot mais recente em um cluster temporário com instância pequena.
2. Aguarde available e crie a instância; cronometre cada etapa.
3. Conecte e valide: contagem de documentos por coleção, índices e uma amostra de dados críticos.
4. Registre o tempo total (RTO medido) e os problemas encontrados.
5. Apague o cluster temporário (e os snapshots que ele gerou) para não gerar custo.