NoSQL/MongoDB con Claude Code: esquema, índices y agregación

Empieza por los patrones de acceso

NoSQL/MongoDB no obliga a guardar todo en tablas fijas de filas y columnas. MongoDB guarda datos como documentos parecidos a JSON, así que el diseño correcto depende de cómo la aplicación lee, escribe, ordena, filtra y agrega esos documentos.

Con Claude Code, el resultado mejora mucho si no pides solo “crea un schema de orders”. Describe pantallas, respuestas API, frecuencia de actualización, volumen esperado, reportes y reglas de permisos. Con ese contexto Claude Code puede razonar sobre embedding versus reference, índices, aggregation pipeline, validation schema, seed/test y riesgos de despliegue.

Casos de uso reales

Caso	Lecturas frecuentes	Modelo recomendado	Riesgo principal
Pedidos e-commerce	pedidos por usuario, detalle, ventas por mes	incrustar nombre y precio comprados, conservar productId	cambiar el historial al cambiar el producto
Logs de auditoría SaaS	organización, usuario, rango de fechas, evento	documentos append-only, índices compuestos, posible TTL	scans lentos en colecciones grandes
CMS de artículos	buscar por slug, listar por estado, categoría	campos slug, status y fecha bien indexados	exponer borradores o notas internas
Tickets de soporte	cola por cliente, agente, comentarios recientes	incrustar comentarios acotados, separar adjuntos	arrays que crecen sin límite

Para comparar con otros enfoques, revisa también diseño de bases de datos, desarrollo de API, Prisma ORM y optimización SQL.

Prompt práctico para Claude Code

Eres el revisor de diseño MongoDB del proyecto.
Diseña el modelo desde los patrones de acceso antes de proponer colecciones.

Requisitos:
- El usuario ve sus pedidos recientes en orden descendente.
- El detalle del pedido muestra nombre, precio y categoría en el momento de compra.
- Cambios de precio del producto no deben modificar pedidos históricos.
- Administración necesita ingresos por mes, estado y categoría.
- Usa transactions solo donde el éxito parcial rompa la coherencia del negocio.
- Incluye validation schema, indexes, seed data, aggregation, explain checks y rollout checklist.

La respuesta debe decir qué va incrustado y qué va referenciado. En un pedido, el nombre del producto, el precio y la categoría comprados son hechos históricos del pedido. Stock, descripción actual y datos de catálogo viven en el producto y se enlazan con productId.

Demo ejecutable

Inicia MongoDB local:

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

Instala el driver oficial de Node.js:

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

Crea 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_es");
  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();
  });

Ejecuta:

npx tsx src/mongodb-workflow.ts

El ejemplo cubre validation schema, índices, seed, aggregation pipeline y una comprobación con explain. Pega la salida en Claude Code y pídele revisar si el índice realmente coincide con filtro y orden.

Embedding o reference

Usa embedding cuando los datos se leen juntos y representan un estado histórico. Usa references cuando los datos cambian de forma independiente, pueden crecer sin límite o deben mantenerse como única fuente de verdad. El snapshot de un producto comprado pertenece al pedido; el catálogo vivo queda referenciado. Logs y notificaciones no deberían crecer dentro del documento padre.

Índices, aggregation y transactions

Los índices se derivan de queries reales. find({ userId }).sort({ createdAt: -1 }) corresponde a { userId: 1, createdAt: -1 }. La aggregation debe filtrar pronto con $match, expandir solo lo necesario con $unwind y luego agrupar. Para dashboards frecuentes, considera caché o colecciones preagregadas.

Las transactions sirven cuando un éxito parcial rompe el proceso, por ejemplo marcar un pedido como pagado y registrar el pago capturado. Notificaciones, sincronización de búsqueda y contadores suelen poder reintentarse fuera de la transaction.

Referencias oficiales: Data Modeling, Indexes, Aggregation, Transactions y MongoDB Node.js Driver.

Errores comunes

El primer error es copiar la normalización relacional sin pensar. El segundo es incrustar arrays sin límite como comentarios, logs o notificaciones. El tercero es confiar solo en TypeScript y no validar en la base. El cuarto es crear índices sin mirar explain("executionStats"). El quinto es ejecutar una aggregation pesada en cada request.

Antes de producción, confirma que las queries principales tienen índice, el validation schema está aplicado, seed/test cubre lista, detalle y reportes, explain no muestra scans inesperados, y los límites de transaction, backup y rollback están documentados.

ClaudeCodeLab puede ayudar con formación en Claude Code, plantillas CLAUDE.md y consultoría de implementación MongoDB/API. En la práctica, revisar explain con Claude Code suele ahorrar más trabajo que añadir índices a ciegas.