Panduan NoSQL/MongoDB dengan Claude Code: Schema, Index, Aggregation

Mulai dari access pattern, bukan nama collection

NoSQL/MongoDB adalah database yang tidak memaksa data masuk ke tabel tetap berisi baris dan kolom. MongoDB menyimpan data sebagai dokumen yang mirip JSON. Jadi desain yang bagus ditentukan oleh cara aplikasi membaca, menulis, mengurutkan, memfilter, dan mengagregasi dokumen tersebut.

Saat memakai Claude Code, jangan mulai dengan “buat collection users, products, orders”. Berikan dulu konteks layar, respons API, frekuensi update, pertumbuhan data, kebutuhan laporan, dan batasan permission. Dengan konteks itu, Claude Code bisa menilai embedding vs reference, index, aggregation pipeline, validation schema, seed/test, dan risiko rollout.

Use case yang sering muncul

Use case	Pola baca umum	Bentuk model MongoDB	Risiko utama
Order e-commerce	order terbaru per user, detail order, revenue bulanan	embed nama dan harga saat beli, simpan productId	histori order ikut berubah saat produk diubah
Audit log SaaS	organisasi, user, rentang tanggal, tipe event	dokumen append-only, compound index, TTL jika perlu	scan lambat di collection besar
CMS artikel	lookup by slug, list by status, archive kategori	field slug, status, tanggal dengan index jelas	draft atau catatan internal bocor
Tiket support	antrean customer, agent, komentar terbaru	embed komentar terbatas, pisahkan attachment	array tumbuh tanpa batas

Untuk konteks arsitektur, baca juga desain database dengan Claude Code, pengembangan API, Prisma ORM, dan optimasi SQL.

Prompt yang lebih berguna untuk Claude Code

You are the MongoDB design reviewer for this project.
Design from access patterns before proposing collections.

Requirements:
- Users view their recent orders in reverse chronological order.
- Order detail shows product name, price, and category at purchase time.
- Product price changes must not rewrite historical orders.
- Admins need revenue by month, status, and category.
- Use transactions only when partial success would break business correctness.
- Include validation schema, indexes, seed data, aggregation, explain checks, and rollout checklist.

Jawaban yang bagus harus jelas: mana yang di-embed dan mana yang direferensikan. Pada order, nama produk, harga beli, dan kategori saat pembelian adalah fakta historis. Data stok, deskripsi terbaru, dan aturan katalog tetap ada di dokumen produk, lalu dihubungkan dengan productId.

Demo yang bisa langsung dijalankan

Jalankan MongoDB lokal:

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

Pasang driver resmi Node.js:

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

Buat 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_id");
  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();
  });

Jalankan:

npx tsx src/mongodb-workflow.ts

Demo ini mencakup validation schema, index, seed data, aggregation pipeline, dan pengecekan explain. Setelah jalan, tempel output ke Claude Code dan minta review apakah query, sort, dan urutan index sudah cocok.

Embedding atau reference

Pakai embedding saat data sering dibaca bersama dan merepresentasikan fakta pada satu waktu. Pakai reference saat data berubah sendiri, bisa tumbuh tanpa batas, atau harus menjadi satu sumber kebenaran. Snapshot produk yang dibeli cocok di-embed ke order. Katalog produk tetap direferensikan. Audit log, notifikasi, dan komentar panjang jangan dibiarkan tumbuh tanpa batas di dokumen induk.

Index, aggregation, dan transaction

Index harus diturunkan dari query nyata. find({ userId }).sort({ createdAt: -1 }) cocok dengan { userId: 1, createdAt: -1 }. Aggregation sebaiknya mulai dengan $match, lalu $unwind hanya array yang diperlukan, kemudian $group. Untuk dashboard yang sering dibuka, cache atau collection hasil agregasi bisa lebih stabil.

Transaction dipakai saat partial success akan merusak proses bisnis, misalnya mengubah order menjadi paid dan menulis payment record. Notifikasi, sinkronisasi search index, dan counter biasanya bisa retry di luar transaction.

Referensi resmi: Data Modeling, Indexes, Aggregation, Transactions, dan MongoDB Node.js Driver.

Kesalahan yang sering terjadi

Pertama, menyalin normalisasi relasional tanpa menyesuaikan pola baca. Kedua, meng-embed array tanpa batas seperti komentar, log, dan notifikasi. Ketiga, hanya mengandalkan tipe TypeScript tanpa validasi di database. Keempat, membuat index tapi tidak melihat explain("executionStats"). Kelima, menjalankan aggregation berat di setiap request API.

Sebelum production, pastikan query utama punya index, validation schema sudah aktif, seed/test mencakup list, detail, dan report, explain tidak menunjukkan scan tak terduga, dan batas transaction, backup, serta rollback sudah ditulis.

ClaudeCodeLab bisa membantu training Claude Code, template CLAUDE.md, dan konsultasi implementasi MongoDB/API. Dari pengalaman menerapkan workflow ini, review explain bersama Claude Code lebih sering mengurangi rework daripada menambah index secara asal.