Document, collection, BSON et ObjectId

Un document MongoDB est un ensemble de paires champ-valeur, écrit comme un objet JSON, qui peut contenir d'autres documents et des tableaux. Les documents sont rangés dans des collections, elles-mêmes rangées dans des bases. MongoDB les stocke au format BSON, une version binaire et typée de JSON, et identifie chacun par un champ _id, le plus souvent un ObjectId. Ce chapitre décrit ce vocabulaire et les types que tu utiliseras dans toutes tes requêtes.

Base, collection, document : le vocabulaire

Une instance MongoDB (le serveur mongod) héberge plusieurs bases ; chaque base contient des collections ; chaque collection contient des documents.

Voici la fiche de frais de septembre 2026 de Lucas Martin, telle que MongoDB la renvoie :

{
  _id: ObjectId('6ae8a9d8fc828abd94f81c6f'),
  visiteur: ObjectId('6a0000000000000000000001'),
  mois: '2026-09',
  etat: 'VA',
  dateModif: ISODate('2026-10-12T09:30:00.000Z'),
  lignesForfait: [
    { code: 'ETP', quantite: 3, montantUnitaire: 110 },
    { code: 'KM', quantite: 420, montantUnitaire: 0.62 },
    { code: 'NUI', quantite: 2, montantUnitaire: 80 },
    { code: 'REP', quantite: 5, montantUnitaire: 25 }
  ],
  fraisHorsForfait: [
    { date: ISODate('2026-09-14T00:00:00.000Z'), libelle: 'Repas client à Lyon', montant: 23.5 }
  ],
  montantValide: 898.9
}

On y lit tout le vocabulaire du modèle :

• des champs simples : mois est une chaîne, montantValide un nombre, dateModif une date ;
• une référence : visiteur contient l'_id d'un document de la collection visiteurs, comme une clé étrangère ;
• des tableaux de sous-documents : lignesForfait contient quatre documents, un par type de frais forfaitisé (ETP pour forfait étape, KM pour frais kilométriques, NUI pour nuitée, REP pour repas) ;
• l'identifiant _id, généré par MongoDB à l'insertion.

Les codes d'état sont ceux d'AppliFrais : CR (fiche créée, en cours de saisie), CL (clôturée par le visiteur), VA (validée par le comptable), MP (mise en paiement), RB (remboursée).

Un schéma souple, mais un schéma quand même

Rien n'empêche deux documents de la même collection d'avoir des champs différents. Dans le jeu de données du cours, Sophie Lambert, comptable, n'a pas de champ region, alors que les visiteurs en ont un. En relationnel, il faudrait une colonne region vide pour elle ; ici, le champ est simplement absent.

Cette souplesse sert pendant le développement (ajouter un champ ne demande aucune migration) et pour les données réellement variables. Elle devient un piège quand elle n'est pas voulue : une faute de frappe (montantValider au lieu de montantValide) crée silencieusement un nouveau champ, et la requête qui cherche montantValide ne trouve plus le document. D'où deux protections, qu'on verra plus loin :

• un schéma Mongoose côté application, qui ne garde que les champs déclarés et vérifie les types (chapitre 10) ;
• un validateur $jsonSchema côté base, qui refuse un document mal formé quelle que soit l'application qui écrit (chapitre 6).

BSON : du JSON binaire et typé

JSON, que tu connais par les API (le format JSON), n'a que six types : chaîne, nombre, booléen, null, objet et tableau. C'est trop peu pour une base de données : JSON ne distingue pas un entier d'un décimal, et n'a pas de type date. MongoDB stocke donc ses documents en BSON (Binary JSON), un format binaire qui ajoute des types et la longueur de chaque élément, pour que le serveur parcoure un document sans le relire entièrement.

Tu vérifies le type réel d'un champ avec l'opérateur $type (chapitre 5), ou dans Compass, qui l'affiche à côté de chaque valeur.

Les nombres et l'argent

Un double est un nombre à virgule flottante, comme tous les nombres de JavaScript : il ne représente pas exactement la plupart des décimaux. Dans mongosh, 0.1 + 0.2 affiche 0.30000000000000004. Pour des montants qu'on additionne, deux solutions propres existent :

• le type Decimal128, exact : Decimal128('0.1') plus Decimal128('0.2') donne exactement Decimal128('0.3') ;
• des entiers en centimes (2350 pour 23,50 €), comme le font beaucoup d'API de paiement.

Le jeu de données du cours garde des double pour que les exemples restent lisibles, et arrondit au centime avec $round dans les calculs (chapitre 8). Pour un vrai logiciel comptable, choisis Decimal128 ou les centimes dès le départ : changer de type plus tard demande de réécrire tous les documents.

L'identifiant _id et l'ObjectId

Chaque document a un champ _id, unique dans sa collection, qui joue le rôle de clé primaire. MongoDB crée automatiquement un index unique dessus. Si tu n'en fournis pas, le driver en génère un de type ObjectId au moment de l'insertion.

Un ObjectId tient sur 12 octets, affichés en 24 caractères hexadécimaux :

Cette construction a trois conséquences utiles :

• deux programmes peuvent générer des identifiants sans se concerter et sans risque de doublon : c'est ce qui permet de répartir la base sur plusieurs serveurs, là où un AUTO_INCREMENT demande un compteur central ;
• les ObjectId sont à peu près croissants dans le temps : trier par _id trie à peu près par date de création ;
• la date de création se lit dans l'identifiant : ObjectId('6ae8a9d8fc828abd94f81c6f').getTimestamp() renvoie ISODate('2026-11-02T15:18:48.000Z').

Tu peux aussi fournir ton propre _id, de n'importe quel type sauf un tableau ou une expression régulière : un matricule, un code ISO de pays, un numéro de commande métier. C'est pertinent quand l'identifiant naturel est stable et unique. Les visiteurs du jeu de données ont des ObjectId fixés à la main (6a0000000000000000000001, …0002…) pour que tes résultats ressemblent à ceux du cours ; dans une vraie application, laisse MongoDB les générer.

Les limites d'un document

• 16 Mio par document, au maximum. C'est énorme pour des données texte (la fiche ci-dessus pèse moins d'un kilo-octet), mais c'est une limite dure : un tableau qui grossit sans fin (l'historique de toutes les connexions d'un utilisateur, les commentaires d'un article très populaire) finira par l'atteindre. C'est un critère de modélisation majeur (chapitre 6).
• 100 niveaux d'imbrication, au maximum. Tu n'en approcheras jamais avec un modèle raisonnable.
• Les noms de champs : évite ceux qui commencent par $ (réservé aux opérateurs) ou qui contiennent un point (réservé à la notation pointée, lignesForfait.code).
• Les fichiers : une image ou un PDF n'a rien à faire dans un document. Range-le sur un disque ou dans un stockage objet (comme S3), et garde son chemin dans le document. Pour les rares cas où il faut le garder en base, MongoDB propose GridFS, qui découpe un fichier en morceaux de 255 Kio.

Exercices

{
  _id: 'GH-482-KL',                              // string : l'immatriculation, identifiant naturel
  modele: 'Peugeot e-208',                       // string
  miseEnCirculation: ISODate('2024-03-18'),      // date
  puissanceFiscale: 5,                           // int
  kilometrage: 48210,                            // int (un long au-delà de 2 147 483 647)
  utilisateurs: [                                // array d'objectId : des références
    ObjectId('6a0000000000000000000001'),
    ObjectId('6a0000000000000000000003')
  ],
  prixAchat: Decimal128('31450.00')              // decimal : un montant exact
}