Skip to content

MongoDB Hoja de referencia

Base de datos de documentos NoSQL para almacenar grandes volúmenes de datos.

01

Primeros pasos

Conectar a MongoDB

mongosh es el shell moderno de MongoDB (sustituye al antiguo shell mongo). Una cadena de conexión sigue el formato URI mongodb://[user:pass@]host[:port]/[db][?options]. La base de datos /admin es la base de datos de autenticación por defecto. Puedes conectarte directamente a una base de datos concreta añadiéndola al 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()

Conceptos básicos de bases de datos

MongoDB crea las bases de datos y colecciones de forma diferida (lazy): solo aparecen tras insertar el primer documento. 'use mydb' cambia el contexto pero no crea la base de datos hasta que se escriben datos. show dbs no muestra las bases de datos vacías. dropDatabase elimina permanentemente todas las colecciones y sus datos.

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()

Colecciones

Las colecciones son análogas a las tablas de SQL y contienen documentos. Se crean automáticamente en la primera inserción, pero createCollection permite definir opciones como capped (colecciones de tamaño fijo que sobrescriben los documentos antiguos — útiles para logs). stats() muestra el tamaño de almacenamiento, el número de documentos y los detalles de los índices.

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()

Tipos de datos BSON

BSON amplía JSON con tipos adicionales esenciales para las aplicaciones: ObjectId (IDs únicos de 12 bytes), ISODate, NumberDecimal (decimal exacto para dinero — evita el redondeo de punto flotante), NumberLong (enteros de 64 bits), BinData (binario) y más. Usar NumberDecimal para moneda evita los clásicos errores de punto flotante.

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 y ayuda del shell

mongosh soporta JavaScript completo, así que puedes escribir bucles, funciones y variables en el shell. .pretty() formatea la salida para hacerla legible (por defecto en mongosh). load() ejecuta un archivo .js en el contexto del shell — útil para scripts administrativos repetitivos. db.collection.help() lista cada función disponible.

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

Operaciones CRUD

Insertar documentos

MongoDB genera automáticamente un _id (ObjectId) si no lo proporcionas. El _id debe ser único dentro de una colección — un _id duplicado lanza un error de escritura. ordered:false permite que insertMany siga insertando los documentos restantes tras un error, mejorando el rendimiento en cargas masivas.

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 })

Buscar / consultar documentos

find() devuelve un cursor (evaluación perezosa); findOne() devuelve un único documento o null. La proyección controla qué campos se devuelven — no puedes mezclar inclusión y exclusión (excepto con _id). Usa 1 para incluir y 0 para excluir. countDocuments es preciso; el antiguo count() está obsoleto para conteos con filtros.

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 } })

Actualizar documentos

updateOne/updateMany usan operadores de actualización ($set, $inc, etc.) para modificar campos concretos. replaceOne reemplaza el documento entero excepto el _id. upsert:true crea un nuevo documento cuando no hay coincidencias — útil para patrones de 'crear o actualizar'. Usa siempre $set para actualizar campos; un objeto sin operadores reemplaza el documento (comportamiento heredado).

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 }
)

Operadores de actualización

Los operadores de actualización modifican campos de forma atómica a nivel de documento. $inc es seguro ante concurrencia (sin condiciones de carrera de leer-modificar-escribir). $min/$max solo actualizan si el nuevo valor es menor/mayor. $currentDate es práctico para marcas de tiempo de 'última modificación'. Se pueden combinar varios operadores en una sola actualización.

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} })

Eliminar documentos

deleteOne elimina la primera coincidencia; deleteMany elimina todas. deleteMany({}) vacía la colección pero conserva los índices (más rápido que drop+recrear si quieres mantener las definiciones de índices). findOneAndDelete devuelve el documento eliminado de forma atómica. Las eliminaciones son irreversibles — filtra siempre con cuidado.

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 })

Operadores de actualización de arrays

$push añade al final (permite duplicados); $addToSet evita duplicados. $pull elimina los elementos que cumplen una condición. El operador posicional ($) se refiere al primer elemento del array que coincide con la consulta — imprescindible para actualizar elementos concretos de un array sin conocer su índice. $[] actualiza cada elemento del array.

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

Consulta de documentos

Operadores de comparación

Los operadores de comparación son la base de las consultas. $in es mucho más eficiente que varias condiciones $or sobre el mismo campo. Puedes combinar varios operadores en un campo (p. ej. $gte y $lte para un rango). $exists:true encuentra documentos que tienen el campo, $exists:false los que no lo tienen.

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 } })

Operadores lógicos

El AND implícito (coma en un filtro) es lo más común y eficiente. Usa $and explícito solo cuando necesites varias condiciones sobre el mismo campo (el AND implícito sobre el mismo campo sobrescribe las condiciones anteriores). $or usa recorridos de índice separados y combina resultados — asegúrate de que los campos de $or estén indexados por rendimiento.

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" })

Operadores de elemento y evaluación

$type filtra por tipo BSON (útil para campos de tipos mixtos). $regex admite opciones como 'i' (sin distinguir mayúsculas) — pero una regex sin ancla de prefijo no puede usar índices eficientemente. $expr permite comparaciones entre campos del documento, algo que los operadores normales no pueden hacer. Usa $expr con moderación porque puede saltarse los índices.

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"]
}})

Operadores de consulta de arrays

$all encuentra arrays que contengan cada uno de los valores indicados (sin importar el orden). $elemMatch es imprescindible cuando un elemento del array debe cumplir varias condiciones a la vez (una consulta simple evaluaría los elementos por separado). $size solo coincide con longitudes exactas — no existe un $size con rango; precalcula y guarda la longitud en un campo aparte.

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

Funciones de cursor y ordenación

skip+limit implementa paginación, pero skip se vuelve lento con desplazamientos grandes (escanea cada documento saltado). Para paginación profunda, usa la paginación por clave (keyset pagination): consulta con un filtro sobre el campo de ordenación mayor que el último valor visto. sort() puede apoyarse en un índice para evitar la ordenación en memoria — indexa siempre tus campos de ordenación en colecciones grandes.

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

Indexación

Crear índices

Los índices aceleran enormemente las consultas, pero ralentizan las escrituras y consumen disco. Los índices de un solo campo soportan consultas sobre ese campo en cualquier dirección de ordenación. Los índices compuestos siguen la regla ESR (Equality, Sort, Range) para un orden óptimo. Los índices TTL eliminan documentos automáticamente tras un plazo — perfectos para sesiones y 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" })

Ver y gestionar índices

getIndexes lista cada índice con sus claves y opciones. hideIndex/unhideIndex permite probar el impacto de quitar un índice sin llegar a eliminarlo — el planificador de consultas ignora los índices ocultos. Si el rendimiento no cambia, es seguro eliminarlo. Ejecuta siempre explain() antes y después de cambios de índices.

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")

Tipos de índices especiales

Los índices 2dsphere dan soporte a las consultas geoespaciales ($near, $geoWithin). Los índices hashed soportan sharding basado en hash para una distribución uniforme de los datos. Los índices wildcard ($**) cubren nombres de campo impredecibles/variables en los documentos — útiles para datos polimórficos. Los índices parciales solo indexan los documentos que coinciden, ahorrando espacio cuando consultas solo un subconjunto.

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 y planes de consulta

explain() es la herramienta principal de rendimiento. COLLSCAN (exploración de colección) significa que no se usó ningún índice — una señal de alarma en colecciones grandes. IXSCAN significa que se usó un índice. totalDocsExamined >> nReturned indica un índice pobre (examinar muchos documentos para devolver pocos). hint() fuerza un índice concreto para probar la elección del planificador.

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})

Buenas prácticas de indexación

La regla ESR (Equality, Sort, Range) es el principio de diseño de índices compuestos más importante: coloca primero los campos filtrados por igualdad, luego los de ordenación y después los de rango. Una covered query (cada campo está en el índice) nunca accede al documento — la consulta más rápida posible. Evita los índices que no usas; cada uno añade sobrecarga de escritura.

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 de agregación

Conceptos básicos del pipeline de agregación

El pipeline de agregación procesa los documentos a través de etapas en secuencia. $match al principio del pipeline reduce el conjunto de trabajo (y puede usar índices). $group equivale al GROUP BY de SQL. $count es un atajo de $group + $project. El orden importa: primero filtra, luego agrupa, después ordena y por último limita.

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 y $limit

Coloca siempre $match lo antes posible — reduce los documentos para todas las etapas posteriores y puede usar índices. $project remodela los documentos y calcula campos nuevos con expresiones. Renombrar o calcular campos en $project es habitual antes de $group. $unset es un atajo para excluir campos.

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 y acumuladores

$group es la etapa central de agregación. _id especifica la clave de agrupación (usa null para agregar el conjunto completo de documentos). $push construye un array de valores por grupo; $addToSet elimina duplicados. $first/$last se refieren al orden de los documentos en el grupo — usa $sort antes de $group si el orden importa. El límite de memoria es 100MB por etapa (usa allowDiskUse con conjuntos de datos grandes).

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 (joins)

$lookup realiza un left outer join — como el LEFT JOIN de SQL. Los datos unidos se colocan en un campo array nombrado con 'as'. La forma de pipeline permite filtrar y transformar los documentos unidos. $unwind descompone campos array (un documento de salida por elemento) — se usa a menudo tras $lookup para aplanar resultados. Los joins son menos eficientes que los datos embebidos en 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 y $facet

$facet ejecuta varios sub-pipelines sobre la misma entrada — perfecto para dashboards que necesitan varias agregaciones (top N, conteos, desgloses) en una sola consulta. $bucket categoriza automáticamente valores en rangos. $unwind con preserveNullAndEmptyArrays conserva los documentos cuyo array está vacío o no existe — útil para no perder datos en los 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

Transacciones

Transacciones ACID

Las transacciones multidocumento ofrecen garantías ACID entre colecciones (requiere un replica set o clúster sharded). Pasa la sesión a cada operación dentro de la transacción. commitTransaction hace los cambios permanentes y visibles; abortTransaction revierte cada cambio. Mantén las transacciones cortas — retienen bloqueos y pueden afectar al rendimiento.

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 de las transacciones

El read concern controla cuán 'frescas' y consistentes son las lecturas. 'snapshot' ofrece una vista transaccionalmente consistente entre shards — ideal para reporting. El write concern controla la durabilidad: w:majority garantiza que los datos estén replicados antes del ack (sobrevive a un failover del primario); j:true espera el volcado del journal. Niveles más altos son más seguros pero más lentos.

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

Reintentos y errores

MongoDB marca los errores reintentables con errorLabels: TransientTransactionError (reintentar toda la transacción) y UnknownCommitResult (reintentar solo el commit). Los drivers de producción incluyen reintentos integrados. Diseña siempre las transacciones para que sean idempotentes cuando sea posible. Evita transacciones largas que retengan bloqueos y bloqueen otras operaciones.

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()
    }
  }
}

Operaciones atómicas de un solo documento

Las operaciones de un solo documento son atómicas por defecto — no hace falta transacción. findOneAndUpdate/findOneAndReplace/findOneAndDelete devuelven el documento de forma atómica (genial para generar IDs secuenciales). Para muchas cargas de trabajo, embeber datos relacionados en un documento y usar operadores atómicos ($inc, $push) evita por completo las transacciones multidocumento.

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 (patrón)

El patrón two-phase commit simula transacciones distribuidas sin transacciones multidocumento nativas. Mantiene un estado 'pending' para que un proceso de recuperación pueda reanudar o deshacer si hay un fallo a mitad de la transferencia. Usa transacciones nativas cuando estén disponibles — este patrón es complejo y propenso a errores, y se conserva principalmente con fines educativos y de legado.

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

Modelado de datos

Embeber vs referenciar

La decisión cardinal en el modelado en MongoDB: embebe los datos que se acceden juntos y cambian poco; referencia los datos grandes, compartidos o actualizados de forma independiente. Embebe cuando la relación 'tiene-un' es exclusiva (las direcciones de un usuario). Referencia cuando los datos se reutilizan (un producto en muchos pedidos) o crecen sin límite (los millones de entradas de log de un usuario).

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

Relaciones uno a muchos

Para relaciones de 'pocos', embebe. Para 'muchos', referencia desde el hijo (ID del padre en cada hijo). Para 'muchísimos' (millones), usa el patrón bucket: agrupa documentos hijos en buckets propiedad del padre (p. ej., por mes) para equilibrar el tamaño del documento y la velocidad de consulta. Así evitas tanto arrays ilimitados como un exceso de documentos hijos.

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} ]
})

Relaciones muchos a muchos

Para muchos a muchos, elige el enfoque según los patrones de consulta y el tamaño de los datos. Los arrays en ambas partes son rápidos pero exigen mantenimiento doble. Una colección de unión (tabla de mapeo) es lo más flexible y lo que mejor escala — puede guardar metadatos de la relación (fecha de inscripción, nota) y evita inflar los documentos padre.

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 })

Patrones de diseño de esquema

El Attribute Pattern maneja entidades con atributos variables (productos con especificaciones distintas) — evita campos dispersos y habilita atributos dinámicos. El Polymorphic Pattern guarda formas relacionadas pero distintas en una misma colección usando un discriminante de tipo. El Outlier Pattern trata documentos excepcionales (una celebridad con millones de seguidores) referenciando en lugar de embeber.

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" } })

Validación de esquema

La validación de esquema aplica la estructura del documento en la escritura — la respuesta de MongoDB a los esquemas fijos. validationLevel 'strict' valida todas las escrituras; 'moderate' solo valida inserciones y actualizaciones completas. validationAction 'error' rechaza los documentos inválidos; 'warn' los registra pero los acepta. La validación complementa (no sustituye) la validación a nivel de aplicación.

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

Fundamentos del replica set

Un replica set ofrece alta disponibilidad y escalado de lecturas. Solo un miembro es primario (acepta escrituras); los demás replican de forma asíncrona. Si el primario falla, una elección promueve un secundario automáticamente. Un número impar de miembros con derecho a voto (3 como mínimo) evita empates en las elecciones. rs.status() muestra la salud, el estado y el retardo de replicación de cada miembro.

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

El read preference equilibra consistencia frente a carga. primary garantiza leer siempre las escrituras más recientes. secondary/secondaryPreferred descarga lecturas del primario, pero los datos pueden estar obsoletos (retardo de replicación, normalmente milisegundos). nearest minimiza la latencia — ideal para apps distribuidas geográficamente. Las cargas analíticas/de reporting deberían leer de secundarios.

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

El write concern cambia velocidad por seguridad. w:1 confirma en cuanto el primario escribe (rápido, pero arriesga pérdida de datos si el primario cae antes de replicar). w:majority garantiza que la escritura esté replicada — sobrevive al fallo de un nodo (recomendado para datos importantes). j:true espera el volcado a disco del journal. Configura un valor por defecto sensato a nivel de clúster.

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" } }
})

Árbitros y elecciones

Los árbitros aportan un voto para alcanzar la mayoría sin almacenar datos — útiles en despliegues de dos nodos, aunque un tercer nodo de datos es preferible. Los miembros con prioridad 0 nunca se convierten en primarios (bien para nodos dedicados a analítica o DR). Los miembros hidden quedan excluidos del read preference 'nearest' y son ideales para backups. Los miembros retrasados van por detrás, lo que permite recuperarse de borrados accidentales.

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 y interior de la replicación

El oplog (registro de operaciones) es una colección capped que registra cada escritura — los secundarios aplican esas entradas en orden para replicar. Si un secundario se queda atrás más allá de la ventana del oplog, necesita un resincronizado completo. printReplicationInfo muestra el intervalo temporal del oplog; printSecondaryReplicationInfo muestra el retardo de cada secundario. Oplogs más grandes toleran caídas más largas.

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

Fundamentos del sharding

El sharding escala horizontalmente una colección entre varios shards. El shard key determina la distribución de los datos y es inmutable tras el sharding. El sharding hashed distribuye de forma uniforme (bueno para claves que crecen de forma monótona como ObjectId); el sharding por rangos permite consultas dirigidas pero puede generar hotspots. Elige bien el shard key — no se puede cambiar fácilmente después.

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()

Selección del shard key

El shard key es la decisión más crítica del sharding. Debe soportar tus consultas habituales (las consultas sin el shard key golpean la totalidad de los shards — scatter-gather). Una cardinalidad alta evita jumbo chunks inamovibles. Las claves monótonas (timestamps, ObjectIds) hacen que cada inserción caiga en un solo shard — usa sharding hashed para ellas. Las claves compuestas deben empezar por el campo más selectivo.

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()

Zonas y sharding consciente de etiquetas

Las zonas (tag-aware sharding) dirigen rangos de datos concretos a shards concretos — permite cumplir la residencia de datos (GDPR exige datos de la UE en la UE), la geo-localidad (lecturas regionales rápidas) o niveles de hardware (datos calientes en SSD, fríos en HDD). El balancer respeta los rangos de zona al migrar chunks. Define primero las etiquetas de shard y luego etiqueta los rangos.

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

Gestión de chunks

Los chunks son la unidad de movimiento de datos entre shards. El balancer divide y migra chunks automáticamente para mantener equilibrados los shards. Los jumbo chunks superan el límite de tamaño y no se pueden migrar — evítalos con buena cardinalidad del shard key. El tamaño por defecto de 128MB equilibra velocidad de migración y sobrecarga. Las operaciones manuales de chunks son para diagnóstico, no para el día a día.

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

Componentes de un clúster sharded

Un clúster sharded tiene tres componentes: servidores de configuración (metadatos, desplegados como replica set), enrutadores mongos (sin estado, a ellos se conectan los clientes) y shards (cada uno un replica set con un subconjunto de datos). Los clientes nunca se conectan directamente a los shards. Quitar un shard dispara la migración de datos hacia los demás — un proceso lento que conviene monitorizar.

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

Seguridad y autenticación

Autenticación y usuarios

La autenticación verifica la identidad. Crea el usuario admin antes de activar la autenticación, o te quedarás fuera. Los roles integrados van de solo lectura a admin completo. Usa passwordPrompt() en el shell para evitar contraseñas en texto plano en el historial. Cada usuario pertenece a una base de datos, pero puede tener roles en otras. Activa TLS en producción (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")

Roles integrados y roles personalizados

Los roles integrados cubren los casos comunes; los roles personalizados permiten el mínimo privilegio. Los privilegios emparejan un recurso (base de datos/colección) con acciones permitidas (find, insert, update, etc.). Concede lo mínimo necesario — un usuario de reporting solo necesita 'find' sobre colecciones concretas. Los roles personalizados se guardan en la base de datos admin y pueden reutilizarse entre usuarios.

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" }])

Cifrado TLS/SSL

TLS cifra los datos en tránsito — obligatorio en producción. requireTLS rechaza conexiones no TLS. Para una PKI interna, usa autenticación con certificados x.509 (sin contraseñas — el certificado ES la credencial). La base de datos $external guarda los usuarios x.509. Usa siempre una CA real (o CA interna) en producción; los certificados autofirmados son solo para pruebas.

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

Red y auditoría

bindIp limita las interfaces de red en las que MongoDB escucha — nunca expongas MongoDB directamente a internet (bindIp: 0.0.0.0 + sin autenticación ha causado incontables brechas). La auditoría (solo Enterprise) registra operaciones relevantes para la seguridad por cumplimiento. La edición comunitaria puede usar herramientas del SO (auditd) o logging a nivel de aplicación como alternativa.

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

Cifrado a nivel de campo (CSFLE)

CSFLE cifra los campos sensibles en el cliente, de modo que el servidor, los backups y los logs nunca contienen texto plano — la protección de datos más fuerte. El cifrado determinista soporta consultas por igualdad; el aleatorio es más seguro pero no consultable. El auto-cifrado (vía un esquema del driver) es transparente para el código de la aplicación. Las claves de cifrado se gestionan en un KMS (AWS KMS, clave local, 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 y restauración

mongodump y mongorestore

mongodump crea un backup lógico (archivos BSON) — portable pero lento con conjuntos de datos grandes y sin consistencia punto en el tiempo entre colecciones sin --oplog. --drop elimina las colecciones existentes antes de restaurar. --archive + --gzip producen un único archivo comprimido. Para backups grandes de producción, prefiere snapshots del sistema de archivos o Percona Backup antes 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 y mongoimport

mongoexport/mongoimport trabajan con JSON/CSV — para intercambiar datos con otros sistemas, no para backups (pierden tipos BSON como ObjectId y la precisión de Date). Para backups usa mongodump. Las exportaciones CSV son geniales para hojas de cálculo y herramientas de BI. Especifica siempre --fields para un orden de columnas CSV previsible. Las exportaciones JSON se limitan a un documento por línea por defecto (--jsonArray para un único array).

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 del sistema de archivos

Los snapshots del sistema de archivos son la técnica de backup más rápida para conjuntos de datos grandes — capturan el directorio de datos completo de forma consistente. fsyncLock bloquea brevemente las escrituras y vuelca a disco para que el snapshot sea consistente. Los snapshots son casi instantáneos sin importar el tamaño de los datos. Restaurar es tan simple como copiar los archivos de vuelta — mucho más rápido que mongorestore. Funciona mejor en LVM, ZFS o almacenamiento de bloques en la nube (snapshots de 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)

Recuperación punto en el tiempo (oplog)

La recuperación punto en el tiempo (PITR) reconstruye el estado de la base de datos en un momento concreto — esencial tras borrados accidentales o migraciones fallidas. Toma backups base periódicos con --oplog y después reproduce el oplog hasta la marca de tiempo deseada (--oplogLimit se detiene justo antes de una operación problemática). PITR requiere un replica set (el oplog solo existe en los miembros de 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 en Atlas y opciones en la nube

MongoDB Atlas ofrece backups continuos gestionados con recuperación punto en el tiempo — lo más simple para despliegues en la nube. Percona Backup for MongoDB (PBM) es la herramienta de backup open source líder para clústers autoalojados; soporta backups físicos y PITR en replica sets y clústers sharded. Prueba siempre los procedimientos de restauración — un backup que no puedes restaurar no es 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

Rendimiento y optimización

Perfilar consultas lentas

El database profiler registra las operaciones más lentas que slowms (100ms por defecto) en system.profile (una colección capped). El nivel 2 registra cada operación — útil para depurar, pero afecta al rendimiento. Mira millis (duración), nreturned (documentos devueltos) y docsExamined para encontrar consultas ineficientes. Desactiva el profiling al terminar.

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() a fondo

explain() es tu herramienta principal de ajuste. COLLSCAN significa un escaneo completo de la colección — añade un índice. La proporción entre docsExamined y nReturned es la métrica clave de eficiencia: si examinas 10000 documentos para devolver 10, tu índice es malo. allPlansExecution muestra por qué el planificador eligió su plan. Indexa los campos de igualdad, ordenación y rango de tu consulta (regla 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 y memoria

El rendimiento depende de que el working set (datos accedidos con frecuencia) quepa en RAM. Si wiredTiger.cache 'pages read into cache' es alto, estás yendo a disco — añade RAM o índices para reducir escaneos. mongotop muestra qué colecciones son calientes en I/O; mongostat muestra tasas de consulta/inserción/actualización y fallos. compact reclama el espacio en disco desperdiciado por documentos borrados/actualizados.

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" })

Connection pooling

Cada conexión de MongoDB consume memoria del servidor — miles de conexiones degradan el rendimiento. Usa connection pooling (los drivers mantienen un pool reutilizable) con maxPoolSize ajustado a tu carga (50-100 es habitual). Comparte un único MongoClient en toda la aplicación — nunca crees uno por petición. Configura maxIdleTimeMS para reciclar conexiones obsoletas tras balanceadores de carga.

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 }

Escrituras masivas y tamaños de lote

Las escrituras bulk agrupan operaciones en un solo viaje de ida y vuelta — mucho más rápido que operaciones individuales. unordered:true maximiza el rendimiento (continúa tras errores y paraleliza en clústers sharded). Para importaciones grandes, agrupa en lotes de 1000-5000 documentos para equilibrar memoria y viajes de red. insertMany con ordered:false es la forma más rápida de cargar datos.

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

Observar cambios

Los change streams permiten a las aplicaciones reaccionar a cambios de datos en tiempo real siguiendo el oplog. Cada evento incluye el tipo de operación, el documento completo (para inserciones/actualizaciones con la opción fullDocument) y un resume token. Guarda el resume token para reanudar tras un reinicio sin perder ni duplicar eventos. Requiere un replica set o clúster sharded.

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()

Filtrar eventos de cambio

Filtra los change streams con un pipeline de agregación — solo los eventos que coinciden llegan a tu app, reduciendo el ruido. Por defecto, las actualizaciones solo incluyen los campos cambiados, no el documento completo; fullDocument:'updateLookup' obtiene el documento actual (una consulta extra por evento). fullDocumentBeforeChange (6.0+) incluye el documento previo al cambio — útil para logs de auditoría.

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 en base de datos/clúster

Los change streams pueden observar una colección concreta, una base de datos entera o el clúster completo. Los streams de base de datos y de clúster incluyen el namespace (ns) en cada evento, así sabes dónde ocurrió el cambio. Usa startAtOperationTime para reproducir cambios desde un punto concreto del oplog — útil para rellenar datos o recuperar eventos perdidos tras una caída.

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 y fiabilidad

Los resume tokens garantizan entrega al menos una vez — persiste el token tras procesar cada evento para que un reinicio retome exactamente donde lo dejaste. resumeAfter y startAfter son similares; startAfter funciona incluso tras eventos de invalidación de colección (como un drop). Maneja siempre los errores y reconecta con el último token. El token es opaco — trátalo como una caja negra.

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

Casos de uso de los change streams

Los change streams impulsan arquitecturas en tiempo real: invalidación de caché (borrar entradas obsoletas), notificaciones en vivo (push por WebSocket), logs de auditoría (registrar cada cambio por cumplimiento) y ETL/sincronización (replicar a Elasticsearch, un data warehouse u otro sistema). Sustituyen el polling manual y los triggers por un modelo limpio y reactivo guiado por eventos.

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

Administración y herramientas

Estado del servidor y monitorización

serverStatus() es la fuente principal de monitorización — sigue conexiones, opcounters, ratio de acierto de caché y retardo de replicación. currentOp muestra las operaciones en curso; killOp termina una consulta de larga duración por su opid. Configura un agente de monitorización (Prometheus, Datadog, Atlas) que recoja estas métricas de forma continua. Alertas clave: número de conexiones cerca del límite, ratio de acierto de caché cayendo, retardo de replicación disparándose.

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()

Estadísticas de base de datos y colección

stats() muestra detalles de almacenamiento: dataSize (lógico), storageSize (físico, tras la compresión de WiredTiger — a menudo un 50-80% menor) e indexSize. estimatedDocumentCount es instantáneo (de los metadatos de la colección) pero aproximado; countDocuments({}) es preciso pero escanea. Usa conteos estimados para dashboards y exactos para facturación. Monitoriza las tendencias de crecimiento para planificar capacidad.

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 y repair

WiredTiger reutiliza el espacio en disco liberado, así que compact rara vez hace falta — solo tras borrar una gran fracción de una colección. compact bloquea las operaciones sobre la colección (antes de 4.4) o se ejecuta en línea (4.4+). repairDatabase es un último recurso destructivo que reescribe los datos por completo — haz siempre backup primero. Para reclamar espacio en un replica set, resincroniza un secundario (borra sus datos y deja que vuelva a replicar).

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 y mongostat

mongostat da una visión en tiempo real de la carga del servidor (inserciones, consultas, uso de caché, conexiones) — como top/vmstat para MongoDB. mongotop muestra qué colecciones consumen más tiempo de I/O — inestimable para encontrar colecciones calientes. Ambos vienen incluidos con MongoDB. Para monitorización en producción, envía el log de mongod y las métricas de serverStatus a un sistema de monitorización para análisis histórico.

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

Configuración y arranque

MongoDB en producción se ejecuta con un archivo de configuración (mongod.conf en YAML). Ajustes clave: cacheSizeGB limita la RAM de WiredTiger (por defecto usa el 50% de la RAM — fíjalo explícitamente en servidores compartidos), bindIp restringe el acceso de red, authorization activa la autenticación, y replSetName/clusterRole habilitan replicación/sharding. Revisa siempre y versiona tu mongod.conf. serverCmdLineOpts muestra la configuración activa.

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 e integración

Driver de Node.js

El driver de Node.js está basado en async/await con soporte completo de ES6+. Usa siempre connection pooling (un MongoClient por app, reutilizado). Los cursores son iterables asíncronos. Usa for-await-of para iterar sin cargar la colección completa en memoria. Cierra el cliente al apagar. El driver soporta transacciones, change streams y todas las funciones de agregación.

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 de Python (PyMongo)

PyMongo es el driver oficial de Python. Es síncrono; para async usa Motor (asyncio) o Beanie (ODM). Los diccionarios de PyMongo son dicts de Python normales — no hacen falta objetos especiales. Los pipelines de agregación son listas de dicts. El patrón de transacción con context manager garantiza commit/abort automáticos. Usa siempre connection pooling (el MongoClient por defecto agrupa conexiones).

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)

Índices desde los drivers

Crea los índices desde los scripts de configuración/migración de tu aplicación, no en cada petición. createIndexes (plural) crea varios índices en una sola llamada. En producción, construir índices sobre colecciones grandes puede ser lento — MongoDB 4.2+ construye índices sin bloquear por defecto. Versiona los scripts de creación de índices junto con las migraciones de esquema.

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" }
])

Opciones de la cadena de conexión

La cadena de conexión transporta toda la configuración del cliente como parámetros de consulta. mongodb+srv usa registros DNS SRV para descubrir hosts — Atlas usa este formato; simplifica las cadenas de conexión y se actualiza solo cuando cambian los nodos. retryWrites=true (por defecto en drivers modernos) reintenta automáticamente escrituras idempotentes tras microcortes de red. Fija timeouts razonables para evitar conexiones colgadas.

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

ODMs y librerías de más alto nivel

Los ODM (Object Document Mappers) añaden esquemas, validación y una API de más alto nivel. Mongoose (Node.js) es el más popular — impone la estructura que MongoDB no tiene de forma nativa. Beanie es el ODM async líder en Python. Los ODM son geniales para desarrollo rápido y consistencia de equipo, pero añaden sobrecarga y pueden ocultar el poder de MongoDB. Para apps de rendimiento crítico, usa el driver directo.

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 y archivos grandes

Fundamentos de GridFS

GridFS almacena archivos mayores que el límite de 16MB de los documentos BSON dividiéndolos en chunks (255KB por defecto) guardados en fs.chunks, con metadatos en fs.files. Es efectivamente un sistema de archivos sobre MongoDB. Úsalo para archivos que superan 16MB pero que aún se benefician de la replicación y el sharding de MongoDB. Para medios realmente grandes, considera S3 o 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 desde los drivers

Los drivers exponen GridFS como una API de streams (GridFSBucket) — ideal para archivos grandes porque nunca se cargan por completo en memoria. Subir/descargar son streams que conectas con archivos o respuestas HTTP. Los metadata de las subidas se consultan como cualquier campo de documento. Los chunks de GridFS se reensamblan automáticamente al descargar. El nombre del bucket ('fs' por defecto) es 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()

Colecciones de series temporales

Las colecciones de series temporales (5.0+) están optimizadas para datos secuenciales ordenados por tiempo (sensores IoT, métricas, logs). Guardan los datos en formato columnar por debajo, logrando un 30-50% de compresión y consultas por rango más rápidas que las colecciones normales. granularity debe ajustarse al intervalo de tus datos. TTL (expireAfterSeconds) purga los datos antiguos automáticamente. Usa $dateTrunc para agregación por tramos de tiempo.

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" }
  }}
])

Colecciones capped

Las colecciones capped mantienen el orden de inserción y sobrescriben los documentos más antiguos al llenarse — perfectas para logs, feeds de actividad reciente y ring buffers. Soportan inserciones de alto rendimiento y cursores tailable (como tail -f). Limitaciones: no puedes borrar documentos individuales ni hacer crecer documentos más allá de su tamaño original. Los change streams son la alternativa moderna para el tailing en tiempo real.

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
})

Tamaño BSON y límites de documentos

El límite de 16MB por documento BSON es un tope duro — usa Object.bsonsize() para comprobar tamaños. Los arrays grandes (miles de elementos) hinchan los documentos y ralentizan las actualizaciones (MongoDB reescribe el documento completo al actualizar). Para datos sin límite (reseñas, comentarios, entradas de log), usa una colección aparte con una referencia. Para blobs binarios de más de 16MB, usa GridFS o almacenamiento externo con una URL de referencia.

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

Comparación con SQL y migración

Mapeo de SQL a MongoDB

Este mapeo es la forma más rápida de aprender MongoDB para desarrolladores SQL. La diferencia clave: MongoDB no tiene esquema fijo (los documentos de una colección pueden diferir), y los 'joins' se sustituyen embebiendo datos relacionados o usando $lookup (más lento que los joins de SQL — diseña tu esquema para minimizarlos). El GROUP BY de SQL se mapea a la etapa de agregación $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 } } }
])

Migrar desde SQL

La migración no es un mapeo 1:1 de tabla a colección — el esquema debe rediseñarse para el modelo documental de MongoDB. Embebe los datos pequeños, exclusivos y accedidos juntos con frecuencia (perfil de un usuario + direcciones). Mantén referencias para datos grandes, compartidos o ilimitados (pedidos de un cliente). La herramienta Relational Migrator de MongoDB automatiza buena parte de este análisis. Planifica el esquema, no lo portes tal cual.

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

Transacciones vs ACID de SQL

MongoDB ofrece ACID: las operaciones de un solo documento son siempre atómicas (sin transacción), y las transacciones multidocumento (4.0+) dan ACID completo entre colecciones. La diferencia clave: SQL aplica ACID por defecto en cada sentencia, mientras que MongoDB fomenta un diseño de esquema que mantenga los datos relacionados en un documento (atómico por defecto) y usa transacciones solo cuando de verdad hacen falta. Prefiere embeber para evitar la sobrecarga de las transacciones.

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)

Normalización vs desnormalización

SQL normaliza para evitar duplicación; MongoDB desnormaliza por velocidad de lectura. El compromiso: los datos desnormalizados se leen más rápido pero son más difíciles de actualizar (varios documentos). Desnormaliza los datos que cambian poco (nombres de países, catálogos de productos) y referencia los que cambian a menudo (precios, inventario). El equilibrio correcto depende de tu proporción lectura/escritura — monitoriza y ajusta.

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

Cuándo usar MongoDB vs SQL

No existe la base de datos 'mejor' universal. MongoDB destaca en esquemas flexibles, datos jerárquicos y escalado horizontal. SQL destaca en integridad relacional, joins complejos y cargas transaccionales intensivas. Muchas apps modernas son políglotas — MongoDB para catálogos/contenido/datos generados por usuarios, PostgreSQL para transacciones financieras. Ajusta la base de datos a la carga de trabajo, no al hype.

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

Agregación avanzada

$merge y $out (vistas materializadas)

$out reemplaza una colección destino con la salida del pipeline (destructivo). $merge es más flexible — puede insertar, reemplazar o combinar con documentos existentes, habilitando vistas materializadas incrementales. $merge es preferible para refrescos programados: solo se actualizan los datos nuevos o cambiados. Las vistas materializadas precalculan agregaciones costosas para consultas rápidas de dashboard.

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" } }
])

Funciones de ventana ($setWindowFields)

$setWindowFields (5.0+) trae las funciones de ventana de SQL a MongoDB: totales acumulados, rankings, medias móviles y lag/lead. partitionBy es PARTITION BY, sortBy es ORDER BY, y window define el marco. Las ventanas por rango usan valores (p. ej., últimos 7 días) mientras que las de documentos usan conteos de filas. Imprescindible para analítica de series temporales y 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 y $reduce

$map, $filter y $reduce son operadores funcionales de arrays para transformaciones dentro del documento. $map transforma cada elemento, $filter conserva los que coinciden y $reduce agrega un array a un solo valor. La variable 'as' ($$this por defecto) nombra el elemento actual. Estos operadores evitan $unwind en muchas operaciones de arrays — más rápidos y limpios.

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 y multi-pipeline

$facet ejecuta varios sub-pipelines sobre la misma entrada en una sola consulta — perfecto para dashboards que necesitan varias vistas de los datos (desgloses, estadísticas, top N). Cada sub-pipeline es independiente. El resultado es un documento con un campo por sub-pipeline. Esto reemplaza múltiples viajes de red y garantiza un snapshot consistente.

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 y $bucketAuto

$bucket categoriza documentos en rangos de valores explícitos (como el CASE WHEN de SQL) — genial para tramos de precios, grupos de edad e histogramas. $bucketAuto deja que MongoDB calcule los límites para producir un número objetivo de buckets (bueno para explorar datos cuando no conoces la distribución). Los límites incluyen el extremo izquierdo y excluyen el derecho.

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

Monitorización y resolución de problemas

Métricas clave que monitorizar

Las cuatro señales doradas de MongoDB: conexiones (acercarse al límite indica fugas o falta de pooling), ratio de acierto de caché (leer páginas de disco indica presión de RAM), retardo de replicación (un secundario rezagado arriesga pérdida de datos en el failover) y profundidad de colas (contención de bloqueos). Configura alertas sobre las cuatro. Un ratio de acierto de caché cayendo es la señal de alarma de rendimiento número uno.

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

Resolver la contención de bloqueos

MongoDB usa bloqueo a nivel de documento (WiredTiger), así que la contención es rara — pero las consultas sin índice, las ordenaciones enormes y las transacciones largas igualmente bloquean. currentOp encuentra al culpable; killOp lo detiene. La causa raíz suele ser un índice que falta (ejecuta explain). Las migraciones de esquema sobre colecciones grandes pueden bloquear durante mucho tiempo — hazlas en lotes pequeños o en horas de bajo tráfico.

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"))

Análisis de memoria y disco

La caché de WiredTiger es la frontera de la memoria — si está llena de páginas sucias, las escrituras se ralentizan (vaciando a disco). Si 'pages read into cache' es alto, añade RAM o índices para reducir escaneos. Elimina los índices sin uso — consumen disco Y memoria Y ralentizan las escrituras. Monitoriza el crecimiento del almacenamiento para prever necesidades de capacidad. En clústers sharded, los jumbo chunks (demasiado grandes para migrar) indican un shard key pobre.

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]
}))

Análisis de logs

El log de mongod registra operaciones lentas, elecciones, errores y más. Configura slowOpThresholdMs para capturar consultas por encima de tu SLO. getLog recupera el buffer circular en memoria; el log en disco persiste tras reinicios. logRotate archiva el log actual (úsalo con logrotate para rotación diaria). Aumenta temporalmente la verbosidad de componentes para depuración profunda (p. ej., replication: 2 para problemas de elecciones) y luego restablece.

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 }
})

Errores comunes y soluciones

Estos son los errores de MongoDB más comunes. Los errores de clave duplicada vienen de violaciones del _id o de índices únicos — manéjalos en el código de la app. Los límites de memoria de la agregación se resuelven con allowDiskUse (más lento, pero funciona). WriteConflict en transacciones es normal bajo contención — reintenta. Los timeouts de cursor significan que tu procesamiento por lotes es demasiado lento — usa lotes menores o noCursorTimeout (pero cierra siempre los cursores).

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?