Skip to content

MongoDB Aide-mémoire

Base de données documentaire NoSQL pour le stockage de données à fort volume.

01

Premiers pas

Se connecter à MongoDB

mongosh est le shell MongoDB moderne (remplaçant l'ancien shell mongo). Une chaîne de connexion suit le format URI mongodb://[user:pass@]host[:port]/[db][?options]. La base /admin est la base d'authentification par défaut. Vous pouvez vous connecter directement à une base précise en l'ajoutant à l'URI.

mongodb
# connect to a local server on default port
mongosh

# connect to a specific host and port
mongosh "mongodb://localhost:27017"

# connect with authentication
mongosh "mongodb://user:pass@localhost:27017/admin"

# connect to a specific database directly
mongosh "mongodb://localhost:27017/mydb"

# show connection info
db.getMongo().getDBNames()

Bases de données : les bases

MongoDB crée les bases et collections paresseusement — elles n'apparaissent qu'après l'insertion du premier document. 'use mydb' change le contexte mais ne crée pas la base tant que rien n'est écrit. show dbs ne liste pas les bases vides. dropDatabase supprime définitivement toutes les collections et leurs données.

mongodb
# show all databases
show dbs

# switch to (or create) a database
use mydb

# show the current database
db

# create is implicit: inserting into a
# non-existent collection creates both the
# collection and the database

# drop the current database
db.dropDatabase()

Collections

Les collections sont l'analogue des tables SQL et contiennent des documents. Elles sont créées automatiquement à la première insertion, mais createCollection permet de fixer des options comme capped (collections à taille fixe qui écrasent les vieux documents — utile pour les logs). stats() montre la taille de stockage, le nombre de documents et les détails d'index.

mongodb
# list collections in current database
show collections
db.getCollectionNames()

# create a collection explicitly with options
db.createCollection("users", {
  capped: true,
  size: 5242880,
  max: 5000
})

# rename a collection
db.users.renameCollection("accounts")

# drop a collection
db.users.drop()

# get collection stats
db.users.stats()

Types de données BSON

BSON étend JSON avec des types essentiels aux applications : ObjectId (IDs uniques de 12 octets), ISODate, NumberDecimal (décimal exact pour l'argent — évite les arrondis flottants), NumberLong (entiers 64 bits), BinData (binaire), etc. Utiliser NumberDecimal pour la devise évite les erreurs classiques de virgule flottante.

mongodb
# MongoDB stores BSON (binary JSON) with rich types
{
  _id: ObjectId("65a1b2c3d4e5f6a7b8c9d0e1"),
  name: "Alice",                       // String
  age: 30,                             // Int32
  score: NumberLong(9007199254740992), // Int64
  price: NumberDecimal("19.99"),       // Decimal128 (exact money)
  active: true,                        // Boolean
  birthday: ISODate("1995-08-15"),     // Date
  tags: ["red", "blue"],               // Array
  meta: { views: 100 },                // Embedded document
  data: BinData(0, "aGVsbG8="),        // Binary
  id: UUID("...")                      // UUID
}

Helpers du shell et aide

mongosh supporte le JavaScript complet : vous pouvez écrire boucles, fonctions et variables dans le shell. .pretty() formate la sortie pour la lisibilité (défaut dans mongosh). load() exécute un fichier .js dans le contexte du shell — utile pour des scripts d'admin répétitifs. db.collection.help() liste toutes les méthodes disponibles.

mongodb
# get help on database methods
db.help()

# get help on collection methods
db.users.help()

# list common shell commands
help

# pretty-print query results
db.users.find().pretty()

# print JSON in a compact form
db.users.find().toArray()

# execute a JavaScript file
mongosh --file script.js
load("script.js")
02

Opérations CRUD

Insérer des documents

MongoDB génère automatiquement un _id (ObjectId) si vous n'en fournissez pas. Le _id doit être unique dans une collection — un _id dupliqué lève une erreur d'écriture. ordered:false permet à insertMany de continuer à insérer les documents restants après une erreur, améliorant le débit des chargements en masse.

mongodb
# insert a single document
db.users.insertOne({
  name: "Alice",
  email: "[email protected]",
  age: 30
})

# insert multiple documents
db.users.insertMany([
  { name: "Bob", age: 25 },
  { name: "Carol", age: 28 }
])

# insert with a custom _id
db.users.insertOne({ _id: 1, name: "Dave" })

# ordered insert (stops on error) vs unordered
db.users.insertMany(docs, { ordered: false })

Trouver / interroger des documents

find() retourne un curseur (évalué paresseusement) ; findOne() retourne un seul document ou null. La projection contrôle les champs retournés — on ne peut pas mélanger inclusion et exclusion (sauf _id). Utilisez 1 pour inclure, 0 pour exclure. countDocuments est précis ; l'ancien count() est déprécié pour les comptages filtrés.

mongodb
# find all documents
db.users.find()

# find with a filter
db.users.find({ age: 30 })
db.users.find({ "address.city": "NYC" })

# find one matching document
db.users.findOne({ name: "Alice" })

# projection: include/exclude fields
db.users.find({}, { name: 1, age: 1, _id: 0 })
db.users.find({}, { email: 0 })

# count matching documents
db.users.countDocuments({ age: { $gte: 18 } })

Mettre à jour des documents

updateOne/updateMany utilisent des opérateurs de mise à jour ($set, $inc, etc.) pour modifier des champs précis. replaceOne remplace tout le document sauf _id. upsert:true crée un nouveau document quand aucun ne correspond — utile pour les motifs « créer ou mettre à jour ». Utilisez toujours $set pour modifier des champs ; un objet nu remplace le document (comportement hérité).

mongodb
# update one document
db.users.updateOne(
  { name: "Alice" },
  { $set: { age: 31, status: "active" } }
)

# update many documents
db.users.updateMany(
  { status: "pending" },
  { $set: { status: "active" } }
)

# replace an entire document (keeps _id)
db.users.replaceOne(
  { name: "Alice" },
  { name: "Alice", age: 32, city: "NYC" }
)

# upsert: insert if no match found
db.users.updateOne(
  { name: "Eve" },
  { $set: { age: 22 } },
  { upsert: true }
)

Opérateurs de mise à jour

Les opérateurs de mise à jour modifient les champs atomiquement au niveau du document. $inc est concurrency-safe (pas de course read-modify-write). $min/$max ne mettent à jour que si la nouvelle valeur est plus petite/grande. $currentDate est pratique pour les timestamps « dernière modification ». Plusieurs opérateurs peuvent être combinés en une seule mise à jour.

mongodb
# $set and $unset
db.users.updateOne({n:"A"}, { $set: {age:30}, $unset: {temp:""} })

# $inc increments a numeric field
db.users.updateOne({n:"A"}, { $inc: {views: 1} })
db.users.updateOne({n:"A"}, { $inc: {balance: -50} })

# $rename a field
db.users.updateOne({n:"A"}, { $rename: {n: "name"} })

# $min / $max keep the smaller/larger value
db.users.updateOne({n:"A"}, { $min: {lowScore: 80} })

# $mul multiply the field value
db.users.updateOne({n:"A"}, { $mul: {price: 1.1} })

# $currentDate sets to current date
db.users.updateOne({n:"A"}, { $currentDate: {updatedAt: true} })

Supprimer des documents

deleteOne supprime la première correspondance ; deleteMany supprime toutes les correspondances. deleteMany({}) vide la collection mais garde les index (plus rapide que drop+recréer si vous voulez préserver les définitions d'index). findOneAndDelete retourne le document supprimé atomiquement. Les suppressions sont irréversibles — filtrez toujours soigneusement.

mongodb
# delete one matching document
db.users.deleteOne({ name: "Alice" })

# delete all matching documents
db.users.deleteMany({ status: "inactive" })

# delete all documents in a collection
db.users.deleteMany({})

# findAndDelete: return the deleted document
db.users.findOneAndDelete({ name: "Bob" })

# remove is deprecated, prefer deleteOne/deleteMany
db.users.remove({ name: "Bob" }, { justOne: true })

Opérateurs de mise à jour de tableaux

$push ajoute (duplicatas autorisés) ; $addToSet déduplique. $pull retire les éléments correspondant à une condition. L'opérateur positionnel ($) désigne le premier élément de tableau trouvé par la requête — essentiel pour mettre à jour un élément précis sans connaître son index. $[] met à jour tous les éléments du tableau.

mongodb
# $push append to an array
db.users.updateOne({n:"A"}, { $push: {tags: "new"} })

# $push with $each for multiple values
db.users.updateOne({n:"A"}, { $push: {tags: { $each: ["x","y"] } } })

# $addToSet adds only if not already present
db.users.updateOne({n:"A"}, { $addToSet: {tags: "x"} })

# $pull remove all matching array elements
db.users.updateOne({n:"A"}, { $pull: {tags: "x"} })

# $pop remove first (-1) or last (1) element
db.users.updateOne({n:"A"}, { $pop: {tags: 1} })

# update an array element by position
db.users.updateOne({}, { $set: {"tags.0": "first"} })
db.users.updateOne({"tags":"old"}, { $set: {"tags.$":"new"} })
03

Interroger des documents

Opérateurs de comparaison

Les opérateurs de comparaison sont le socle des requêtes. $in est bien plus efficace que plusieurs conditions $or sur le même champ. On peut combiner plusieurs opérateurs sur un champ (ex. $gte et $lte pour une plage). $exists:true trouve les documents avec le champ, $exists:false ceux qui en sont dépourvus.

mongodb
# $eq equal (same as direct value)
db.products.find({ price: { $eq: 100 } })

# $ne not equal
db.products.find({ price: { $ne: 100 } })

# $gt, $gte, $lt, $lte
db.products.find({ price: { $gte: 50, $lte: 200 } })

# $in matches any value in an array
db.products.find({ category: { $in: ["books", "music"] } })

# $nin not in array
db.products.find({ category: { $nin: ["books"] } })

# $exists check field presence
db.products.find({ discount: { $exists: true } })

Opérateurs logiques

Le AND implicite (virgule dans un filtre) est le plus courant et le plus efficace. Utilisez $and explicite seulement quand vous avez besoin de plusieurs conditions sur le même champ (le AND implicite sur un même champ écrase les conditions antérieures). $or fait des scans d'index séparés et fusionne les résultats — assurez-vous que les champs de $or sont indexés pour la performance.

mongodb
# $and (explicit, useful for same-field conditions)
db.users.find({ $and: [
  { age: { $gte: 18 } },
  { age: { $lte: 65 } }
]})

# $or matches if ANY condition is true
db.users.find({ $or: [
  { status: "active" },
  { vip: true }
]})

# $nor matches if NO condition is true
db.users.find({ $nor: [{ status: "active" }]})

# $not inverts a condition
db.users.find({ age: { $not: { $gt: 18 } } })

# implicit AND (comma-separated)
db.users.find({ age: { $gte: 18 }, status: "active" })

Opérateurs d'élément et d'évaluation

$type filtre par type BSON (utile pour des champs de types mixtes). $regex supporte des options comme 'i' (insensible à la casse) — mais une regex sans ancre de préfixe ne peut pas utiliser les index efficacement. $expr permet des comparaisons entre champs d'un document, ce que les opérateurs normaux ne savent pas faire. Utilisez $expr avec parcimonie car il peut contourner les index.

mongodb
# $type filter by BSON data type
db.users.find({ age: { $type: "int" } })
db.users.find({ age: { $type: ["int", "double"] } })

# $regex regular expression match
db.users.find({ name: { $regex: "^Al", $options: "i" } })

# $mod modulo operation
db.users.find({ age: { $mod: [2, 0] } })  # even ages

# $expr compare fields within a document
db.orders.find({ $expr: { $gt: ["$total", "$budget"] } })

# $jsonSchema validate against a schema
db.users.find({ $jsonSchema: {
  required: ["name", "email"]
}})

Opérateurs de requête sur tableaux

$all trouve les tableaux contenant toutes les valeurs spécifiées (indépendamment de l'ordre). $elemMatch est essentiel quand un même élément du tableau doit satisfaire plusieurs conditions simultanément (une requête simple matcherait des éléments différents). $size ne matche que les longueurs exactes — pas de $size avec plage ; précalculez et stockez plutôt la longueur dans un champ séparé.

mongodb
# $all: array contains ALL specified values
db.posts.find({ tags: { $all: ["mongo", "db"] } })

# $elemMatch: at least one element matches all conditions
db.students.find({ scores: { $elemMatch: {
  subject: "math", score: { $gte: 90 }
}}})

# $size: array of exact length
db.users.find({ tags: { $size: 3 } })

# match if array contains the value
db.posts.find({ tags: "mongo" })

# match a specific array index
db.users.find({ "scores.0": 95 })  # first score is 95

Méthodes de curseur et tri

skip+limit implémente la pagination mais skip devient lent pour de grands offsets (il parcourt tous les documents sautés). Pour la pagination profonde, utilisez le keyset : requête filtrée sur le champ de tri supérieur à la dernière valeur vue. sort() peut utiliser un index pour éviter le tri en mémoire — indexez toujours vos champs de tri sur les grandes collections.

mongodb
# limit and skip (pagination)
db.users.find().limit(10)
db.users.find().skip(20).limit(10)  # page 3

# sort: 1 ascending, -1 descending
db.users.find().sort({ age: 1, name: -1 })

# count results
db.users.find({active:true}).count()

# iterate the cursor in the shell
db.users.find().forEach(doc => print(doc.name))

# get a specific field's distinct values
db.users.distinct("city")
04

Indexation

Créer des index

Les index accélèrent drastiquement les requêtes mais ralentissent les écritures et consomment du disque. Les index mono-champ supportent les requêtes sur ce champ dans les deux sens de tri. Les index composés suivent la règle ESR (Égalité, Tri, Plage) pour un ordre optimal. Les index TTL suppriment automatiquement les documents après une durée — parfait pour sessions et logs.

mongodb
# create a single-field index
db.users.createIndex({ email: 1 })          # ascending
db.users.createIndex({ age: -1 })            # descending

# create a unique index
db.users.createIndex({ email: 1 }, { unique: true })

# create a compound index
db.users.createIndex({ lastName: 1, firstName: 1 })

# create a text index
db.posts.createIndex({ title: "text", body: "text" })

# create a TTL (time-to-live) index
db.sessions.createIndex({ createdAt: 1 },
  { expireAfterSeconds: 3600 })

# name an index explicitly
db.users.createIndex({ email: 1 }, { name: "email_idx" })

Voir et gérer les index

getIndexes liste tous les index avec leurs clés et options. hideIndex/unhideIndex permet de tester l'impact du retrait d'un index sans vraiment le supprimer — le planificateur ignore les index cachés. Si la performance reste identique, la suppression est sûre. Lancez toujours explain() avant et après un changement d'index.

mongodb
# list all indexes on a collection
db.users.getIndexes()

# total index size in bytes
db.users.totalIndexSize()

# drop an index by name
db.users.dropIndex("email_1")

# drop all indexes except _id
db.users.dropIndexes()

# hide an index (test impact before dropping)
db.users.hideIndex("email_1")
db.users.unhideIndex("email_1")

# check if queries use indexes
db.users.find({email:"[email protected]"}).explain("executionStats")

Types d'index spéciaux

Les index 2dsphere alimentent les requêtes geo ($near, $geoWithin). Les index Hashed supportent le sharding par hachage pour une distribution uniforme. Les index wildcard ($**) couvrent des noms de champs imprévisibles/variables — utiles pour les données polymorphes. Les index partiels n'indexent que les documents correspondants, économisant de l'espace quand on n'interroge qu'un sous-ensemble.

mongodb
# geospatial 2dsphere index (GeoJSON points)
db.places.createIndex({ location: "2dsphere" })
db.places.find({
  location: { $near: {
    $geometry: { type: "Point", coordinates: [-73.99, 40.73] },
    $maxDistance: 1000
  }}
})

# hashed index (for sharding)
db.users.createIndex({ user_id: "hashed" })

# wildcard index (index arbitrary field names)
db.products.createIndex({ "$**": 1 })

# partial index (only matching documents)
db.users.createIndex({ email: 1 },
  { partialFilterExpression: { active: true } })

Explain et plans de requête

explain() est l'outil de performance principal. COLLSCAN (scan de collection) signifie qu'aucun index n'a été utilisé — signal d'alarme sur les grandes collections. IXSCAN signifie qu'un index a été utilisé. totalDocsExamined >> nReturned indique un index médiocre (examiner beaucoup de documents pour en retourner peu). hint() force un index précis pour tester le choix du planificateur.

mongodb
# explain a query (basic)
db.users.find({age:30}).explain()

# explain with execution stats (timing)
db.users.find({age:30}).explain("executionStats")

# key fields in the output:
#   winningPlan.stage    -> COLLSCAN (bad) or IXSCAN (good)
#   totalDocsExamined    -> should be close to nReturned
#   executionTimeMillis  -> query duration
#   indexUsed            -> which index was chosen

# force a specific index (testing)
db.users.find({age:30}).hint("age_1")
db.users.find({age:30}).hint({age:1})

Bonnes pratiques d'indexation

La règle ESR (Égalité, Tri, Plage) est le principe le plus important de conception d'index composé : champs filtrés par égalité d'abord, puis champs de tri, puis champs de plage. Une covered query (tous les champs sont dans l'index) ne fetch jamais le document — la requête la plus rapide possible. Évitez les index que vous n'utilisez pas ; chacun ajoute un coût d'écriture.

mongodb
# ESR rule: Equality, Sort, Range for compound indexes
# equality fields first, then sort, then range
db.orders.createIndex({
  status: 1,        # Equality  (filter)
  date: 1,          # Sort      (order)
  amount: 1         # Range     (comparison)
})

# avoid over-indexing: each index slows writes
db.orders.getIndexes().length

# covered query: index satisfies query without fetching doc
db.users.createIndex({ name: 1, email: 1 })
db.users.find({ name: "A" }, { _id: 0, name: 1, email: 1 })

# background index build (deprecated in 4.2+, builds don't block)
db.users.createIndex({ name: 1 })  # non-blocking by default
05

Framework d'agrégation

Bases du pipeline d'agrégation

Le pipeline d'agrégation traite les documents par étapes successives. $match tôt dans le pipeline réduit l'ensemble de travail (et peut utiliser des index). $group est l'équivalent du GROUP BY SQL. $count est un raccourci de $group + $project. L'ordre compte : filtrer, puis grouper, puis trier, puis limiter.

mongodb
# a pipeline is an array of stages
db.orders.aggregate([
  { $match: { status: "shipped" } },
  { $group: { _id: "$customerId", total: { $sum: "$amount" } } },
  { $sort: { total: -1 } },
  { $limit: 10 }
])

# each stage transforms documents and passes them
# to the next stage

# count documents
db.orders.aggregate([
  { $match: { status: "shipped" } },
  { $count: "shippedCount" }
])

$match, $project et $limit

Placez toujours $match le plus tôt possible — il réduit les documents pour toutes les étapes suivantes et peut utiliser des index. $project remodèle les documents et calcule de nouveaux champs via des expressions. Renommer ou calculer des champs dans $project est courant avant $group. $unset est un raccourci pour exclure des champs.

mongodb
# $match filters documents (like find)
{ $match: { status: "active", age: { $gte: 18 } } }

# $project reshapes documents (1 include, 0 exclude)
{ $project: { name: 1, _id: 0, "address.city": 1 } }

# $project with computed fields
{ $project: {
  fullName: { $concat: ["$first", " ", "$last"] },
  ageNextYear: { $add: ["$age", 1] }
}}

# $limit and $skip
{ $limit: 10 }
{ $skip: 20 }

# $unset removes fields (inverse of $project)
{ $unset: "tempField" }

$group et accumulateurs

$group est l'étape d'agrégation cœur. _id spécifie la clé de groupement (null pour agréger tous les documents). $push construit un tableau de valeurs par groupe ; $addToSet déduplique. $first/$last se réfèrent à l'ordre des documents dans le groupe — faites $sort avant $group si l'ordre importe. La limite mémoire est 100 Mo par étape (utilisez allowDiskUse pour les grands jeux de données).

mongodb
# $group: group by a field and aggregate
{ $group: {
  _id: "$category",
  count: { $sum: 1 },
  totalRevenue: { $sum: "$amount" },
  avgPrice: { $avg: "$price" },
  minPrice: { $min: "$price" },
  maxPrice: { $max: "$price" },
  products: { $push: "$name" },     # array of values
  firstOrder: { $first: "$date" },
  lastOrder: { $last: "$date" }
}}

# group by multiple fields
{ $group: { _id: { category: "$cat", status: "$status" } } }

# group ALL documents together (_id: null)
{ $group: { _id: null, total: { $sum: "$amount" } } }

$lookup (jointures)

$lookup fait une left outer join — comme le LEFT JOIN SQL. Les données jointes sont placées dans un champ tableau nommé par 'as'. La forme pipeline permet de filtrer et transformer les documents joints. $unwind déconstruit les champs tableaux (un document de sortie par élément) — souvent utilisé après $lookup pour aplatir les résultats. Les jointures sont moins efficaces que les données embarquées dans MongoDB.

mongodb
# $lookup: join another collection (left outer join)
{ $lookup: {
  from: "orders",
  localField: "_id",
  foreignField: "customerId",
  as: "orders"
}}

# with pipeline (filtered/transformed join)
{ $lookup: {
  from: "orders",
  let: { custId: "$_id" },
  pipeline: [
    { $match: { $expr: { $eq: ["$customerId", "$$custId"] } } },
    { $project: { amount: 1, _id: 0 } }
  ],
  as: "recentOrders"
}}

# $unwind: flatten an array field into multiple docs
{ $unwind: "$orders" }

$unwind, $sort et $facet

$facet exécute plusieurs sous-pipelines sur la même entrée — parfait pour des tableaux de bord nécessitant plusieurs agrégations (top N, comptages, ventilations) en une requête. $bucket catégorise automatiquement les valeurs en plages. $unwind avec preserveNullAndEmptyArrays conserve les documents dont le tableau est vide ou absent — utile pour éviter des pertes de données dans les pipelines.

mongodb
# $unwind with preserveNullAndEmptyArrays
{ $unwind: {
  path: "$tags",
  preserveNullAndEmptyArrays: true
}}

# $sort within pipeline
{ $sort: { total: -1 } }

# $facet: run multiple pipelines in parallel
{ $facet: {
  "topCustomers": [{ $sort: {total:-1} }, { $limit: 5 }],
  "byCategory":   [{ $group: { _id: "$cat" } }],
  "totalCount":   [{ $count: "n" }]
}}

# $bucket: group into ranges automatically
{ $bucket: {
  groupBy: "$price",
  boundaries: [0, 50, 100, 500],
  default: "other",
  output: { count: { $sum: 1 } }
}}
07

Transactions

Transactions ACID

Les transactions multi-documents fournissent des garanties ACID à travers les collections (exige un replica set ou un cluster shardé). Passez la session à chaque opération de la transaction. commitTransaction rend les changements permanents et visibles ; abortTransaction annule tout. Gardez les transactions courtes — elles détiennent des verrous et peuvent affecter la performance.

mongodb
# multi-document transaction (replica set required)
const session = db.getMongo().startSession()
session.startTransaction()

try {
  db.accounts.updateOne(
    { name: "Alice" }, { $inc: { balance: -100 } }, { session }
  )
  db.accounts.updateOne(
    { name: "Bob" }, { $inc: { balance: 100 } }, { session }
  )
  session.commitTransaction()
} catch (e) {
  session.abortTransaction()
  print("Transaction aborted: " + e)
} finally {
  session.endSession()
}

Read/Write concern des transactions

Le read concern contrôle la « fraîcheur » et la cohérence des lectures. 'snapshot' donne une vue transactionnellement cohérente entre shards — idéal pour le reporting. Le write concern contrôle la durabilité : w:majority garantit la réplication avant ack (survit à un failover de primaire) ; j:true attend le flush du journal. Des concerns plus élevés sont plus sûrs mais plus lents.

mongodb
# set transaction-level read/write concern
session.startTransaction({
  readConcern: { level: "snapshot" },
  writeConcern: { w: "majority", j: true, wtimeout: 5000 }
})

# read concern levels:
#   "local"      - sees latest local data (default)
#   "majority"   - committed, replicated to majority
#   "snapshot"   - consistent snapshot across shards

# write concern levels:
#   { w: 1 }             - ack from primary (default)
#   { w: "majority" }    - ack from majority of members
#   { j: true }          - wait for journal write

Logique de retry et erreurs

MongoDB marque les erreurs retryables avec errorLabels : TransientTransactionError (rejouer toute la transaction) et UnknownCommitResult (rejouer seulement le commit). Les drivers de production offrent un retry intégré. Concevez toujours les transactions pour être idempotentes quand possible. Évitez les transactions longues qui détiennent des verrous et bloquent d'autres opérations.

mongodb
# transactions can fail with TransientTransactionError
# retry the whole transaction on these errors

function runTransaction(txnFunc) {
  while (true) {
    const session = db.getMongo().startSession()
    try {
      session.startTransaction()
      txnFunc(session)
      session.commitTransaction()
      return
    } catch (e) {
      session.abortTransaction()
      if (e.errorLabels &&
          e.errorLabels.includes("TransientTransactionError")) {
        continue  // retry
      }
      throw e   // non-retryable error
    } finally {
      session.endSession()
    }
  }
}

Opérations mono-document atomiques

Les opérations mono-document sont atomiques par défaut — pas de transaction nécessaire. findOneAndUpdate/findOneAndReplace/findOneAndDelete retournent le document atomiquement (parfait pour générer des IDs séquentiels). Pour beaucoup de charges, embarquer les données liées dans un document et utiliser des opérateurs atomiques ($inc, $push) évite entièrement les transactions multi-documents.

mongodb
# single-document operations are ALWAYS atomic
db.counters.updateOne(
  { _id: "pageViews" },
  { $inc: { count: 1 } }
)

# findAndModify: atomically find & update, return the doc
db.sequences.findOneAndUpdate(
  { _id: "orderId" },
  { $inc: { seq: 1 } },
  { returnNewDocument: true }
)

# atomic upsert (create-or-increment)
db.counters.updateOne(
  { _id: "visits", date: "2025-01-01" },
  { $inc: { count: 1 } },
  { upsert: true }
)

# use $expr for conditional atomic updates
db.products.updateMany(
  { $expr: { $lt: ["$stock", "$reorderLevel"] } },
  { $set: { needsRestock: true } }
)

Two-Phase Commit (motif)

Le motif two-phase commit simule des transactions distribuées sans transactions multi-docs natives. Il suit un état « pending » pour qu'un processus de récupération puisse reprendre ou annuler en cas de crash au milieu d'un transfert. Utilisez plutôt les transactions natives quand disponibles — ce motif est complexe et error-prone, conservé surtout à des fins pédagogiques et legacy.

mongodb
# pattern for atomic transfers without transactions
# (pre-4.0 compatibility, or cross-system transfers)

# 1. create a pending transaction document
db.transactions.insertOne({
  _id: "t1", from: "Alice", to: "Bob", amount: 100, state: "pending"
})

# 2. debit source
db.accounts.updateOne(
  { name: "Alice", pendingTransactions: { $ne: "t1" } },
  { $inc: { balance: -100 }, $push: { pendingTransactions: "t1" } }
)

# 3. credit destination
db.accounts.updateOne(
  { name: "Bob", pendingTransactions: { $ne: "t1" } },
  { $inc: { balance: 100 }, $push: { pendingTransactions: "t1" } }
)

# 4. mark transaction done
db.transactions.updateOne({ _id: "t1" }, { $set: { state: "done" } })

# 5. clean up pending references
db.accounts.updateMany({},
  { $pull: { pendingTransactions: "t1" } })
08

Modélisation des données

Embarquer vs référencer

La décision cardinale de modélisation MongoDB : embarquer pour des données accédées ensemble et changeant rarement ; référencer pour des données grandes, partagées ou mises à jour indépendamment. Embarquez quand la relation « has-a » est exclusive (les adresses d'un utilisateur). Référencez quand les données sont réutilisées (un produit dans beaucoup de commandes) ou croissent sans borne (des millions d'entrées de log d'un utilisateur).

mongodb
# EMBED: store related data in one document
db.users.insertOne({
  name: "Alice",
  addresses: [
    { city: "NYC", zip: "10001" },
    { city: "LA", zip: "90001" }
  ]
})
# Pros: single read, atomic update
# Cons: document size limit (16MB), data duplication

# REFERENCE: store IDs, join with $lookup
db.users.insertOne({ name: "Alice" })
db.orders.insertOne({
  customerId: ObjectId("..."),
  amount: 100
})
# Pros: no duplication, independent updates
# Cons: needs joins, more queries

Relations un-à-plusieurs

Pour des relations « peu nombreuses », embarquez. Pour « beaucoup », référencez depuis l'enfant (ID parent sur chaque enfant). Pour « très nombreuses » (millions), utilisez le bucket pattern : groupez les documents enfants en buckets possédés par le parent (ex. par mois) pour équilibrer taille de document et vitesse de requête. Cela évite à la fois les tableaux sans borne et l'excès de documents enfants.

mongodb
# FEW: embed (e.g., a few addresses per user)
db.users.insertOne({
  name: "Alice",
  addresses: [{ city: "NYC" }, { city: "LA" }]
})

# MANY: reference with parent pointer
db.posts.insertOne({ title: "Hello", authorId: ObjectId("...") })

# VERY MANY: reference from parent (bucket pattern)
db.users.updateOne(
  { _id: userId },
  { $push: { postIds: postId } }   # beware 16MB limit
)

# BUCKET pattern for time series (thousands of items)
db.buckets.insertOne({
  ownerId: userId,
  date: "2025-01",
  measurements: [ {t: 1, v: 30}, {t: 2, v: 31} ]
})

Relations plusieurs-à-plusieurs

Pour le plusieurs-à-plusieurs, choisissez selon les motifs de requête et la taille des données. Les tableaux bilatéraux sont rapides mais exigent une double maintenance. Une collection de jonction (table de mapping) est la plus flexible et passe le mieux à l'échelle — elle peut stocker des métadonnées de relation (date d'inscription, note) et évite d'enfler les documents parents.

mongodb
# option 1: arrays of ObjectIds on both sides
db.students.insertOne({ name: "Alice", courseIds: [c1, c2] })
db.courses.insertOne({ name: "Math", studentIds: [s1, s2] })

# option 2: one side references (smaller side)
db.students.insertOne({ name: "Alice", courseIds: [c1, c2] })

# option 3: mapping/junction collection
db.enrollments.insertOne({
  studentId: s1,
  courseId: c1,
  enrolledAt: ISODate(),
  grade: "A"
})

# query: find a student's courses
db.enrollments.find({ studentId: s1 })

Motifs de conception de schéma

L'Attribute Pattern gère les entités à attributs variables (produits avec specs différents) — évite les champs sparses et permet des attributs dynamiques. Le Polymorphic Pattern stocke des formes liées mais différentes dans une même collection avec un discriminant de type. L'Outlier Pattern traite les documents exceptionnels (une célébrité avec des millions de followers) par référence au lieu d'embarquer.

mongodb
# ATTRIBUTE PATTERN: flexible attributes (e.g., products)
db.products.insertOne({
  name: "Laptop",
  attributes: [
    { k: "cpu", v: "i7" },
    { k: "ram", v: 16 }
  ]
})
# query: db.products.find({ "attributes.k": "cpu", "attributes.v": "i7" })

# POLYMORPHIC PATTERN: one collection, type discriminator
db.events.insertMany([
  { type: "click", url: "/home", userId: 1 },
  { type: "purchase", orderId: 99, total: 50 }
])

# OUTLIER PATTERN: cap large lists
db.users.updateOne({n:"A"}, { $set: { reviews: "see reviews collection" } })

Validation de schéma

La validation de schéma impose la structure des documents à l'écriture — la réponse de MongoDB aux schémas fixes. validationLevel 'strict' valide toutes les écritures ; 'moderate' ne valide que les insertions et les mises à jour complètes. validationAction 'error' rejette les documents invalides ; 'warn' logue mais les accepte. La validation complète (sans remplacer) la validation applicative.

mongodb
# add a JSON schema validator to a collection
db.createCollection("users", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["name", "email"],
      properties: {
        name: { bsonType: "string", maxLength: 100 },
        email: { bsonType: "string", pattern: "^\S+@\S+$" },
        age: { bsonType: "int", minimum: 0, maximum: 150 },
        role: { enum: ["admin", "user", "guest"] }
      }
    }
  },
  validationLevel: "strict",
  validationAction: "error"
})

# add validation to an existing collection
db.runCommand({ collMod: "users", validator: { ... } })

# check existing validation rules
db.getCollectionInfos({ name: "users" })
09

Replica sets

Bases des replica sets

Un replica set apporte la haute disponibilité et le scaling en lecture. Un seul membre est primary (accepte les écritures) ; les autres répliquent de façon asynchrone. Si le primaire échoue, une élection promeut automatiquement un secondaire. Un nombre impair de membres votants (3 minimum) évite les égalités d'élection. rs.status() montre la santé, l'état et le lag de réplication de chaque membre.

mongodb
# a replica set = 1 primary + N secondaries
# all writes go to the primary; secondaries replicate

# initiate a replica set
rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "host1:27017" },
    { _id: 1, host: "host2:27017" },
    { _id: 2, host: "host3:27017" }
  ]
})

# check replica set status
rs.status()
rs.conf()

# step down the primary (force an election)
rs.stepDown(60)

# add a new member
rs.add("host4:27017")
rs.remove("host4:27017")

Read preference

La read preference équilibre cohérence vs charge. primary garantit la lecture des dernières écritures. secondary/secondaryPreferred déleste le primaire mais les données peuvent être périmées (lag de réplication, typiquement millisecondes). nearest minimise la latence — idéal pour des apps géographiquement distribuées. Les charges analytiques/reporting devraient lire sur les secondaires.

mongodb
# control where reads are routed
# primary (default) - always read from primary (strongest consistency)
db.users.find().readPref("primary")

# primaryPreferred - primary if available, else secondary
db.users.find().readPref("primaryPreferred")

# secondary - only secondaries (may be stale)
db.users.find().readPref("secondary")

# secondaryPreferred - prefer secondaries to offload primary
db.users.find().readPref("secondaryPreferred")

# nearest - lowest latency member
db.users.find().readPref("nearest")

# set in connection string
mongodb://host1:27017/mydb?replicaSet=rs0&readPreference=secondary

Write concern

Le write concern échange vitesse contre sûreté. w:1 ack dès que le primaire écrit (rapide mais risque de perte si le primaire crashe avant réplication). w:majority garantit la réplication de l'écriture — survit à une panne d'un nœud (recommandé pour les données importantes). j:true attend un flush du journal sur disque. Réglez un défaut raisonnable au niveau du cluster.

mongodb
# control how durable a write must be before ack
# w: 1 - primary acks (default, fastest, least safe)
db.users.insertOne(doc, { writeConcern: { w: 1 } })

# w: "majority" - majority of members confirmed
db.users.insertOne(doc, { writeConcern: { w: "majority" } })

# j: true - wait for journal flush (survives crash)
db.users.insertOne(doc, { writeConcern: { w: 1, j: true } })

# wtimeout - max wait time in ms
db.users.insertOne(doc, {
  writeConcern: { w: "majority", wtimeout: 5000 }
})

# set default write concern for the cluster
db.adminCommand({
  setDefaultRWConcern: { defaultWriteConcern: { w: "majority" } }
})

Arbiters et élection

Les arbiters fournissent un vote pour atteindre la majorité sans stocker de données — utiles pour des déploiements à deux nœuds, mais un troisième nœud de données est préférable. Les membres priority 0 ne deviennent jamais primaires (bien pour des nœuds d'analytics ou de DR dédiés). Les membres hidden sont exclus de la read preference 'nearest' et sont idéals pour les backups. Les membres delayed prennent du retard, permettant de récupérer des suppressions accidentelles.

mongodb
# an arbiter votes in elections but holds no data
rs.addArb("host5:27017")

# useful to break ties in even-member sets (e.g., 2 data + 1 arbiter)
# but prefer 3 data members for durability

# force a member to never become primary (priority 0)
rs.conf().members[1].priority = 0
rs.reconfig(rs.conf())

# hidden member: not visible to clients, used for analytics/backup
rs.conf().members[2].hidden = true
rs.conf().members[2].priority = 0
rs.reconfig(rs.conf())

# delayed member: lags behind (insurance against human errors)
rs.conf().members[3].secondaryDelaySecs = 3600
rs.conf().members[3].priority = 0

Oplog et internals de réplication

L'oplog (journal des opérations) est une collection capped enregistrant chaque écriture — les secondaires rejouent ces entrées dans l'ordre pour répliquer. Si un secondaire prend du retard au-delà de la fenêtre de l'oplog, il exige une resynchronisation complète. printReplicationInfo montre la plage temporelle de l'oplog ; printSecondaryReplicationInfo montre le lag de chaque secondaire. Des oplogs plus grands tolèrent des indisponibilités plus longues.

mongodb
# the oplog is a capped collection of all writes
use local
db.oplog.rs.stats()
db.oplog.rs.find().sort({ $natural: -1 }).limit(5)

# each oplog entry is an idempotent operation
# { ts: ..., op: "i", ns: "mydb.users", o: { ... } }

# check replication lag
rs.printReplicationInfo()   # primary's oplog window
rs.printSecondaryReplicationInfo()  # each secondary's lag

# resync a stale secondary (full re-sync)
rs.syncFrom("host2:27017")

# change the oplog size (MongoDB 4.4+)
db.adminCommand({ replSetResizeOplog: 1, size: 16384 })  # MB
10

Sharding

Bases du sharding

Le sharding met à l'échelle une collection horizontalement sur plusieurs shards. La shard key détermine la distribution des données et est immuable après sharding. Le sharding hashé distribue uniformément (bien pour les clés monotones croissantes comme ObjectId) ; le sharding par plages permet des requêtes ciblées mais peut créer des hotspots. Choisissez la shard key avec soin — on ne la change pas facilement ensuite.

mongodb
# sharding distributes data across multiple machines
# requires: config servers + shard replica sets + mongos router

# enable sharding on a database
sh.enableSharding("mydb")

# shard a collection (index on shard key required first)
sh.shardCollection("mydb.users", { userId: 1 })

# hash-based sharding (even distribution)
db.users.createIndex({ userId: "hashed" })
sh.shardCollection("mydb.users", { userId: "hashed" })

# view shard status
sh.status()
sh.addShard("rs1/host1:27017,host2:27017")

# balancer moves chunks between shards automatically
sh.startBalancer()
sh.stopBalancer()

Choix de la shard key

La shard key est la décision de sharding la plus critique. Elle doit supporter vos requêtes courantes (les requêtes sans la shard key touchent tous les shards — scatter-gather). Une cardinalité élevée prévient les jumbo chunks immobiles. Les clés monotones (timestamps, ObjectIds) font que toutes les insertions touchent un seul shard — utilisez le sharding hashé pour elles. Les clés composées devraient commencer par le champ le plus sélectif.

mongodb
# GOOD shard key properties:
# - high cardinality (many distinct values)
# - low frequency (no single value dominates)
# - non-monotonic (avoids hot shards) OR use hashed

# hashed shard key (even distribution)
sh.shardCollection("mydb.logs", { _id: "hashed" })

# ranged shard key (enables targeted queries)
sh.shardCollection("mydb.events", { region: 1, date: 1 })

# compound shard key
sh.shardCollection("mydb.orders", { customerId: 1, orderId: 1 })

# check chunk distribution
db.getSiblingDB("config").chunks.find({ ns: "mydb.users" })

# see data distribution per shard
db.users.getShardDistribution()

Zones et sharding tag-aware

Les zones (sharding tag-aware) routent des plages de données précises vers des shards précis — permettant la conformité de résidence des données (le GDPR exige les données UE en UE), la géolocalité (lectures régionaux rapides) ou des niveaux de matériel (données chaudes sur SSD, froides sur HDD). Le balancer respecte les plages de zones lors de la migration des chunks. Définissez d'abord les tags de shard, puis les plages.

mongodb
# tag shards by region (data locality / compliance)
sh.addShardTag("shard-us-east", "US")
sh.addShardTag("shard-eu", "EU")

# associate a key range with a tag
sh.addTagRange(
  "mydb.users",
  { region: "US", _id: MinKey },
  { region: "US", _id: MaxKey },
  "US"
)
sh.addTagRange(
  "mydb.users",
  { region: "EU", _id: MinKey },
  { region: "EU", _id: MaxKey },
  "EU"
)

# the balancer migrates tagged data to tagged shards
# useful for data residency (GDPR) and geo-locality

Gestion des chunks

Les chunks sont l'unité de déplacement de données entre shards. Le balancer découpe et migre automatiquement les chunks pour garder les shards équilibrés. Les jumbo chunks dépassent la limite de taille et ne peuvent pas migrer — évitez-les avec une bonne cardinalité de shard key. La taille de chunk par défaut de 128 Mo équilibre vitesse de migration et overhead. Les opérations manuelles sur les chunks sont pour le dépannage, pas le routine.

mongodb
# chunks are ranges of shard key values
# default chunk size: 128MB (configurable)

# view chunks for a collection
db.getSiblingDB("config").chunks.find({ ns: "mydb.users" })

# manually move a chunk (testing)
sh.moveChunk("mydb.users", { userId: 100 }, "shard2")

# split a chunk at a specific value
sh.splitAt("mydb.users", { userId: 1000 })

# merge contiguous chunks
sh.mergeChunks("mydb.users",
  { userId: MinKey },
  { userId: 1000 }
)

# find chunks too large to migrate (jumbo chunks)
sh.status(true)   # verbose

Composants d'un cluster shardé

Un cluster shardé a trois composants : les config servers (métadonnées, déployés en replica set), les routeurs mongos (routeurs de requêtes sans état auxquels les clients se connectent), et les shards (chacun un replica set détenant un sous-ensemble des données). Les clients ne se connectent jamais directement aux shards. Retirer un shard déclenche la migration des données vers les shards restants — un processus lent à surveiller.

mongodb
# config servers store metadata and routing info
# (deploy as a 3-member replica set)
# config server connection string:
# mongodb://cfg1:27019,cfg2:27019,cfg3:27019/config?replicaSet=cfgRS

# mongos is the query router (stateless, scale horizontally)
# clients connect to mongos, not shards directly
mongos --configdb cfgRS/cfg1:27019,cfg2:27019,cfg3:27019

# each shard is a replica set
sh.addShard("shardRS1/s1a:27017,s1b:27017,s1c:27017")
sh.addShard("shardRS2/s2a:27017,s2b:27017,s2c:27017")

# check cluster status
sh.status()

# remove a shard (migrates its data first)
db.adminCommand({ removeShard: "shardRS2" })
11

Sécurité et authentification

Authentification et utilisateurs

L'authentification vérifie l'identité. Créez l'utilisateur admin avant d'activer l'auth, sinon vous serez verrouillé dehors. Les rôles intégrés vont du read-only à l'admin complet. Utilisez passwordPrompt() dans le shell pour éviter les mots de passe en clair dans l'historique. Chaque utilisateur est rattaché à une base mais peut avoir des rôles sur d'autres bases. Activez TLS en production (net.tls.mode).

mongodb
# enable auth: start mongod with --auth
# or set security.authorization: "enabled" in config

# create the first admin user (before enabling auth)
use admin
db.createUser({
  user: "admin",
  pwd: passwordPrompt(),   // prompts securely
  roles: [ { role: "userAdminAnyDatabase", db: "admin" },
           { role: "readWriteAnyDatabase", db: "admin" } ]
})

# create a user for a specific database
use mydb
db.createUser({
  user: "appUser",
  pwd: passwordPrompt(),
  roles: [ { role: "readWrite", db: "mydb" } ]
})

# authenticate as a user
db.auth("appUser", "password")

Rôles intégrés et rôles personnalisés

Les rôles intégrés couvrent les cas courants ; les rôles personnalisés permettent le moindre privilège. Les privilèges associent une ressource (base/collection) à des actions autorisées (find, insert, update, etc.). Accordez le minimum nécessaire — un utilisateur de reporting n'a besoin que de 'find' sur des collections précises. Les rôles personnalisés sont stockés dans la base admin et réutilisables entre utilisateurs.

mongodb
# built-in roles:
#   read, readWrite, dbAdmin, dbOwner, userAdmin  (per database)
#   readAnyDatabase, readWriteAnyDatabase,         (all databases)
#   userAdminAnyDatabase, dbAdminAnyDatabase
#   root (superuser), clusterAdmin, backup, restore

# create a custom role with fine-grained privileges
db.createRole({
  role: "analyst",
  privileges: [
    { resource: { db: "mydb", collection: "reports" },
      actions: ["find"] },
    { resource: { db: "mydb", collection: "" },
      actions: ["listCollections"] }
  ],
  roles: []
})

# grant a role to a user
db.grantRolesToUser("appUser", [{ role: "analyst", db: "mydb" }])
db.revokeRolesFromUser("appUser", [{ role: "analyst", db: "mydb" }])

Chiffrement TLS/SSL

TLS chiffre les données en transit — obligatoire en production. requireTLS rejette les connexions non TLS. Pour une PKI interne, utilisez l'authentification par certificat x.509 (pas de mots de passe — le certificat EST le credential). La base $external stocke les utilisateurs x.509. Utilisez toujours une vraie CA (ou CA interne) en production ; les certificats auto-signés sont pour les tests seulement.

mongodb
# enable TLS in mongod.conf
net:
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/mongodb/server.pem
    CAFile: /etc/mongodb/ca.pem

# connect with TLS and verify the server cert
mongosh "mongodb://host:27017/mydb" \
  --tls --tlsCAFile /etc/mongodb/ca.pem

# connect with a client certificate (x.509 auth)
mongosh "mongodb://host:27017/mydb" \
  --tls --tlsCertificateKeyFile client.pem \
  --tlsCAFile ca.pem \
  --authenticationMechanism MONGODB-X509 \
  --authenticationDatabase '$external'

# generate a self-signed cert for testing
openssl req -x509 -newkey rsa:4096 -nodes \
  -keyout server.key -out server.crt -days 365

Réseau et audit

bindIp limite les interfaces réseau sur lesquelles MongoDB écoute — n'exposez jamais MongoDB directement à Internet (bindIp: 0.0.0.0 + sans auth a causé d'innombrables breaches). L'audit (Enterprise seulement) logue les opérations sensibles à la sécurité pour la conformité. L'édition community peut utiliser des outils OS (auditd) ou du logging applicatif en alternative.

mongodb
# restrict network interface in mongod.conf
net:
  bindIp: 127.0.0.1,10.0.0.5    # never 0.0.0.0 in production
  port: 27017

# enable auditing (enterprise feature)
auditLog:
  destination: file
  format: JSON
  path: /var/log/mongodb/audit.log
  filter: '{ atype: { $in: ["authenticate","createCollection","dropDatabase"] } }'

# view current authentication mechanisms
db.runCommand({ getCmdLineOpts: 1 })

# enable FIPS mode (government compliance)
setParameter:
  fipsMode: true

Chiffrement au niveau champ (CSFLE)

CSFLE chiffre les champs sensibles côté client pour que serveur, backups et logs ne contiennent jamais de texte en clair — la protection des données la plus forte. Le chiffrement déterministe supporte les requêtes d'égalité ; le chiffrement aléatoire est plus sûr mais non interrogeable. L'auto-encryption (via un schéma de driver) est transparente pour le code applicatif. Les clés de chiffrement sont gérées dans un KMS (AWS KMS, clé locale, etc.).

mongodb
# Client-Side Field Level Encryption encrypts fields
# before sending to the server — server never sees plaintext

# define a data key in the key vault
const clientEncryption = db.getMongo().getClientEncryption()
const keyId = clientEncryption.createDataKey(
  "local", { keyAltNames: ["mainKey"] }
)

# encrypt a field explicitly
const ssn = clientEncryption.encrypt(
  keyId, "123-45-6789", "deterministic"
)

# store encrypted, query with encrypted value
db.patients.insertOne({ name: "Alice", ssn: ssn })
db.patients.find({
  ssn: clientEncryption.encrypt(keyId, "123-45-6789", "deterministic")
})

# automatic CSFLE uses a schema to encrypt per a JSON schema
# { encryptMetadata: { keyId: [keyId], algorithm: "AEAD_AES_256_CBC..." } }
12

Backup et restauration

mongodump et mongorestore

mongodump crée un backup logique (fichiers BSON) — portable mais lent pour les grands jeux de données et non ponctuellement cohérent entre collections sans --oplog. --drop supprime les collections existantes avant restauration. --archive + --gzip produisent un unique fichier compressé. Pour les backups de production volumineux, préférez les snapshots filesystem ou Percona Backup plutôt que mongodump.

mongodb
# dump an entire database
mongodump --db=mydb --out=/backup/$(date +%F)

# dump a single collection
mongodump --db=mydb --collection=users --out=/backup

# dump with a query filter
mongodump --db=mydb --collection=logs \
  --query='{"date":{"$gte":{"$date":"2025-01-01T00:00:00Z"}}}'

# compress the output archive
mongodump --archive=/backup/full.gz --gzip

# restore from a dump
mongorestore --db=mydb --drop /backup/2025-01-01/mydb
mongorestore --archive=/backup/full.gz --gzip

mongoexport et mongoimport

mongoexport/mongoimport travaillent en JSON/CSV — pour l'échange de données avec d'autres systèmes, pas pour les backups (ils perdent les types BSON comme ObjectId et la précision des dates). Pour les backups, utilisez mongodump. Les exports CSV sont parfaits pour tableurs et outils BI. Spécifiez toujours --fields pour un ordre de colonnes CSV prévisible. Les exports JSON sont limités à un document par ligne par défaut (--jsonArray pour un seul tableau).

mongodb
# export to JSON (human-readable)
mongoexport --db=mydb --collection=users \
  --out=users.json

# export to CSV
mongoexport --db=mydb --collection=users \
  --type=csv --fields=name,email,age --out=users.csv

# export with a query filter
mongoexport --db=mydb --collection=users \
  --query='{"status":"active"}' --out=active.json

# import from JSON
mongoimport --db=mydb --collection=users --file=users.json

# import from CSV with header row
mongoimport --db=mydb --collection=users \
  --type=csv --headerline --file=users.csv

Snapshots filesystem

Les snapshots filesystem sont la méthode de backup la plus rapide pour les grands jeux de données — ils capturent tout le répertoire de données de façon cohérente. fsyncLock bloque brièvement les écritures et flush sur disque pour que le snapshot soit cohérent. Les snapshots sont quasi instantanés quelle que soit la taille des données. La restauration se réduit à copier les fichiers — bien plus rapide que mongorestore. Fonctionne au mieux sur LVM, ZFS ou du stockage bloc cloud (snapshots EBS).

mongodb
# snapshot the dbPath volume for a consistent backup
# 1. flush writes to disk and lock (brief)
db.fsyncLock()

# 2. take a filesystem snapshot (LVM, ZFS, EBS, etc.)
lvcreate --snapshot --size 1G --name mongosnap /dev/vg/data

# 3. unlock the database
db.fsyncUnlock()

# 4. mount the snapshot and copy or back it up
mount /dev/vg/mongosnap /mnt/snap
rsync -a /mnt/snap/ /backup/

# restore: stop mongod, replace dbPath, start mongod
# (fastest restore method for large datasets)

Restauration ponctuelle (oplog)

La restauration ponctuelle (PITR) reconstruit l'état de la base à un instant précis — essentielle après des suppressions accidentelles ou de mauvaises migrations. Prenez des backups de base réguliers avec --oplog, puis rejouez l'oplog jusqu'au timestamp désiré (--oplogLimit s'arrête juste avant une mauvaise opération). La PITR exige un replica set (l'oplog n'existe que sur les membres d'un replica set).

mongodb
# 1. take a base backup (snapshot or mongodump --oplog)
mongodump --archive=/backup/base.gz --oplog --gzip

# 2. note the time of the accident
# 3. replay the oplog up to just before the error

# dump the oplog from a secondary
mongodump --db=local --collection=oplog.rs \
  --query='{"ts":{"$gt":{"$timestamp":{"t":1700000000,"i":1}}}}' \
  --out=/oplog_dump

# restore the base backup, then replay oplog
mongorestore --archive=/backup/base.gz --oplogReplay \
  --oplogLimit=1700000123:1   # stop before this timestamp

# for a running replica set, use mongorestore --oplogReplay
# with a BSON oplog file

Backup Atlas et options cloud

MongoDB Atlas offre des backups continus gérés avec restauration ponctuelle — le plus simple pour les déploiements cloud. Percona Backup for MongoDB (PBM) est l'outil de backup open-source de référence pour les clusters auto-hébergés, supportant les backups physiques et la PITR sur replica sets et clusters shardés. Testez toujours vos procédures de restauration — un backup que vous ne pouvez pas restaurer n'est pas un backup.

mongodb
# MongoDB Atlas: continuous backups with PITR
# configured via UI or Atlas CLI:
atlas backups policies create [clusterId] ...

# on-demand snapshot
atlas backups snapshots create [clusterId] \
  --description "pre-migration" \
  --retentionDays 7

# restore an Atlas snapshot
atlas backups restores start [clusterId] \
  --snapshotId [snapId] \
  --deliveryType automated \
  --targetClusterName [target]

# Percona Backup for MongoDB (PBM) — open source
pbm backup --type=physical
pbm restore [snapshotName]
pbm pitr restore --time "2025-01-15T14:30:00"
13

Performance et optimisation

Profiler les requêtes lentes

Le profiler de base logue les opérations plus lentes que slowms (défaut 100 ms) dans system.profile (une collection capped). Le niveau 2 logue tout — utile pour déboguer mais impacte la performance. Regardez millis (durée), nreturned (documents retournés) et docsExamined pour repérer les requêtes inefficaces. Désactivez le profiling une fois terminé.

mongodb
# enable the database profiler
# levels: 0=off, 1=slow ops only, 2=all ops
db.setProfilingLevel(1, { slowms: 100 })

# view profiled operations
db.system.profile.find().sort({ ts: -1 }).limit(5)

# find the slowest operations
db.system.profile.find({ millis: { $gt: 1000 } })
  .sort({ millis: -1 })

# profile a specific collection
db.system.profile.find({ ns: "mydb.users" })

# get current profiling level
db.getProfilingStatus()

# clear the profile collection
db.system.profile.drop()

explain() en profondeur

explain() est votre outil de réglage principal. COLLSCAN signifie un scan complet de collection — ajoutez un index. Le rapport docsExamined/nReturned est la métrique d'efficacité clé : si vous examinez 10000 docs pour en retourner 10, votre index est mauvais. allPlansExecution montre pourquoi le planificateur a choisi son plan. Indexez les champs d'égalité, de tri et de plage de votre requête (règle ESR).

mongodb
# three verbosity modes
db.users.find({age:30}).explain("queryPlanner")     # plan only
db.users.find({age:30}).explain("executionStats")    # + timing
db.users.find({age:30}).explain("allPlansExecution") # + rejected plans

# key metrics to check:
#   winningPlan.stage: COLLSCAN (bad) vs IXSCAN (good)
#   totalKeysExamined: index entries scanned
#   totalDocsExamined: documents fetched
#   nReturned: documents returned
#   executionTimeMillis: total time
#   works: number of work units

# ideal ratio: docsExamined ≈ nReturned
# if docsExamined >> nReturned -> missing or bad index

Working set et mémoire

La performance dépend du working set (données fréquemment accédées) qui tient en RAM. Si wiredTiger.cache « pages read into cache » est élevé, vous tapez le disque — ajoutez de la RAM ou des index pour réduire les scans. mongotop montre quelles collections sont chaudes en I/O ; mongostat montre les taux de requête/insertion/mise à jour et les faults. compact récupère l'espace disque gaspillé par les documents supprimés/mis à jour.

mongodb
# check the working set size
db.serverStatus().wiredTiger.cache
# look at: "maximum bytes configured", "current bytes"
#          "pages requested from disk" vs "pages read into cache"

# check storage stats
db.stats()
db.users.stats()
db.users.totalSize()   # data + index size in bytes

# mongotop: time spent reading/writing per collection
mongotop 30   # every 30 seconds

# mongostat: live server stats
mongostat --rowcount 10  # 10 iterations

# compact a collection (reclaims disk, blocks writes pre-4.4)
db.runCommand({ compact: "users" })

Pooling de connexions

Chaque connexion MongoDB consomme de la mémoire serveur — des milliers de connexions dégradent la performance. Utilisez le pooling (les drivers maintiennent un pool réutilisable) avec maxPoolSize réglé selon votre charge (50-100 est typique). Partagez un seul MongoClient dans toute l'app — n'en créez jamais un par requête. Réglez maxIdleTimeMS pour recycler les connexions périmées derrière les load balancers.

mongodb
# each connection consumes memory (~1MB) on the server
# limit connections in the driver's connection string
mongodb://host:27017/mydb?maxPoolSize=50

# Node.js driver example
const { MongoClient } = require("mongodb")
const client = new MongoClient(uri, {
  maxPoolSize: 50,        // max connections
  minPoolSize: 5,         // keep-alive connections
  maxIdleTimeMS: 30000,   // close idle conns after 30s
  serverSelectionTimeoutMS: 5000
})

# view current connections on the server
db.serverStatus().connections
# { current: 120, available: 880, totalCreated: 200 }

Écritures en masse et tailles de batch

Les écritures en masse regroupent les opérations en un seul aller-retour — bien plus rapide que des ops individuelles. unordered:true maximise le débit (continue après erreurs, parallélise sur clusters shardés). Pour les gros imports, batchez par groupes de 1000-5000 documents pour équilibrer mémoire et aller-retours. insertMany avec ordered:false est le moyen le plus rapide de charger des données.

mongodb
# ordered bulk write (stops on first error)
db.users.bulkWrite([
  { insertOne: { document: { name: "A" } } },
  { updateOne: { filter: {n:"B"}, update: {$set:{age:1}} } },
  { deleteOne: { filter: { n: "C" } } }
], { ordered: true })

# unordered bulk write (continues on errors, faster)
db.users.bulkWrite(ops, { ordered: false })

# insertMany is a bulk insert — batch large loads
const docs = Array.from({length: 100000}, (_,i) => ({ i }))
const batch = 1000
for (let i = 0; i < docs.length; i += batch) {
  db.big.insertMany(docs.slice(i, i + batch), { ordered: false })
}
14

Change streams

Surveiller les changements

Les change streams permettent aux applications de réagir aux changements de données en temps réel en suivant l'oplog. Chaque événement inclut le type d'opération, le document complet (pour inserts/updates avec l'option fullDocument) et un resume token. Stockez le resume token pour reprendre après un redémarrage sans manquer ni dupliquer d'événements. Exige un replica set ou un cluster shardé.

mongodb
# open a change stream on a collection
const stream = db.users.watch()

# process change events (Node.js driver)
stream.on("change", (event) => {
  console.log(event.operationType)  // insert|update|delete|replace
  console.log(event.fullDocument)   // the new document
  console.log(event.documentKey)    // the _id
  console.log(event.updateDescription)  // updated fields
})

# resume token enables restart from last position
const token = stream.resumeToken
// store token, then resume later:
const stream2 = db.users.watch([], { resumeAfter: token })

# close the stream
stream.close()

Filtrer les événements de changement

Filtrez les change streams avec un pipeline d'agrégation — seuls les événements correspondants atteignent votre app, réduisant le bruit. Par défaut, les updates n'incluent que les champs modifiés, pas le document complet ; fullDocument:'updateLookup' va chercher le document courant (requête supplémentaire par événement). fullDocumentBeforeChange (6.0+) inclut le document d'avant modification — utile pour les logs d'audit.

mongodb
# filter with an aggregation pipeline
const stream = db.users.watch([
  { $match: { operationType: "update" } },
  { $match: { "updateDescription.updatedFields.status": "active" } },
  { $project: { fullDocument: 1, documentKey: 1 } }
])

# watch specific operations
{ $match: { operationType: { $in: ["insert", "update"] } } }

# full document lookup on update (fetches current doc)
db.users.watch([], {
  fullDocument: "updateLookup"   // include latest doc on updates
})

# fullDocumentBeforeChange (MongoDB 6.0+)
db.users.watch([], {
  fullDocumentBeforeChange: "whenAvailable"
})

Change stream sur base/cluster

Les change streams peuvent surveiller une seule collection, toute une base, ou tout le cluster. Les streams de base et de cluster incluent le namespace (ns) dans chaque événement pour savoir où le changement a eu lieu. Utilisez startAtOperationTime pour rejouer les changements depuis un point précis de l'oplog — utile pour du backfill ou la récupération d'événements manqués après une panne.

mongodb
# watch all collections in a database
const stream = db.watch()

# watch all databases in a cluster
const stream = client.watch()

# events include the ns (namespace) field
stream.on("change", (e) => {
  console.log(e.ns.db + "." + e.ns.coll)
  console.log(e.operationType)
})

# useful for audit logging, cache invalidation,
# cross-system sync, and real-time analytics

# start at a specific timestamp
db.users.watch([], {
  startAtOperationTime: Timestamp(1700000000, 1)
})

Resume tokens et fiabilité

Les resume tokens garantissent une livraison at-least-once — persistez-les après traitement de chaque événement pour qu'un redémarrage reprenne exactement où vous en étiez. resumeAfter et startAfter sont similaires ; startAfter marche même après des événements d'invalidation de collection (comme un drop). Gérez toujours les erreurs et reconnectez avec le dernier token. Le token est opaque — traitez-le comme une boîte noire.

mongodb
# each event has a resume token (_id)
stream.on("change", (e) => {
  saveToStore(e._id)        // persist the token
  processEvent(e)
})

# after a restart, resume from the last token
const lastToken = loadFromStore()
const stream = db.users.watch([], {
  resumeAfter: lastToken     // resume after this event
})

# alternative: start after a cluster time
db.users.watch([], { startAfter: lastToken })

# handle errors and reconnect
stream.on("error", (err) => {
  console.error("stream error", err)
  // reconnect with the last saved token
})

# the token is opaque — store it, don't parse it

Cas d'usage des change streams

Les change streams alimentent les architectures temps réel : invalidation de cache (supprimer les entrées périmées), notifications live (push WebSocket), logging d'audit (enregistrer chaque changement pour la conformité), et ETL/sync (répliquer vers Elasticsearch, un data warehouse ou un autre système). Ils remplacent le polling manuel et les triggers par un modèle événementiel réactif et propre.

mongodb
# 1. Cache invalidation: clear cache when data changes
stream.on("change", (e) => {
  redis.del("user:" + e.documentKey._id)
})

# 2. Real-time notifications: push to WebSocket clients
stream.on("change", (e) => {
  io.emit("user-updated", e.fullDocument)
})

# 3. Audit log: record all changes to a separate store
stream.on("change", (e) => {
  auditLog.insertOne({
    op: e.operationType,
    doc: e.fullDocument,
    at: new Date()
  })
})

# 4. ETL: sync to a search index or warehouse
stream.on("change", async (e) => {
  await elasticsearch.index(e.fullDocument)
})
15

Administration et outils

Statut serveur et monitoring

serverStatus() est la source de monitoring principale — suivez les connexions, opcounters, le ratio de hit du cache et le lag de réplication. currentOp montre les opérations en cours ; killOp termine une requête longue par son opid. Réglez un agent de monitoring (Prometheus, Datadog, Atlas) pour collecter ces métriques en continu. Alertes clés : nombre de connexions approchant la limite, ratio de hit du cache en baisse, lag de réplication en pic.

mongodb
# overall server status
db.serverStatus()

# key metrics to monitor:
db.serverStatus().connections       # active/idle connections
db.serverStatus().opcounters         # queries/inserts/updates/sec
db.serverStatus().wiredTiger.cache   # cache hit ratio (aim >95%)
db.serverStatus().metrics.document   # docs inserted/returned/deleted
db.serverStatus().repl               # replication state

# current operations (find long-running ops)
db.currentOp({ secs_running: { $gte: 5 } })

# kill a long-running operation
db.killOp(opid)

# host info (CPU, OS, memory)
db.hostInfo()

Stats de base et collection

stats() montre les détails de stockage : dataSize (logique), storageSize (physique, après compression WiredTiger — souvent 50-80 % plus petit) et indexSize. estimatedDocumentCount est instantané (depuis les métadonnées de collection) mais approximatif ; countDocuments({}) est précis mais scanne. Utilisez les estimés pour les tableaux de bord et les comptages exacts pour la facturation. Suivez les tendances de croissance du stockage pour planifier la capacité.

mongodb
# database-level stats
db.stats()
db.stats(1024*1024)   # in MB

# collection-level stats
db.users.stats()
db.users.dataSize()       # uncompressed data size
db.users.storageSize()    # on-disk size (with compression)
db.users.totalIndexSize() # total index size
db.users.totalSize()      # data + indexes

# count documents (accurate, may be slow)
db.users.countDocuments({})

# estimated count (fast, from metadata)
db.users.estimatedDocumentCount()

# list collections with sizes
db.runCommand({ listCollections: 1 })

Compact et repair

WiredTiger réutilise l'espace disque libéré, donc compact est rarement nécessaire — seulement après avoir supprimé une grande fraction d'une collection. compact bloque les opérations sur la collection (avant 4.4) ou tourne en ligne (4.4+). repairDatabase est un dernier recours destructif qui réécrit toutes les données — backupez toujours d'abord. Pour récupérer de l'espace sur un replica set, resynchronisez un secondaire (supprimez ses données et laissez-le re-répliquer).

mongodb
# compact: reclaim disk space from deleted/updated docs
# (WiredTiger reuses freed space, so rarely needed)
db.runCommand({ compact: "users" })

# fullDatabase compact (compact every collection)
db.getCollectionNames().forEach(c => {
  db.runCommand({ compact: c })
})

# repairDatabase (legacy, rewrites all data — last resort)
# Stops the server! Back up first.
mongod --repair --dbpath /data/db

# check data integrity (validates BSON)
db.users.validate({ full: true })

# reclaim space by re-syncing a secondary instead
# (safer than repair on a running primary)

mongotop et mongostat

mongostat donne une vue temps réel de la charge serveur (inserts, requêtes, usage cache, connexions) — l'équivalent de top/vmstat pour MongoDB. mongotop montre quelles collections consomment le plus de temps I/O — inestimable pour trouver les collections chaudes. Les deux sont fournis avec MongoDB. Pour le monitoring de production, expédiez le log mongod et les métriques serverStatus vers un système de monitoring pour l'analyse historique.

mongodb
# mongostat: live server stats (like vmstat for MongoDB)
mongostat
mongostat --host=host:27017 --rowcount 10
# columns: insert/query/update/delete/getmore/command
#          dirty (cache %), used (cache %), conn, time

# mongotop: time spent per collection (read/write)
mongotop
mongotop 30          # every 30 seconds
mongotop --host=host:27017

# columns: ns (namespace), total/read/write time (ms)
# helps identify which collections are I/O hot

# log slow queries in the mongod log
# set in mongod.conf:
# operationProfiling:
#   mode: slowOp
#   slowOpThresholdMs: 100

Configuration et démarrage

MongoDB en production tourne via un fichier de config (mongod.conf en YAML). Réglages clés : cacheSizeGB limite la RAM de WiredTiger (le défaut prend 50 % de la RAM — réglez-le explicitement sur des serveurs partagés), bindIp restreint l'accès réseau, authorization active l'auth, et replSetName/clusterRole activent réplication/sharding. Revoyez et versionnez toujours votre mongod.conf. serverCmdLineOpts montre la configuration active.

mongodb
# start mongod with a config file
mongod --config /etc/mongod.conf

# typical mongod.conf (YAML)
storage:
  dbPath: /var/lib/mongodb
  wiredTiger:
    engineConfig:
      cacheSizeGB: 4        # limit RAM usage
  journal:
    enabled: true
net:
  port: 27017
  bindIp: 127.0.0.1
security:
  authorization: enabled
replication:
  replSetName: rs0
sharding:
  clusterRole: shardsvr

# view current configuration
db.serverCmdLineOpts()
db.runCommand({ getCmdLineOpts: 1 })
16

Drivers et intégration

Driver Node.js

Le driver Node.js est basé async/await avec support ES6+ complet. Utilisez toujours le pooling (un MongoClient par app, réutilisé). Les curseurs sont des itérables async. Utilisez for-await-of pour itérer sans tout charger en mémoire. Fermez le client à l'arrêt. Le driver supporte transactions, change streams et toutes les fonctionnalités d'agrégation.

mongodb
const { MongoClient } = require("mongodb")

const client = new MongoClient(
  "mongodb://localhost:27017",
  { maxPoolSize: 50 }
)

async function main() {
  await client.connect()
  const db = client.db("mydb")
  const users = db.collection("users")

  // insert
  await users.insertOne({ name: "Alice", age: 30 })

  // find with a cursor
  const cursor = users.find({ age: { $gte: 18 } })
  for await (const doc of cursor) {
    console.log(doc.name)
  }

  // update
  await users.updateOne(
    { name: "Alice" },
    { $inc: { age: 1 } }
  )
}

main().finally(() => client.close())

Driver Python (PyMongo)

PyMongo est le driver Python officiel. Il est synchrone ; pour l'async utilisez Motor (asyncio) ou Beanie (ODM). Les dictionnaires PyMongo sont de simples dicts Python — pas d'objets spéciaux. Les pipelines d'agrégation sont des listes de dicts. Le motif transactionnel en context-manager assure commit/abort automatiques. Utilisez toujours le pooling (le MongoClient par défaut pool les connexions).

mongodb
from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017")
db = client["mydb"]
users = db["users"]

# insert
users.insert_one({"name": "Alice", "age": 30})

# find
for doc in users.find({"age": {"$gte": 18}}).sort("age", -1):
    print(doc["name"])

# update
users.update_one(
    {"name": "Alice"},
    {"$inc": {"age": 1}}
)

# aggregation
pipeline = [
    {"$group": {"_id": "$city", "count": {"$sum": 1}}},
    {"$sort": {"count": -1}}
]
for doc in users.aggregate(pipeline):
    print(doc)

# use a context manager for transactions
with client.start_session() as session:
    with session.start_transaction():
        users.update_one({"n":"A"}, {"$inc":{"bal":-100}}, session=session)
        users.update_one({"n":"B"}, {"$inc":{"bal":100}}, session=session)

Index depuis les drivers

Créez les index depuis vos scripts de setup/migration applicatifs, pas à chaque requête. createIndexes (pluriel) crée plusieurs index en un appel. En production, la construction d'index sur de grandes collections peut être lente — MongoDB 4.2+ construit les index sans blocage par défaut. Versionnez vos scripts de création d'index avec vos migrations de schéma.

mongodb
// Node.js: create indexes
await db.collection("users").createIndex({ email: 1 }, { unique: true })
await db.collection("users").createIndex({ name: "text" })

// Python
users.create_index([("email", 1)], unique=True)
users.create_index([("name", "text")])

// list indexes
const indexes = await db.collection("users").indexes()

// drop an index
await db.collection("users").dropIndex("email_1")

// create indexes in bulk
await db.collection("orders").createIndexes([
  { key: { customerId: 1 } },
  { key: { status: 1, date: -1 }, name: "status_date" }
])

Options de la chaîne de connexion

La chaîne de connexion porte toute la config client en paramètres de requête. mongodb+srv utilise des enregistrements DNS SRV pour découvrir les hôtes — Atlas utilise ce format ; il simplifie les chaînes de connexion et se met à jour seul quand les nœuds changent. retryWrites=true (défaut dans les drivers modernes) rejoue automatiquement les écritures idempotentes après des accidents réseau. Réglez des timeouts raisonnables pour éviter des connexions suspendues.

mongodb
# standard connection string
mongodb://user:pass@host1:27017,host2:27017/mydb?replicaSet=rs0

# common options (as query params):
#   replicaSet=rs0            - replica set name
#   readPreference=secondary  - route reads to secondaries
#   readConcernLevel=majority - read committed data
#   w=majority                - write concern
#   journal=true              - wait for journal flush
#   maxPoolSize=50            - max connections
#   connectTimeoutMS=5000     - connection timeout
#   socketTimeoutMS=30000     - socket timeout
#   authSource=admin          - db for credentials
#   tls=true                  - enable TLS
#   retryWrites=true          - retry on network errors

# SRV connection string (Atlas, uses DNS)
mongodb+srv://user:[email protected]/mydb

ODM et bibliothèques de haut niveau

Les ODM (Object Document Mappers) ajoutent schémas, validation et une API de plus haut niveau. Mongoose (Node.js) est le plus populaire — il impose la structure que MongoDB n'a pas nativement. Beanie est l'ODM Python async de référence. Les ODM sont parfaits pour le développement rapide et la cohérence d'équipe, mais ajoutent de l'overhead et peuvent masquer la puissance de MongoDB. Pour les apps critiques en performance, utilisez le driver brut.

mongodb
// Mongoose (Node.js ODM with schemas)
const mongoose = require("mongoose")
const userSchema = new mongoose.Schema({
  name: { type: String, required: true },
  age: { type: Number, min: 0 }
})
const User = mongoose.model("User", userSchema)
await User.create({ name: "Alice", age: 30 })
await User.find({ age: { $gte: 18 } })

# Beanie (Python async ODM)
from beanie import Document
class User(Document):
    name: str
    age: int
await User(name="Alice", age=30).insert()
await User.find(User.age >= 18).to_list()

# Mongose vs raw driver:
# ODMs add schemas, validation, and middleware
# but add overhead and a learning curve
# use the raw driver for max performance/control
17

GridFS et gros fichiers

Bases de GridFS

GridFS stocke les fichiers dépassant la limite de 16 Mo des documents BSON en les découpant en chunks (défaut 255 Ko) stockés dans fs.chunks, avec les métadonnées dans fs.files. C'est en pratique un système de fichiers au-dessus de MongoDB. Utilisez-le pour les fichiers dépassant 16 Mo qui bénéficient encore de la réplication et du sharding MongoDB. Pour les médias vraiment volumineux, considérez plutôt S3 ou un CDN.

mongodb
# GridFS stores files larger than 16MB (the BSON doc limit)
# by splitting them into chunks

# store a file via mongofiles (CLI)
mongofiles --db=mydb put large_video.mp4
mongofiles --db=mydb list
mongofiles --db=myfs get large_video.mp4

# two collections are used:
#   fs.files  - file metadata (one doc per file)
#   fs.chunks - file data in 255KB chunks

# query file metadata
db.fs.files.find().pretty()
db.fs.files.findOne({ filename: "large_video.mp4" })

# query chunks for a file
db.fs.chunks.find({ files_id: fileId }).sort({ n: 1 })

GridFS depuis les drivers

Les drivers exposent GridFS comme API en flux (GridFSBucket) — idéal pour les gros fichiers puisqu'ils ne se chargent jamais entièrement en mémoire. Upload/download sont des flux à rediriger vers/depuis fichiers ou réponses HTTP. Les metadata des uploads sont interrogeables comme tout champ de document. Les chunks GridFS sont réassemblés automatiquement au téléchargement. Le nom du bucket ('fs' par défaut) est configurable.

mongodb
// Node.js: upload and download with streams
const { MongoClient, GridFSBucket } = require("mongodb")
const fs = require("fs")

const bucket = new GridFSBucket(db)

// upload a file
fs.createReadStream("video.mp4")
  .pipe(bucket.openUploadStream("video.mp4", {
    metadata: { uploadedBy: "alice" }
  }))

// download a file
bucket.openDownloadStreamByName("video.mp4")
  .pipe(fs.createWriteStream("downloaded.mp4"))

// delete a file
await bucket.delete(fileId)

// find files
const files = await bucket.find({}).toArray()

Collections time series

Les collections time series (5.0+) sont optimisées pour les données séquentielles ordonnées par temps (capteurs IoT, métriques, logs). Elles stockent les données en format quasi columnar sous le capot, atteignant 30-50 % de compression et des requêtes par plage plus rapides que les collections ordinaires. granularity doit matcher l'intervalle de vos données. Le TTL (expireAfterSeconds) purge automatiquement les vieilles données. Utilisez $dateTrunc pour l'agrégation par tranches temporelles.

mongodb
# create a time series collection (MongoDB 5.0+)
db.createCollection("temperatures", {
  timeseries: {
    timeField: "timestamp",
    metaField: "sensorId",
    granularity: "seconds"   // seconds|minutes|hours
  },
  expireAfterSeconds: 2592000   // auto-delete after 30 days
})

# insert measurements
db.temperatures.insertMany([
  { timestamp: ISODate(), sensorId: "s1", value: 22.5 },
  { timestamp: ISODate(), sensorId: "s1", value: 22.7 }
])

# query by time range
db.temperatures.find({
  sensorId: "s1",
  timestamp: { $gte: ISODate("2025-01-01") }
})

# aggregate averages per hour
db.temperatures.aggregate([
  { $group: {
    _id: { $dateTrunc: { date: "$timestamp", unit: "hour" } },
    avg: { $avg: "$value" }
  }}
])

Collections capped

Les collections capped conservent l'ordre d'insertion et écrasent les plus vieux documents quand elles sont pleines — parfait pour les logs, flux d'activité récente et ring buffers. Elles supportent les insertions à haut débit et les curseurs tailable (comme tail -f). Limites : impossible de supprimer des documents individuels ni de faire croître un document au-delà de sa taille d'origine. Les change streams sont l'alternative moderne au tailing temps réel.

mongodb
# capped collections have a fixed size and overwrite old docs
db.createCollection("logs", {
  capped: true,
  size: 5242880,    # 5MB max
  max: 10000        # optional: max document count
})

# inserts only (no arbitrary deletes/updates)
db.logs.insertOne({ msg: "started", t: new Date() })

# high-throughput tail with a tailable cursor
const cursor = db.logs.find().addOption(2)  // tailable
while (true) {
  if (cursor.hasNext()) printjson(cursor.next())
}

# convert a regular collection to capped
db.runCommand({
  convertToCapped: "events",
  size: 1000000
})

Taille BSON et limites de documents

La limite de 16 Mo des documents BSON est un cap dur — utilisez Object.bsonsize() pour vérifier les tailles. Les grands tableaux (milliers d'éléments) enflent les documents et ralentissent les mises à jour (MongoDB réécrit tout le document à chaque update). Pour des données sans borne (avis, commentaires, entrées de log), utilisez une collection séparée avec référence. Pour des blobs binaires de plus de 16 Mo, utilisez GridFS ou un stockage externe avec référence par URL.

mongodb
# maximum BSON document size: 16MB
# check a document's size (in bytes)
Object.bsonsize(db.users.findOne())

# large arrays/fields should be referenced, not embedded
# a product with 10000 reviews -> use a separate collection

# check if a document is too large
const doc = { /* ... huge doc ... */ }
const size = Object.bsonsize(doc)
if (size > 16 * 1024 * 1024) {
  throw new Error("Document exceeds 16MB BSON limit")
}

# GridFS bypasses the limit by chunking
# alternatively, store large blobs externally (S3)
# and keep only a URL reference in the document
18

Comparaison SQL et migration

Mapping SQL vers MongoDB

Ce mapping est le moyen le plus rapide pour un développeur SQL d'apprendre MongoDB. La différence clé : MongoDB n'a pas de schéma fixe (les documents d'une collection peuvent différer), et les « jointures » sont remplacées soit par l'embarquement des données liées, soit par $lookup (plus lent que les jointures SQL — concevez votre schéma pour les minimiser). Le GROUP BY SQL correspond à l'étape d'agrégation $group.

mongodb
# SQL -> MongoDB terminology
# database          -> database
# table             -> collection
# row               -> document
# column            -> field
# index             -> index
# join              -> $lookup (or embed)
# primary key       -> _id (ObjectId by default)
# foreign key       -> reference (ObjectId field)
# group by          -> $group
# select            -> find / $project
# where             -> $match

# SQL query -> MongoDB query
# SELECT * FROM users WHERE age >= 18
db.users.find({ age: { $gte: 18 } })

# SELECT name, age FROM users
db.users.find({}, { name: 1, age: 1, _id: 0 })

# SELECT * FROM users ORDER BY age DESC LIMIT 10
db.users.find().sort({ age: -1 }).limit(10)

# SELECT city, COUNT(*) FROM users GROUP BY city
db.users.aggregate([
  { $group: { _id: "$city", count: { $sum: 1 } } }
])

Migrer depuis SQL

La migration n'est pas un mapping 1:1 table-vers-collection — le schéma doit être repensé pour le modèle documentaire de MongoDB. Embarquez les données petites, exclusives et fréquemment accédées ensemble (profil + adresses d'un utilisateur). Gardez les références pour les données grandes, partagées ou sans borne (commandes d'un client). L'outil Relational Migrator de MongoDB automatise une grande partie de cette analyse. Concevez le schéma, ne le portez pas tel quel.

mongodb
# step 1: export SQL data to JSON/CSV
# (mysqldump, pg_dump, or a script)

# step 2: transform relational data to documents
# SQL:
#   users(id, name, dept_id)
#   departments(id, name)
# MongoDB (embed small, related data):
db.users.insertOne({
  _id: 1,
  name: "Alice",
  department: { id: 10, name: "Engineering" }  # embedded
})

# step 3: for large related data, keep references
db.orders.insertOne({
  _id: 101,
  customerId: 1,    # reference, not embedded
  items: [...]      # embed order items (bounded)
})

# tools: MongoDB Relational Migrator (GUI), mongoimport
# https://www.mongodb.com/.../relational-migrator

Transactions vs ACID SQL

MongoDB fournit l'ACID : les opérations mono-document sont toujours atomiques (pas de transaction nécessaire), et les transactions multi-documents (4.0+) offrent un ACID complet entre collections. La différence clé : le SQL est ACID par défaut à chaque instruction, tandis que MongoDB encourage une conception de schéma gardant les données liées dans un document (atomique par défaut) et n'utilise les transactions qu'en cas de réel besoin. Préférez l'embarquement pour éviter le coût des transactions.

mongodb
# SQL: ACID by default on every statement
BEGIN TRANSACTION;
UPDATE accounts SET balance = balance - 100 WHERE name = 'Alice';
UPDATE accounts SET balance = balance + 100 WHERE name = 'Bob';
COMMIT;

# MongoDB: single-document ops are atomic (ACID)
db.accounts.updateOne({name:"Alice"}, {$inc:{balance:-100}})
# (one document = one atomic operation)

# MongoDB: multi-document ACID (transactions, replica set)
const s = db.getMongo().startSession()
s.startTransaction()
db.accounts.updateOne({name:"Alice"},{$inc:{balance:-100}},{session:s})
db.accounts.updateOne({name:"Bob"},{$inc:{balance:100}},{session:s})
s.commitTransaction()

# prefer embedding to avoid transactions entirely
# (embedded data updates atomically in one document)

Normalisation vs dénormalisation

Le SQL normalise pour éviter la duplication ; MongoDB dénormalise pour la vitesse de lecture. Le compromis : les données dénormalisées se lisent plus vite mais se mettent à jour plus difficilement (plusieurs documents). Dénormalisez les données changeant rarement (noms de pays, catalogues produits) et référencez celles changeant souvent (prix, inventaire). Le bon équilibre dépend de votre ratio lecture/écriture — surveillez et ajustez.

mongodb
# SQL: normalize to avoid duplication (3NF)
#   users(id, name, city_id)
#   cities(id, name, country_id)
#   countries(id, name)
# -> 4 joins to get a user's country

# MongoDB: denormalize for read performance
db.users.insertOne({
  name: "Alice",
  city: "NYC",
  country: "USA"        # denormalized — duplicate but fast reads
})

# trade-off: updates must touch multiple documents
# when a city's name changes:
db.users.updateMany(
  { "city": "New York" },
  { $set: { "city": "NYC" } }
)

# rule: duplicate data that changes rarely,
# reference data that changes often

Quand utiliser MongoDB vs SQL

Il n'y a pas de « meilleure » base universelle. MongoDB excelle aux schémas flexibles, données hiérarchiques et scaling horizontal. Le SQL excelle à l'intégrité relationnelle, aux jointures complexes et aux charges fortement transactionnelles. Beaucoup d'apps modernes sont polyglottes — MongoDB pour catalogues/contenus/données générées par les utilisateurs, PostgreSQL pour les transactions financières. Accordez la base à la charge, pas au battage.

mongodb
# CHOOSE MongoDB when:
# - schema is flexible or evolving rapidly
# - data is naturally hierarchical (embed)
# - you need horizontal scaling (sharding)
# - reads >> writes and you can denormalize
# - document-oriented domain (CMS, product catalogs, IoT)

# CHOOSE SQL (PostgreSQL/MySQL) when:
# - schema is fixed and relational (banking, ERP)
# - you need complex multi-table joins frequently
# - transactions span many tables constantly
# - strong consistency is non-negotiable
# - your team knows SQL well

# HYBRID: use both — MongoDB for product catalog/comments,
# SQL for orders/payments. Many large apps are polyglot.

# AVOID MongoDB for:
# - heavy multi-entity transactional workloads
# - apps requiring complex cross-table joins as core feature
19

Agrégation avancée

$merge et $out (vues matérialisées)

$out remplace une collection cible par la sortie du pipeline (destructif). $merge est plus flexible — il peut insérer, remplacer ou combiner avec les documents existants, permettant des vues matérialisées incrémentales. $merge est préféré pour les rafraîchissements planifiés : seules les données nouvelles/modifiées sont mises à jour. Les vues matérialisées précalculent des agrégations coûteuses pour des requêtes de dashboard rapides.

mongodb
# $out: write aggregation results to a NEW collection
db.orders.aggregate([
  { $group: { _id: "$customerId", total: { $sum: "$amount" } } },
  { $out: "customer_totals" }
])

# $merge: merge results into an EXISTING collection (flexible)
db.orders.aggregate([
  { $group: { _id: "$customerId", total: { $sum: "$amount" } } },
  { $merge: {
    into: "customer_totals",
    on: "_id",
    whenMatched: "replace",    // replace|keepExisting|merge|fail
    whenNotMatched: "insert"   // insert|discard|fail
  }}
])

# build a materialized view refreshed on a schedule
# (cron job or change-stream triggered)
db.daily_stats.aggregate([
  { $match: { date: today } },
  { $group: { _id: "$category", count: { $sum: 1 } } },
  { $merge: { into: "daily_stats", whenMatched: "replace" } }
])

Fonctions de fenêtre ($setWindowFields)

$setWindowFields (5.0+) apporte les fonctions de fenêtre SQL à MongoDB : totaux cumulés, classements, moyennes mobiles et lag/lead. partitionBy est le PARTITION BY, sortBy le ORDER BY, et window définit le cadre. Les fenêtres range utilisent des valeurs (ex. les 7 derniers jours) tandis que les fenêtres documents utilisent des comptes de lignes. Essentiel pour l'analytique de séries temporelles et le reporting.

mongodb
# $setWindowFields: window functions (MongoDB 5.0+)
# like SQL OVER() — compute values across a window of docs
db.sales.aggregate([{
  $setWindowFields: {
    partitionBy: "$region",       # like PARTITION BY
    sortBy: { date: 1 },          # like ORDER BY
    output: {
      runningTotal: { $sum: "$amount", window: { documents: ["unbounded", "current"] } },
      rank: { $rank: {} },
      denseRank: { $denseRank: {} },
      movingAvg: { $avg: "$amount", window: { range: [-7, "current"], unit: "day" } },
      lagValue: { $shift: { by: -1, output: "$amount" } }
    }
  }
}])

# window: documents (count-based) or range (value-based)
# ["unbounded", "current"] = from start to current row
# [-3, "current"] = last 3 docs including current

$map, $filter et $reduce

$map, $filter et $reduce sont des opérateurs fonctionnels de tableau pour les transformations intra-document. $map transforme chaque élément, $filter garde les éléments correspondants, et $reduce agrège un tableau en une valeur. La variable 'as' (défaut $$this) nomme l'élément courant. Ils évitent $unwind pour beaucoup d'opérations sur tableaux — plus rapides et plus propres.

mongodb
# $map: transform each array element
{ $project: {
  squares: { $map: {
    input: "$nums",
    as: "n",
    in: { $multiply: ["$$n", "$$n"] }
  }}
}}

# $filter: keep elements matching a condition
{ $project: {
  adults: { $filter: {
    input: "$users",
    as: "u",
    cond: { $gte: ["$$u.age", 18] }
  }}
}}

# $reduce: fold an array into a single value
{ $project: {
  total: { $reduce: {
    input: "$items",
    initialValue: 0,
    in: { $add: ["$$value", "$$this.price"] }
  }}
}}

# variables: $$value (accumulator), $$this (current element), $$n (named)

$facet et multi-pipeline

$facet exécute plusieurs sous-pipelines sur la même entrée en une seule requête — parfait pour des tableaux de bord nécessitant plusieurs vues des données (ventilations, stats, top N). Chaque sous-pipeline est indépendant. Le résultat est un document avec un champ par sous-pipeline. Cela remplace plusieurs aller-retours et garantit un snapshot cohérent.

mongodb
# run several aggregations on the same data in one pass
db.products.aggregate([{
  $facet: {
    "byCategory": [
      { $group: { _id: "$category", count: { $sum: 1 } } },
      { $sort: { count: -1 } }
    ],
    "priceStats": [
      { $group: { _id: null, avg: { $avg: "$price" }, max: { $max: "$price" } } }
    ],
    "topRated": [
      { $sort: { rating: -1 } },
      { $limit: 5 },
      { $project: { name: 1, rating: 1, _id: 0 } }
    ],
    "totalCount": [{ $count: "n" }]
  }
}])
# result: a single doc with all four arrays/objects

$bucket et $bucketAuto

$bucket catégorise les documents en plages de valeurs explicites (comme le CASE WHEN SQL) — parfait pour des tranches de prix, groupes d'âge et histogrammes. $bucketAuto laisse MongoDB calculer les bornes pour produire un nombre cible de buckets (bien pour l'exploration de données quand on ignore la distribution). Les bornes incluent à gauche, excluent à droite.

mongodb
# $bucket: group documents into explicit ranges
db.products.aggregate([{
  $bucket: {
    groupBy: "$price",
    boundaries: [0, 50, 100, 500, 1000],
    default: "other",
    output: {
      count: { $sum: 1 },
      names: { $push: "$name" },
      avgPrice: { $avg: "$price" }
    }
  }
}])
# buckets: [0,50), [50,100), [100,500), [500,1000), other

# $bucketAuto: let MongoDB choose the boundaries
db.products.aggregate([{
  $bucketAuto: {
    groupBy: "$price",
    buckets: 5,           # target 5 buckets
    output: { count: { $sum: 1 }, avg: { $avg: "$price" } }
  }
}])
# good for histograms and data exploration
20

Monitoring et dépannage

Métriques clés à surveiller

Les quatre signaux d'or pour MongoDB : les connexions (proche de la limite signale des fuites ou un pooling absent), le ratio de hit du cache (des pages lues depuis le disque indiquent une pression RAM), le lag de réplication (un secondaire en retard risque de perdre des données au failover), et la profondeur de file (contention de verrous). Réglez des alertes sur les quatre. Un ratio de hit du cache qui chute est le signal d'alarme performance n°1.

mongodb
# connections (watch for connection leaks)
db.serverStatus().connections
# { current, available, totalCreated }

# operation rates (queries/inserts/updates/deletes per sec)
db.serverStatus().opcounters

# WiredTiger cache (disk reads = cache misses)
db.serverStatus().wiredTiger.cache
# "bytes currently in the cache" vs "maximum bytes configured"
# "pages read into cache" should be low (cache hits)

# replication lag (critical for HA)
rs.printSecondaryReplicationInfo()

# queue depth (operations waiting for locks)
db.serverStatus().globalLock.currentQueue

# open cursors (watch for leaks)
db.serverStatus().metrics.cursor

Résoudre la contention de verrous

MongoDB utilise un verrouillage au niveau document (WiredTiger), donc la contention est rare — mais les requêtes non indexées, les tris énormes et les transactions longues bloquent quand même. currentOp trouve le coupable ; killOp l'arrête. La cause racine est généralement un index manquant (lancez explain). Les migrations de schéma sur de grandes collections peuvent verrouiller longtemps — faites-les par petits lots ou à faible trafic.

mongodb
# check current queue (operations waiting)
db.serverStatus().globalLock.currentQueue
# { readers, writers, total }

# find long-running operations
db.currentOp({
  secs_running: { $gte: 5 },
  op: { $ne: "none" }
})

# kill a long-running op blocking others
db.killOp(opid)

# common causes of lock contention:
# - unindexed queries (COLLSCAN holds locks)
# - large in-memory sorts
# - long transactions
# - schema migrations on large collections

# check for slow ops in the log
db.adminCommand({ getLog: "global" }).log
  .filter(l => l.includes(" Slow query"))

Analyse mémoire et disque

Le cache de WiredTiger est la frontière mémoire — s'il est plein de pages sales, les écritures ralentissent (flush sur disque). Si « pages read into cache » est élevé, ajoutez de la RAM ou des index pour réduire les scans. Supprimez les index inutilisés — ils consomment disque ET mémoire ET ralentissent les écritures. Surveillez la croissance du stockage pour prédire les besoins de capacité. Sur clusters shardés, des jumbo chunks (trop gros pour migrer) indiquent une mauvaise shard key.

mongodb
# check storage engine memory usage
db.serverStatus().wiredTiger.cache
# "maximum bytes configured" = cache limit (default 50% RAM)
# "tracked dirty bytes" = dirty pages awaiting flush
# target: dirty < 20%, cache usage < 95%

# disk space per collection
db.users.stats().storageSize
db.users.totalIndexSize()

# find the largest collections
db.getCollectionNames().map(c => ({
  name: c, size: db.getCollection(c).storageSize()
})).sort((a,b) => b.size - a.size).slice(0, 5)

# check for jumbo chunks (sharded clusters)
sh.status(true)

# review index sizes (drop unused indexes)
db.users.getIndexes().map(i => ({
  name: i.name, size: db.users.stats().indexSizes[i.name]
}))

Analyse des logs

Le log mongod enregistre les opérations lentes, élections, erreurs et plus. Réglez slowOpThresholdMs pour capturer les requêtes au-dessus de votre SLO. getLog récupère le ring buffer en mémoire ; le log sur disque survit aux redémarrages. logRotate archive le log courant (à utiliser avec logrotate pour une rotation quotidienne). Augmentez la verbosité des composants temporairement pour un débogage profond (ex. replication: 2 pour des problèmes d'élection), puis remettez.

mongodb
# view recent log entries
db.adminCommand({ getLog: "global" })

# log slow queries (set threshold)
db.adminCommand({
  setParameter: 1,
  logComponentVerbosity: { query: { verbosity: 1 } }
})

# mongod.conf: log slow operations
# operationProfiling:
#   mode: slowOp
#   slowOpThresholdMs: 100
#   slowOpSampleRate: 1.0

# grep the mongod log for slow queries
grep "Slow query" /var/log/mongodb/mongod.log
grep "COMMAND" /var/log/mongodb/mongod.log | tail -50

# rotate logs
db.adminCommand({ logRotate: 1 })

# set log verbosity for a component
db.adminCommand({
  setParameter: 1,
  logComponentVerbosity: { replication: 2 }
})

Erreurs courantes et solutions

Voici les erreurs MongoDB les plus courantes. Les erreurs de clé dupliquée viennent de violations de _id ou d'index unique — gérez-les dans le code applicatif. Les limites mémoire d'agrégation se règlent avec allowDiskUse (plus lent mais marche). WriteConflict dans les transactions est normal sous contention — rejouez. Les timeouts de curseur signifient que votre traitement par lots est trop lent — utilisez des lots plus petits ou noCursorTimeout (mais fermez toujours les curseurs).

mongodb
# ERROR: "E11000 duplicate key"
# cause: _id or unique index conflict
# fix: check the duplicate value, use upsert, or catch the error

# ERROR: "QueryExceededMemoryLimitNoDiskUseAllowed"
# cause: aggregation stage exceeded 100MB RAM
# fix: add { allowDiskUse: true } or add $match early
db.big.aggregate([...], { allowDiskUse: true })

# ERROR: "BSONObjTooLarge"
# cause: document > 16MB
# fix: use GridFS or split the document

# ERROR: "WriteConflict" (transaction)
# cause: two transactions modified the same doc
# fix: retry the transaction (TransientTransactionError)

# ERROR: "ReplicaSetNoPrimary"
# cause: no primary (election in progress)
# fix: wait for election; check rs.status()

# ERROR: "cursor not found"
# cause: cursor timed out (10 min default)
# fix: use noCursorTimeout or process faster

Was this helpful?