NoSQL/MongoDB com Claude Code: schema, índices e aggregation

Comece pelos padrões de acesso

NoSQL/MongoDB não é um banco que prende tudo em tabelas fixas de linhas e colunas. O MongoDB salva dados como documentos próximos de JSON. Por isso, o modelo certo depende de como a aplicação lê, grava, ordena, filtra e agrega esses documentos.

Com Claude Code, o resultado melhora quando você descreve o fluxo real antes de pedir código. Em vez de “crie collections de users, products e orders”, informe telas, respostas de API, frequência de atualização, volume esperado, relatórios e regras de permissão. Assim o Claude Code consegue avaliar embedding versus reference, índices, aggregation pipeline, validation schema, seed/test e riscos de rollout.

Casos de uso práticos

Caso	Leituras comuns	Modelo MongoDB indicado	Risco principal
Pedidos de e-commerce	pedidos por usuário, detalhe, receita mensal	embutir nome e preço comprados, manter productId	alterar histórico quando o produto muda
Logs de auditoria SaaS	organização, usuário, período, tipo de evento	documentos append-only, índices compostos, TTL se necessário	scans lentos em coleções grandes
CMS de artigos	buscar por slug, listar por status e categoria	slug, status e data bem indexados	expor rascunhos ou notas internas
Tickets de suporte	fila por cliente, agente, comentários recentes	embutir comentários com limite, separar anexos	arrays crescendo sem controle

Para comparar com outras escolhas, veja também design de banco de dados, desenvolvimento de API, Prisma ORM e otimização SQL.

Prompt recomendado para Claude Code

Você é o revisor de design MongoDB do projeto.
Modele a partir dos padrões de acesso antes de sugerir collections.

Requisitos:
- Usuários veem seus pedidos recentes em ordem decrescente.
- O detalhe do pedido mostra nome, preço e categoria no momento da compra.
- Mudanças de preço no produto não podem alterar pedidos antigos.
- Admins precisam de receita por mês, status e categoria.
- Use transactions só onde sucesso parcial quebraria a consistência do negócio.
- Inclua validation schema, indexes, seed data, aggregation, explain checks e rollout checklist.

A resposta precisa separar o que fica embutido e o que fica referenciado. Nome, preço e categoria do produto no momento da compra são fatos do pedido. Estoque, descrição atual e regras de catálogo ficam no produto e são ligados por productId.

Exemplo executável

Suba o MongoDB local:

docker run --name mongo-claude-demo -p 27017:27017 -d mongo:8

Instale o driver oficial para Node.js:

npm init -y
npm install mongodb
npm install -D tsx typescript
mkdir -p src

Crie src/mongodb-workflow.ts:

import { MongoClient, ObjectId } from "mongodb";

const client = new MongoClient(process.env.MONGODB_URI ?? "mongodb://localhost:27017");

async function main() {
  await client.connect();
  const db = client.db("claude_code_shop_pt");
  await db.dropDatabase();

  await db.createCollection("orders", {
    validator: {
      $jsonSchema: {
        bsonType: "object",
        required: ["userId", "status", "items", "totalAmount", "createdAt", "updatedAt"],
        properties: {
          userId: { bsonType: "objectId" },
          status: { enum: ["pending", "paid", "shipped", "cancelled"] },
          totalAmount: { bsonType: ["int", "long", "double", "decimal"], minimum: 0 },
          createdAt: { bsonType: "date" },
          updatedAt: { bsonType: "date" },
          items: {
            bsonType: "array",
            minItems: 1,
            items: {
              bsonType: "object",
              required: ["productId", "name", "category", "price", "quantity"],
              properties: {
                productId: { bsonType: "objectId" },
                name: { bsonType: "string" },
                category: { bsonType: "string" },
                price: { bsonType: ["int", "long", "double", "decimal"], minimum: 0 },
                quantity: { bsonType: "int", minimum: 1 }
              }
            }
          }
        }
      }
    }
  });

  const products = db.collection("products");
  const orders = db.collection("orders");

  await Promise.all([
    orders.createIndex({ userId: 1, createdAt: -1 }, { name: "orders_by_user_recent" }),
    orders.createIndex({ status: 1, createdAt: -1 }, { name: "orders_by_status_recent" }),
    orders.createIndex({ "items.category": 1, createdAt: -1 }, { name: "orders_by_category_month" })
  ]);

  const inserted = await products.insertMany([
    { name: "Claude Code Workshop", category: "training", currentPrice: 48000 },
    { name: "MongoDB Review Template", category: "template", currentPrice: 9800 }
  ]);

  const userId = new ObjectId();
  const now = new Date("2026-06-01T09:00:00.000Z");

  await orders.insertOne({
    userId,
    status: "paid",
    items: [
      { productId: inserted.insertedIds[0], name: "Claude Code Workshop", category: "training", price: 48000, quantity: 1 },
      { productId: inserted.insertedIds[1], name: "MongoDB Review Template", category: "template", price: 9800, quantity: 2 }
    ],
    totalAmount: 67600,
    createdAt: now,
    updatedAt: now
  });

  const report = await orders.aggregate([
    { $match: { status: { $in: ["paid", "shipped"] } } },
    { $unwind: "$items" },
    {
      $group: {
        _id: {
          month: { $dateToString: { format: "%Y-%m", date: "$createdAt" } },
          category: "$items.category"
        },
        revenue: { $sum: { $multiply: ["$items.price", "$items.quantity"] } },
        quantity: { $sum: "$items.quantity" }
      }
    },
    { $sort: { "_id.month": 1, revenue: -1 } }
  ]).toArray();

  const explain = await orders.find({ userId }).sort({ createdAt: -1 }).limit(10).explain("executionStats");
  if (report.length !== 2) throw new Error("aggregation failed");
  if ((explain.executionStats?.totalDocsExamined ?? 0) > 1) throw new Error("index check failed");

  console.log(JSON.stringify({ report, examined: explain.executionStats.totalDocsExamined }, null, 2));
}

main()
  .catch((error) => {
    console.error(error);
    process.exitCode = 1;
  })
  .finally(async () => {
    await client.close();
  });

Execute:

npx tsx src/mongodb-workflow.ts

O exemplo cobre validation schema, índices, seed, aggregation pipeline e uma checagem com explain. Passe a saída para o Claude Code e peça revisão da ordem do índice, filtro e sort.

Embedding ou reference

Use embedding quando os dados são lidos juntos e representam um fato de um momento específico. Use reference quando os dados mudam de forma independente, crescem sem limite ou precisam ser a única fonte de verdade. O snapshot do produto comprado fica no pedido; o catálogo atual fica referenciado. Logs, notificações e comentários ilimitados não devem crescer dentro do documento pai.

Índices, aggregation e transactions

Índices vêm das queries reais. find({ userId }).sort({ createdAt: -1 }) combina com { userId: 1, createdAt: -1 }. A aggregation deve filtrar cedo com $match, abrir apenas arrays necessários com $unwind e depois agrupar. Relatórios frequentes podem usar cache ou coleções pré-agregadas.

Transactions fazem sentido quando sucesso parcial quebra o negócio, como marcar um pedido como pago e registrar o pagamento capturado. Notificações, sincronização de busca e contadores normalmente podem ser reprocessados fora da transaction.

Referências oficiais: Data Modeling, Indexes, Aggregation, Transactions e MongoDB Node.js Driver.

Armadilhas comuns

A primeira armadilha é copiar normalização relacional sem questionar. A segunda é embutir arrays sem limite, como comentários, logs e notificações. A terceira é confiar só nos tipos do TypeScript e não validar no banco. A quarta é criar índices sem verificar explain("executionStats"). A quinta é rodar aggregation pesada em toda request.

Antes do rollout, confirme que as queries principais têm índice, o validation schema está aplicado, seed/test cobre lista, detalhe e relatório, explain não mostra scans inesperados, e as fronteiras de transaction, backup e rollback estão documentadas.

ClaudeCodeLab pode apoiar com treinamento em Claude Code, templates CLAUDE.md e consultoria de implementação MongoDB/API. Na prática, revisar explain com Claude Code costuma reduzir mais retrabalho do que adicionar índices sem critério.