NoSQL/MongoDB avec Claude Code : schéma, index et agrégation

Commencer par les accès, pas par les collections

NoSQL/MongoDB désigne une base qui ne force pas les données dans des lignes et colonnes fixes. MongoDB stocke les données sous forme de documents proches de JSON. Le bon modèle dépend donc de la manière dont l’application lit, écrit, filtre, trie et agrège ces documents.

Avec Claude Code, la qualité de la réponse dépend du contexte donné. Une demande comme “crée un schéma orders” produit souvent un exemple trop générique. Décris plutôt les écrans, les réponses API, la fréquence des mises à jour, le volume attendu, les rapports nécessaires et les limites d’autorisation. Claude Code peut alors raisonner sur embedding versus reference, index, aggregation pipeline, validation schema, seed/test et risques de déploiement.

Cas d’usage concrets

Cas d’usage	Lectures fréquentes	Modèle MongoDB recommandé	Risque principal
Commandes e-commerce	commandes par utilisateur, détail, revenu mensuel	intégrer le nom et le prix achetés, garder productId	modifier l’historique quand le produit change
Logs d’audit SaaS	organisation, utilisateur, période, type d’événement	documents append-only, index composés, TTL si utile	scans lents sur une grosse collection
CMS éditorial	article par slug, liste par statut, archive par catégorie	champs slug, status et date bien indexés	exposer des brouillons ou notes internes
Support client	file client, agent assigné, derniers commentaires	intégrer un nombre borné de commentaires, séparer les pièces jointes	tableau de commentaires sans limite

Pour replacer ce choix dans l’architecture globale, consulte aussi la conception de base de données, le développement API, Prisma ORM et l’optimisation SQL.

Prompt utile pour Claude Code

Tu es le reviewer MongoDB du projet.
Conçois le modèle à partir des access patterns avant de proposer les collections.

Exigences:
- L'utilisateur voit ses commandes récentes en ordre décroissant.
- Le détail de commande affiche le nom, le prix et la catégorie au moment de l'achat.
- Un changement de prix produit ne doit pas modifier les anciennes commandes.
- L'admin veut le revenu par mois, statut et catégorie.
- Utilise les transactions seulement si un succès partiel casse la cohérence métier.
- Fournis validation schema, indexes, seed data, aggregation, explain checks et rollout checklist.

La réponse doit dire explicitement quoi intégrer et quoi référencer. Dans une commande, le nom du produit acheté, le prix et la catégorie au moment de l’achat sont des faits historiques. Le stock, la description actuelle et les règles de merchandising restent dans le document produit et sont reliés par productId.

Exemple exécutable

Démarre MongoDB localement :

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

Installe le driver officiel Node.js :

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

Crée 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_fr");
  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();
  });

Exécute :

npx tsx src/mongodb-workflow.ts

Ce script couvre validation schema, indexes, seed data, aggregation pipeline et vérification explain. Donne le résultat à Claude Code pour lui demander si l’ordre de l’index correspond bien au filtre et au tri.

Embedding ou reference

Embedding convient aux données lues ensemble et qui décrivent un état à un moment précis. Reference convient aux données qui changent indépendamment, grossissent sans limite ou doivent rester une source de vérité unique. Une commande intègre donc le snapshot acheté, mais garde une référence vers le produit. Des logs d’audit ou notifications ne doivent pas grossir sans fin dans le document parent.

Index, aggregation et transaction

Les index viennent des requêtes réelles. find({ userId }).sort({ createdAt: -1 }) appelle naturellement { userId: 1, createdAt: -1 }. Une aggregation doit commencer par $match, dérouler seulement les tableaux nécessaires avec $unwind, puis grouper. Pour les tableaux de bord fréquents, un cache ou une collection pré-agrégée peut être plus fiable.

Les transactions sont utiles seulement si un succès partiel casse le métier, par exemple marquer une commande comme payée et écrire le paiement capturé. Les notifications ou la synchronisation d’un index de recherche peuvent souvent être réessayées hors transaction.

Références officielles : Data Modeling, Indexes, Aggregation, Transactions et MongoDB Node.js Driver.

Pièges fréquents

Le premier piège consiste à copier une normalisation relationnelle sans réfléchir. Le second est l’excès inverse : tout intégrer, même les commentaires, logs ou notifications sans limite. Le troisième est de se reposer uniquement sur TypeScript et d’oublier la validation côté base. Le quatrième est de créer un index sans vérifier explain("executionStats"). Le cinquième est d’exécuter une aggregation lourde à chaque requête API.

Avant le déploiement, vérifie les index des principales requêtes, le validation schema, les seed/tests, l’absence de scans inattendus, les frontières de transaction, la sauvegarde et le rollback.

ClaudeCodeLab accompagne les équipes avec formation Claude Code, modèles CLAUDE.md et conseil d’implémentation MongoDB/API. Dans la pratique, cette boucle de review avec explain évite souvent d’ajouter des index inutiles.