Index MongoDB et explain() : accélérer les requêtes

Un index MongoDB est une structure triée, rangée à côté d'une collection, qui permet de trouver les documents d'après la valeur d'un ou plusieurs champs sans lire toute la collection. Sans index, MongoDB fait un parcours complet (COLLSCAN) ; avec le bon index, il va directement aux bonnes entrées (IXSCAN). Ce chapitre explique comment créer les index utiles avec createIndex, comment vérifier avec explain() qu'une requête s'en sert, et comment un index unique garantit une règle de gestion. Le principe est le même qu'en SQL (index SQL) ; ce sont les commandes et quelques règles qui changent.

Pourquoi un index

Sur les 9 fiches du jeu de données, tout est instantané. Pour voir la différence, il faut du volume. Ce script crée une collection fichesVolume de 60 000 fiches : 500 visiteurs, 120 mois chacun, de janvier 2017 à décembre 2026.

db.fichesVolume.drop();
const docs = [];
for (let v = 0; v < 500; v++) {
  const visiteur = ObjectId(v.toString(16).padStart(24, '0'));   // 000…000, 000…001, …
  for (let m = 0; m < 120; m++) {
    const mois = `${2017 + Math.floor(m / 12)}-${String((m % 12) + 1).padStart(2, '0')}`;
    const etat = m === 119 ? 'CR' : m === 118 ? 'CL' : ['RB', 'RB', 'RB', 'RB', 'RB', 'RB', 'MP', 'VA'][(v + m) % 8];
    docs.push({ visiteur, mois, etat, montantValide: (v * 7 + m * 13) % 900 });
  }
}
db.fichesVolume.insertMany(docs);
db.fichesVolume.countDocuments()   // 60000

Cherchons la fiche d'octobre 2026 du visiteur n° 42, et demandons à MongoDB comment il l'a trouvée :

db.fichesVolume.find({ visiteur: ObjectId('00000000000000000000002a'), mois: '2026-10' })
  .explain('executionStats')

La réponse est un gros document. Les lignes qui comptent :

queryPlanner: { winningPlan: { stage: 'COLLSCAN', … } },
executionStats: {
  nReturned: 1,
  executionTimeMillis: 10,
  totalKeysExamined: 0,
  totalDocsExamined: 60000,
  …
}

MongoDB a lu les 60 000 documents pour en renvoyer un. Dix millisecondes, c'est encore rapide ; mais le temps croît avec la collection, et si cette requête est appelée à chaque affichage de la page « Ma fiche du mois », par des centaines d'utilisateurs, le serveur passe son temps à relire toute la base.

Créer un index : createIndex

db.fichesVolume.createIndex({ visiteur: 1, mois: 1 }, { unique: true })
// 'visiteur_1_mois_1'

createIndex prend les champs de l'index et le sens du tri (1 croissant, -1 décroissant), puis des options. MongoDB nomme l'index d'après ses champs (visiteur_1_mois_1). La même requête donne maintenant :

queryPlanner: { winningPlan: { stage: 'FETCH', inputStage: { stage: 'IXSCAN', indexName: 'visiteur_1_mois_1', … } } },
executionStats: { nReturned: 1, executionTimeMillis: 1, totalKeysExamined: 1, totalDocsExamined: 1 }

Une entrée d'index lue (IXSCAN), un document chargé (FETCH). La structure d'un index MongoDB est un arbre B, comme dans les SGBD relationnels : quelques pages lues suffisent pour trouver une valeur parmi des millions.

Les commandes de gestion :

db.fichesVolume.getIndexes()                   // liste les index, dont _id_ créé d'office
db.fichesVolume.dropIndex('visiteur_1_mois_1') // supprime un index par son nom
db.fichesVolume.stats().indexSizes             // la place occupée par chaque index

Lire un plan avec explain()

explain() accepte trois niveaux : 'queryPlanner' (le plan choisi, sans exécuter), 'executionStats' (le plan et les chiffres de l'exécution) et 'allPlansExecution' (tous les plans essayés). Retiens ces indicateurs :

Les étapes que tu rencontreras :

L'index composé et la règle du préfixe

Un index sur plusieurs champs est trié par le premier champ, puis par le deuxième à l'intérieur de chaque valeur du premier, comme un annuaire trié par nom puis par prénom. Il sert donc pour toute requête qui porte sur un préfixe de ses champs, en partant de la gauche :

Un index peut être parcouru dans les deux sens : { visiteur: 1, mois: 1 } sert aussi un tri { mois: -1 } pour un visiteur donné. Quand un tri ne correspond à aucun index, le plan contient une étape SORT : MongoDB trie en mémoire, et passe par le disque au-delà de 100 Mio, ce qui est encore plus lent. Trier les fiches d'un visiteur par montantValide donne ainsi SORT ← FETCH ← IXSCAN.

L'ordre des champs : la règle ESR

Pour un index composé qui sert un filtre et un tri, place les champs dans cet ordre, qu'on appelle la règle ESR :

1. Egalité : les champs testés par égalité (etat: 'CL') ;
2. Sort : les champs du tri (mois: -1) ;
3. Range : les champs testés par intervalle (montantValide: { $gte: 500 }).

La liste du comptable, « les fiches clôturées, des plus récentes aux plus anciennes », demande un index { etat: 1, mois: -1 } :

db.fichesVolume.createIndex({ etat: 1, mois: -1 })
db.fichesVolume.find({ etat: 'CL' }).sort({ mois: -1 }).explain('executionStats')

L'égalité d'abord : l'index isole d'un coup les 500 fiches CL, déjà rangées par mois décroissant. Le tri devient gratuit.

Requête couverte

Si la projection ne demande que des champs présents dans l'index (et exclut _id), MongoDB répond avec l'index seul, sans lire un seul document :

db.fichesVolume.find({ etat: 'CL' }, { _id: 0, etat: 1, mois: 1 })
// plan : PROJECTION_COVERED ← IXSCAN, totalDocsExamined: 0

C'est la requête la plus rapide possible. Pense-y pour les listes qui n'affichent que deux ou trois champs.

Les index sur les tableaux

Un index sur un champ qui contient un tableau crée une entrée par élément : c'est un index multiclé (multikey). Il accélère les filtres comme { 'lignesForfait.code': 'NUI' } ou $elemMatch :

db.fiches.createIndex({ 'lignesForfait.code': 1 })

MongoDB le crée automatiquement en multiclé dès qu'il rencontre un tableau. Une limite : un index composé ne peut pas contenir deux champs tableaux du même document.

L'index unique : une règle de gestion

Un index unique refuse deux documents qui ont la même valeur, ou la même combinaison de valeurs. C'est l'équivalent d'une contrainte UNIQUE en SQL, et c'est le seul moyen sûr de garantir l'unicité : vérifier « est-ce que la fiche existe déjà ? » dans le code, puis l'insérer, laisse passer deux requêtes simultanées.

Sur le jeu de données d'AppliFrais, la règle « une seule fiche par visiteur et par mois » devient :

db.fiches.createIndex({ visiteur: 1, mois: 1 }, { unique: true })
db.fiches.createIndex({ etat: 1, mois: -1 })     // la liste du comptable

db.fiches.insertOne({ visiteur: ObjectId('6a0000000000000000000001'), mois: '2026-10', etat: 'CR' })

MongoServerError: E11000 duplicate key error collection: appli_frais.fiches
index: visiteur_1_mois_1 dup key: { visiteur: ObjectId('6a0000000000000000000001'), mois: "2026-10" }

Les autres types d'index

Le coût d'un index

Un index n'est pas gratuit :

• il ralentit chaque écriture : chaque insertion, modification ou suppression met à jour tous les index concernés ;
• il occupe de la place, sur disque et surtout en mémoire vive, où MongoDB essaie de garder les index utilisés : sur fichesVolume, l'index visiteur_1_mois_1 pèse environ 1 Mio pour 60 000 documents ;
• un index inutilisé n'apporte que ces coûts.

Crée donc les index à partir des requêtes réelles : celles des écrans fréquents, celles des règles d'unicité, celles que explain() montre lentes. Avec Mongoose, tu les déclares dans le schéma (ficheSchema.index({ visiteur: 1, mois: 1 }, { unique: true }), chapitre 10).

Exercices

db.fichesVolume.dropIndexes()        // repartir sans index (sauf _id)
db.fichesVolume.find({ etat: 'MP', mois: { $gte: '2026-01' } }).explain('executionStats')
// COLLSCAN : totalDocsExamined 60000
db.fichesVolume.createIndex({ etat: 1, mois: -1 })
db.fichesVolume.find({ etat: 'MP', mois: { $gte: '2026-01' } }).explain('executionStats')
// FETCH ← IXSCAN(etat_1_mois_-1) : totalKeysExamined = totalDocsExamined = nReturned