Skip to content

MongoDB Folha de referência

Banco de dados de documentos NoSQL para armazenamento de dados de alto volume.

01

Primeiros Passos

Conectar ao MongoDB

mongosh é o MongoDB Shell moderno (substituindo o shell mongo legado). Uma string de conexão segue o formato URI mongodb://[user:pass@]host[:port]/[db][?opções]. O banco /admin é o banco de autenticação padrão. Você pode conectar diretamente a um banco específico acrescentando-o à 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()

Básico de Bancos de Dados

O MongoDB cria bancos e coleções preguiçosamente — só aparecem depois que você insere o primeiro documento. 'use mydb' troca o contexto, mas não cria o banco até que dados sejam escritos. show dbs não lista bancos vazios. dropDatabase deleta permanentemente todas as coleções e seus dados.

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

Coleções

Coleções são análogas a tabelas SQL e guardam documentos. São criadas automaticamente na primeira inserção, mas createCollection permite definir opções como capped (coleções de tamanho fixo que sobrescrevem documentos antigos — úteis para logs). stats() mostra tamanho de armazenamento, contagem de documentos e detalhes de í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 Dados BSON

BSON estende o JSON com tipos adicionais essenciais para aplicações: ObjectId (IDs únicos de 12 bytes), ISODate, NumberDecimal (decimal exato para dinheiro — evita arredondamento de float), NumberLong (ints de 64 bits), BinData (binário) e mais. Usar NumberDecimal para moeda evita os clássicos erros de ponto flutuante.

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 e Ajuda do Shell

mongosh suporta JavaScript completo, então você pode escrever loops, funções e variáveis no shell. .pretty() formata a saída para leitura (padrão no mongosh). load() roda um arquivo .js no contexto do shell — útil para scripts administrativos repetitivos. db.collection.help() lista as funções disponíveis.

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

Operações CRUD

Inserir Documentos

O MongoDB gera automaticamente um _id (ObjectId) se você não fornecer um. O _id deve ser único dentro de uma coleção — _id duplicado levanta um erro de escrita. ordered:false permite que insertMany continue inserindo os documentos restantes após um erro, melhorando o rendimento de cargas em massa.

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

Find / Consultar Documentos

find() retorna um cursor (avaliado preguiçosamente); findOne() retorna um único documento ou null. A projeção controla quais campos são retornados — não se pode misturar inclusão e exclusão (exceto _id). Use 1 para incluir, 0 para excluir. countDocuments é preciso; o antigo count() está obsoleto para contagens filtradas.

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

Atualizar Documentos

updateOne/updateMany usam operadores de atualização ($set, $inc etc.) para modificar campos específicos. replaceOne substitui o documento inteiro, exceto o _id. upsert:true cria um novo documento quando não há correspondência — útil para padrões 'criar ou atualizar'. Sempre use $set para atualizar campos; um objeto solto substitui o documento (comportamento legado).

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 Atualização

Operadores de atualização modificam campos atomicamente no nível do documento. $inc é seguro contra concorrência (sem corrida de ler-modificar-escrever). $min/$max só atualizam se o novo valor for menor/maior. $currentDate é prático para timestamps de 'última modificação'. Múltiplos operadores podem ser combinados numa única atualização.

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

Deletar Documentos

deleteOne remove a primeira correspondência; deleteMany remove todas. deleteMany({}) esvazia a coleção, mas mantém os índices (mais rápido que drop+recriar, se você quiser preservar as definições de índice). findOneAndDelete retorna o documento deletado atomicamente. Exclusões são irreversíveis — sempre filtre com 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 Atualização de Array

$push anexa (permite duplicatas); $addToSet deduplica. $pull remove elementos que casem com uma condição. O operador posicional ($) refere-se ao primeiro elemento do array casado pela consulta — essencial para atualizar elementos específicos do array sem conhecer seu índice. $[] atualiza cada um dos elementos do 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

Consultando Documentos

Operadores de Comparação

Operadores de comparação são a fundação das consultas. $in é muito mais eficiente que múltiplas condições $or no mesmo campo. Você pode combinar múltiplos operadores num campo (ex.: $gte e $lte para um intervalo). $exists:true acha documentos com o campo, $exists:false os que não o têm.

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

O AND implícito (vírgula num filtro) é o mais comum e eficiente. Use $and explícito só quando precisar de múltiplas condições no mesmo campo (AND implícito no mesmo campo sobrescreve condições anteriores). $or usa varreduras de índice separadas e mescla os resultados — garanta que os campos no $or estejam indexados, pelo desempenho.

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 e Avaliação

$type filtra por tipo BSON (útil para campos de tipos mistos). $regex suporta opções como 'i' (sem diferenciar caixa) — mas regex sem âncora de prefixo não consegue usar índices eficientemente. $expr habilita comparações entre campos do documento, o que operadores normais não fazem. Use $expr com parcimônia, pois pode contornar í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 Array

$all acha arrays contendo cada um dos valores especificados (independente de ordem). $elemMatch é essencial quando um elemento do array precisa satisfazer múltiplas condições simultaneamente (uma consulta simples casaria elementos individuais). $size casa apenas comprimentos exatos — não existe $size com intervalo; pre-compute e guarde o comprimento como campo separado.

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

Funções de Cursor e Ordenação

skip+limit implementa paginação, mas skip fica lento com offsets grandes (varre cada um dos documentos pulados). Para paginação profunda, use paginação por keyset: consulte com um filtro no campo de ordenação maior que o último valor visto. sort() pode usar um índice para evitar ordenação em memória — sempre indexe seus campos de ordenação em coleções 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

Indexação

Criar Índices

Índices aceleram drasticamente as consultas, mas retardam escritas e consomem disco. Índices de campo único suportam consultas naquele campo em qualquer direção de ordenação. Índices compostos seguem a regra ESR (Igualdade, Ordenação, Intervalo) para a ordem ótima. Índices TTL deletam automaticamente documentos após uma duração — perfeito para sessões e 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 e Gerenciar Índices

getIndexes lista cada um dos índices com suas chaves e opções. hideIndex/unhideIndex permite testar o impacto de remover um índice sem realmente descartá-lo — o planejador de consultas ignora índices ocultos. Se o desempenho continuar o mesmo, é seguro descartar. Sempre rode explain() antes e depois de mudanças de índice.

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 Especiais de Índice

Índices 2dsphere sustentam consultas geo ($near, $geoWithin). Índices hashed suportam sharding baseado em hash para distribuição uniforme de dados. Índices wildcard ($**) cobrem nomes de campos imprevisíveis/variáveis nos documentos — úteis para dados polimórficos. Índices parciais indexam só os documentos que casam, economizando espaço quando você consulta só um 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 e Planos de Consulta

explain() é a ferramenta primária de desempenho. COLLSCAN (varredura de coleção) significa que nenhum índice foi usado — um sinal de alerta para coleções grandes. IXSCAN significa que um índice foi usado. totalDocsExamined >> nReturned indica um índice ruim (examinar muitos documentos para retornar poucos). hint() força um índice específico, para testar a escolha do planejador.

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

Boas Práticas de Indexação

A regra ESR (Igualdade, Ordenação, Intervalo) é o princípio de design de índices compostos mais importante: ponha primeiro os campos filtrados por igualdade, depois os campos de ordenação, depois os de intervalo. Uma consulta coberta (cada campo está no índice) nunca busca o documento — a consulta mais rápida possível. Evite índices que você não usa; cada um adiciona custo de escrita.

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 Agregação

Básico do Pipeline de Agregação

O pipeline de agregação processa documentos através de estágios em sequência. $match cedo no pipeline reduz o conjunto de trabalho (e pode usar índices). $group é como o GROUP BY do SQL. $count é um atalho para $group + $project. A ordem importa: filtre primeiro, depois agrupe, depois ordene, depois limite.

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

Sempre ponha $match o mais cedo possível — reduz os documentos para cada um dos estágios seguintes e pode usar índices. $project remodela documentos e computa novos campos usando expressões. Renomear ou computar campos no $project é comum antes do $group. $unset é abreviação 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 e Acumuladores

$group é o estágio central de agregação. _id especifica a chave de agrupamento (use null para agregar cada um dos documentos). $push constrói um array de valores por grupo; $addToSet deduplica. $first/$last referem-se à ordem dos documentos no grupo — use $sort antes do $group se a ordem importa. O limite de memória é 100MB por estágio (use allowDiskUse para datasets 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 executa um left outer join — como o LEFT JOIN do SQL. Os dados unidos são colocados num campo array nomeado por 'as'. A forma de pipeline permite filtrar e transformar documentos unidos. $unwind deconstrói campos array (um documento de saída por elemento do array) — frequentemente usado após $lookup para achatar resultados. Joins são menos eficientes que dados embutidos no 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 e $facet

$facet roda múltiplos sub-pipelines sobre a mesma entrada — perfeito para dashboards que precisam de várias agregações (top N, contagens, desdobramentos) numa única consulta. $bucket auto-categoriza valores em intervalos. $unwind com preserveNullAndEmptyArrays mantém documentos cujo array está vazio ou ausente — útil para evitar perda de dados em 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

Transações

Transações ACID

Transações multi-documento fornecem garantias ACID entre coleções (requer um replica set ou cluster sharded). Passe a sessão a cada operação da transação. commitTransaction torna as mudanças permanentes e visíveis; abortTransaction desfaz todas. Mantenha as transações curtas — elas seguram travas e podem afetar o desempenho.

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 Transações

O read concern controla quão 'frescas' e consistentes são as leituras. 'snapshot' dá uma visão transacionalmente consistente entre shards — ideal para relatórios. O write concern controla a durabilidade: w:majority garante que os dados são replicados antes do ack (sobrevive a failover do primário); j:true espera o flush do journal. Concerns mais altos são mais seguros, porém mais 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

Lógica de Retry e Erros

O MongoDB marca erros repetíveis com errorLabels: TransientTransactionError (repita a transação inteira) e UnknownCommitResult (repita só o commit). Drivers de produção oferecem retry embutido. Sempre projete transações para serem idempotentes quando possível. Evite transações longas que seguram travas e bloqueiam outras operações.

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

Operações Atômicas de Documento Único

Operações de documento único são atômicas por padrão — sem transação. findOneAndUpdate/findOneAndReplace/findOneAndDelete retornam o documento atomicamente (ótimo para gerar IDs sequenciais). Para muitas cargas, embutir dados relacionados num documento e usar operadores atômicos ($inc, $push) elimina por completo a necessidade de transações multi-documento.

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 (Padrão)

O padrão two-phase commit simula transações distribuídas sem transações multi-doc nativas. Ele acompanha um estado 'pending' para que um processo de recuperação possa retomar ou desfazer se um crash ocorrer no meio da transferência. Prefira transações nativas quando disponíveis — esse padrão é complexo e propenso a erros, mantido principalmente por fins educativos e 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

Modelagem de Dados

Embutir vs Referenciar

A decisão cardinal na modelagem MongoDB: embuta para dados acessados juntos e que raramente mudam; referencie para dados grandes, compartilhados ou atualizados independentemente. Embuta quando a relação 'tem um' é exclusiva (os endereços de um usuário). Referencie quando os dados são reutilizados (um produto em muitos pedidos) ou crescem sem limites (milhões de entradas de log de um usuário).

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

Relações Um-para-Muitos

Para relações 'poucos', embuta. Para 'muitos', referencie do filho (ID do pai em cada filho). Para 'muitíssimos' (milhões), use o padrão bucket: agrupe documentos filhos em buckets pertencentes ao pai (ex.: por mês) para equilibrar tamanho de documento e velocidade de consulta. Isso evita tanto arrays sem limites quanto documentos filhos em excesso.

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

Relações Muitos-para-Muitos

Para muitos-para-muitos, escolha a abordagem pelos padrões de consulta e tamanho dos dados. Arrays dos dois lados são rápidos, mas exigem manutenção dupla. Uma coleção de junção (tabela de mapeamento) é a mais flexível e a que melhor escala — pode guardar metadados da relação (data de matrícula, nota) e evita inflar os documentos pais.

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

Padrões de Design de Schema

O Padrão de Atributos trata entidades com atributos variáveis (produtos com especificações diferentes) — evita campos esparsos e habilita atributos dinâmicos. O Padrão Polimórfico guarda formas relacionadas mas diferentes numa mesma coleção usando um discriminador de tipo. O Padrão Outlier trata documentos excepcionais (uma celebridade com milhões de seguidores) referenciando em vez de embutir.

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

Validação de Schema

A validação de schema impõe a estrutura dos documentos na escrita — a resposta do MongoDB aos schemas fixos. validationLevel 'strict' valida todas as escritas; 'moderate' valida só inserções e atualizações completas. validationAction 'error' rejeita documentos inválidos; 'warn' registra e aceita. A validação complementa (não substitui) a validação no nível da aplicação.

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

Básico de Replica Sets

Um replica set fornece alta disponibilidade e escala de leitura. Só um membro é primário (aceita escritas); os outros replicam de forma assíncrona. Se o primário falha, uma eleição promove um secundário automaticamente. Um número ímpar de membros votantes (mínimo 3) evita empates de eleição. rs.status() mostra a saúde, o estado e o atraso de replicação de cada membro.

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

A read preference equilibra consistência vs carga. primary garante que você sempre lê as escritas mais recentes. secondary/secondaryPreferred aliviam o primário, mas os dados podem estar desatualizados (atraso de replicação, tipicamente milissegundos). nearest minimiza a latência — ideal para apps geograficamente distribuídos. Cargas analíticas/de relatórios devem usar leituras secundárias.

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

O write concern troca velocidade por segurança. w:1 confirma assim que o primário escreve (rápido, mas arrisca perda de dados se o primário cair antes de replicar). w:majority garante que a escrita é replicada — sobrevive à falha de um único nó (recomendado para dados importantes). j:true espera o flush do journal em disco. Defina um padrão sensato no nível do cluster.

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

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

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

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

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

Arbiters e Eleição

Arbiters fornecem um voto para atingir maioria sem guardar dados — úteis em implantações de dois nós, mas um terceiro nó de dados é preferível. Membros com prioridade 0 nunca viram primários (bons para nós dedicados de análise ou DR). Membros hidden ficam de fora da read preference 'nearest' e são ideais para backups. Membros atrasados ficam para trás, permitindo recuperação de exclusões acidentais.

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 e Entranhas da Replicação

O oplog (log de operações) é uma coleção capped que registra cada escrita — os secundários aplicam essas entradas em ordem para replicar. Se um secundário ficar para trás além da janela do oplog, precisa de um resync completo. printReplicationInfo mostra o intervalo de tempo do oplog; printSecondaryReplicationInfo mostra o atraso de cada secundário. Oplogs maiores acomodam indisponibilidades mais longas.

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

Básico de Sharding

Sharding escala horizontalmente uma coleção por múltiplos shards. A shard key determina a distribuição dos dados e é imutável após o sharding. Sharding hashed distribui uniformemente (bom para chaves monotonicamente crescentes como ObjectId); sharding por intervalo habilita consultas direcionadas, mas pode causar hotspots. Escolha a shard key com cuidado — não pode ser trocada facilmente depois.

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

Seleção da Shard Key

A shard key é a decisão de sharding mais crítica. Ela deve suportar suas consultas comuns (consultas sem a shard key atingem cada um dos shards — scatter-gather). Alta cardinalidade impede jumbo chunks imóveis. Chaves monotônicas (timestamps, ObjectIds) fazem todas as inserções caírem num shard — use sharding hashed para elas. Chaves compostas devem começar pelo campo mais seletivo.

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 e Sharding Ciente de Tags

Zonas (sharding ciente de tags) roteiam intervalos de dados específicos a shards específicos — habilitando conformidade de residência de dados (GDPR exige dados da UE na UE), geolocalidade (leituras regionais rápidas) ou níveis de hardware (dados quentes em SSD, frios em HDD). O balancer respeita os intervalos de zona ao migrar chunks. Defina as tags de shard primeiro, depois as faixas de tags.

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

Gestão de Chunks

Chunks são a unidade de movimento de dados entre shards. O balancer divide e migra chunks automaticamente para manter os shards equilibrados. Jumbo chunks excedem o limite de tamanho e não podem migrar — evite-os com boa cardinalidade da shard key. O tamanho padrão de chunk de 128MB equilibra velocidade de migração e custo. Operações manuais de chunk são para solução de problemas, não rotina.

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 do Cluster Sharded

Um cluster sharded tem três componentes: servidores de configuração (metadados, implantados como replica set), roteadores mongos (roteadores de consulta sem estado, aos quais os clientes se conectam) e shards (cada um um replica set guardando um subconjunto dos dados). Clientes nunca conectam diretamente aos shards. Remover um shard dispara a migração dos dados aos shards restantes — processo lento que deve ser monitorado.

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

Segurança e Autenticação

Autenticação e Usuários

Autenticação verifica identidade. Crie o usuário admin antes de habilitar auth, ou você ficará trancado fora. As funções embutidas vão de somente leitura a admin total. Use passwordPrompt() no shell para evitar senhas em texto puro no histórico. Cada usuário tem escopo num banco, mas pode ter papéis em outros bancos. Habilite TLS em produção (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")

Funções Embutidas e Personalizadas

As funções embutidas cobrem casos comuns; as personalizadas habilitam o menor privilégio. Privilégios pareiam um recurso (banco/coleção) com ações permitidas (find, insert, update etc.). Conceda o mínimo necessário — um usuário de relatórios só precisa de 'find' em coleções específicas. Funções personalizadas ficam no banco admin e podem ser reutilizadas entre usuários.

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

Criptografia TLS/SSL

TLS criptografa dados em trânsito — obrigatório em produção. requireTLS rejeita conexões sem TLS. Para PKI interna, use autenticação por certificado x.509 (sem senhas — o certificado É a credencial). O banco $external guarda usuários x.509. Sempre use uma CA real (ou CA interna) em produção; certificados autoassinados são só para teste.

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

Rede e Auditoria

bindIp limita em quais interfaces de rede o MongoDB escuta — nunca exponha o MongoDB direto à internet (bindIp: 0.0.0.0 + sem auth já causou incontáveis violações). Auditoria (só Enterprise) registra operações relevantes à segurança, por conformidade. A edição community pode usar ferramentas no nível do SO (auditd) ou logging no nível da aplicação como alternativas.

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

Criptografia a Nível de Campo (CSFLE)

CSFLE criptografa campos sensíveis no cliente, para que o servidor, os backups e os logs nunca contenham texto puro — a proteção de dados mais forte. Criptografia determinística suporta consultas de igualdade; a aleatória é mais segura, mas não consultável. A cripto automática (via schema do driver) é transparente ao código do app. As chaves de criptografia são geridas num KMS (AWS KMS, chave 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 e Restauração

mongodump e mongorestore

mongodump cria um backup lógico (arquivos BSON) — portátil, mas lento para datasets grandes e sem consistência point-in-time entre coleções sem --oplog. --drop descarta as coleções existentes antes da restauração. --archive + --gzip produzem um único arquivo comprimido. Para backups de produção grandes, prefira snapshots de filesystem ou Percona Backup em vez de 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 e mongoimport

mongoexport/mongoimport trabalham com JSON/CSV — para troca de dados com outros sistemas, não para backups (perdem tipos BSON como ObjectId e a precisão de Date). Para backups use mongodump. Exportações CSV são ótimas para planilhas e ferramentas de BI. Sempre especifique --fields para uma ordem de colunas CSV previsível. Exportações JSON são limitadas a um documento por linha por padrão (--jsonArray para um ú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 de Filesystem

Snapshots de filesystem são a forma de backup mais rápida para datasets grandes — capturam o diretório de dados inteiro de forma consistente. fsyncLock bloqueia brevemente as escritas e descarrega no disco, para que o snapshot seja consistente. Snapshots são quase instantâneos, independentemente do tamanho dos dados. Restaurar é tão simples quanto copiar os arquivos de volta — muito mais rápido que mongorestore. Funciona melhor em LVM, ZFS ou armazenamento de blocos na nuvem (snapshots EBS).

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

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

# 3. unlock the database
db.fsyncUnlock()

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

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

Recuperação Point-in-Time (oplog)

A recuperação point-in-time (PITR) reconstrói o estado do banco num momento específico — essencial após exclusões acidentais ou migrações ruins. Faça backups de base regulares com --oplog, depois reproduza o oplog até o timestamp desejado (--oplogLimit para logo antes de uma operação ruim). PITR exige um replica set (o oplog só existe em membros de replica set).

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

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

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

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

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

Backup Atlas e Opções na Nuvem

MongoDB Atlas oferece backups contínuos gerenciados com recuperação point-in-time — o mais simples para implantações na nuvem. Percona Backup for MongoDB (PBM) é a principal ferramenta de backup open-source para clusters self-hosted, suportando backups físicos e PITR entre replica sets e clusters sharded. Sempre teste os procedimentos de restauração — um backup que você não consegue restaurar não é um 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

Desempenho e Otimização

Profiling de Consultas Lentas

O database profiler registra operações mais lentas que slowms (padrão 100ms) em system.profile (uma coleção capped). O nível 2 registra tudo — útil para depuração, mas impacta o desempenho. Olhe millis (duração), nreturned (documentos retornados) e docsExamined para achar consultas ineficientes. Desative o profiling quando 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()

Imersão em explain()

explain() é sua ferramenta principal de ajuste. COLLSCAN significa varredura completa da coleção — adicione um índice. A razão entre docsExamined e nReturned é a métrica-chave de eficiência: se você examina 10000 documentos para retornar 10, seu índice é ruim. allPlansExecution mostra por que o planejador escolheu seu plano. Indexe os campos de igualdade, ordenação e intervalo da sua consulta (regra 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 e Memória

O desempenho depende do working set (dados acessados com frequência) caber na RAM. Se 'pages read into cache' do wiredTiger.cache está alto, você está batendo no disco — adicione RAM ou índices para reduzir varreduras. mongotop mostra quais coleções estão quentes em I/O; mongostat mostra taxas de consulta/insert/update e faltas. compact recupera espaço em disco desperdiçado por documentos deletados/atualizados.

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

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

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

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

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

Pooling de Conexões

Cada conexão MongoDB consome memória do servidor — milhares de conexões degradam o desempenho. Use pooling de conexões (drivers mantêm um pool reutilizável) com maxPoolSize ajustado à sua carga (50-100 é típico). Compartilhe um único MongoClient pelo app — nunca crie um por requisição. Defina maxIdleTimeMS para reciclar conexões velhas atrás de load balancers.

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

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

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

Escritas em Massa e Tamanhos de Lote

Escritas em massa agrupam operações numa única ida e volta — muito mais rápido que operações individuais. unordered:true maximiza o rendimento (continua após erros, paraleliza em clusters sharded). Para importações grandes, agrupe em lotes de 1000-5000 documentos para equilibrar memória e idas e voltas. insertMany com ordered:false é a forma mais rápida de carregar dados.

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

Observando Mudanças

Change streams permitem que aplicações reajam a mudanças de dados em tempo real, acompanhando o oplog. Cada evento inclui o tipo de operação, o documento completo (para inserts/updates com a opção fullDocument) e um resume token. Guarde o resume token para retomar após um reinício sem perder ou duplicar eventos. Requer replica set ou cluster 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()

Filtrando Eventos de Mudança

Filtre change streams com um pipeline de agregação — só eventos que casem chegam ao seu app, reduzindo ruído. Por padrão, updates incluem apenas os campos alterados, não o documento completo; fullDocument:'updateLookup' busca o documento atual (consulta extra por evento). fullDocumentBeforeChange (6.0+) inclui o documento antes da mudança — útil para logs de auditoria.

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 em Banco/Cluster

Change streams podem observar uma única coleção, um banco inteiro ou o cluster inteiro. Streams de banco e de cluster incluem o namespace (ns) em cada evento, para que você saiba onde a mudança ocorreu. Use startAtOperationTime para reproduzir mudanças de um ponto específico do oplog — útil para backfill ou recuperar eventos perdidos após uma indisponibilidade.

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 e Confiabilidade

Resume tokens garantem entrega pelo-menos-uma-vez — persista-os depois de processar cada evento, para que um reinício retome exatamente de onde você parou. resumeAfter e startAfter são parecidos; startAfter funciona mesmo depois de eventos de invalidação de coleção (como um drop). Sempre trate erros e reconecte com o último token. O token é opaco — trate-o como caixa preta.

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 Change Streams

Change streams sustentam arquiteturas em tempo real: invalidação de cache (deletar entradas velhas), notificações ao vivo (pushes WebSocket), logs de auditoria (registrar cada mudança por conformidade) e ETL/sincronização (replicar para Elasticsearch, um data warehouse ou outro sistema). Eles substituem polling manual e triggers por um modelo limpo e reativo dirigido a 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

Administração e Ferramentas

Status do Servidor e Monitoramento

serverStatus() é a fonte primária de monitoramento — acompanhe conexões, opcounters, taxa de acerto do cache e atraso de replicação. currentOp mostra operações em execução; killOp termina uma consulta de longa duração pelo seu opid. Defina um agente de monitoramento (Prometheus, Datadog, Atlas) para coletar essas métricas continuamente. Alertas-chave: contagem de conexões perto do limite, taxa de acerto do cache caindo, atraso de replicação subindo.

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

Estatísticas de Banco e Coleção

stats() mostra detalhes de armazenamento: dataSize (lógico), storageSize (físico, após compressão WiredTiger — frequentemente 50-80% menor) e indexSize. estimatedDocumentCount é instantâneo (dos metadados da coleção), mas aproximado; countDocuments({}) é preciso, mas varre. Use contagens estimadas para dashboards e exatas para cobrança. Monitore tendências de crescimento de armazenamento para planejar capacidade.

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 e Repair

WiredTiger reutiliza espaço em disco liberado, então compact raramente é necessário — só depois de deletar uma grande fração de uma coleção. compact bloqueia operações na coleção (antes da 4.4) ou roda online (4.4+). repairDatabase é um último recurso destrutivo que reescreve cada um dos dados — sempre faça backup antes. Para recuperar espaço num replica set, faça resync de um secundário (delete seus dados e deixe-o re-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 e mongostat

mongostat dá uma visão em tempo real da carga do servidor (inserts, consultas, uso de cache, conexões) — como top/vmstat para MongoDB. mongotop mostra quais coleções consomem mais tempo de I/O — inestimável para achar coleções quentes. Ambos vêm com o MongoDB. Para monitoramento de produção, envie o log do mongod e as métricas serverStatus a um sistema de monitoramento para análise histórica.

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

Configuração e Inicialização

MongoDB de produção roda via arquivo de config (mongod.conf em YAML). Configurações-chave: cacheSizeGB limita a RAM do WiredTiger (o padrão usa 50% da RAM — defina explicitamente em servidores compartilhados), bindIp restringe o acesso de rede, authorization habilita auth, e replSetName/clusterRole habilitam replicação/sharding. Sempre revise e versione seu mongod.conf. serverCmdLineOpts mostra a configuração ativa.

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 Integração

Driver Node.js

O driver Node.js é baseado em async/await, com suporte completo a ES6+. Sempre use pooling de conexões (um MongoClient por app, reutilizado). Cursores são iteráveis assíncronos. Use for-await-of para iterar sem carregar cada um dos documentos na memória. Feche o cliente ao desligar. O driver suporta transações, change streams e a gama completa de recursos de agregação.

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

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

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

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

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

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

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

Driver Python (PyMongo)

PyMongo é o driver oficial Python. É síncrono; para async, use Motor (asyncio) ou Beanie (ODM). Dicionários PyMongo são dicts Python comuns — sem objetos especiais. Pipelines de agregação são listas de dicts. O padrão de transação com context-manager garante commit/abort automáticos. Sempre use pooling de conexões (o MongoClient padrão agrupa conexões).

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 pelos Drivers

Crie índices nos scripts de setup/migração da aplicação, não a cada requisição. createIndexes (plural) cria múltiplos índices numa chamada. Em produção, builds de índice em coleções grandes podem ser lentos — MongoDB 4.2+ constrói índices de forma não bloqueante por padrão. Versione seus scripts de criação de índice junto às migrações de schema.

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

Opções da String de Conexão

A string de conexão carrega toda a configuração do cliente como parâmetros de consulta. mongodb+srv usa registros DNS SRV para descobrir hosts — o Atlas usa esse formato; simplifica as strings de conexão e se atualiza sozinho quando os nós mudam. retryWrites=true (padrão nos drivers modernos) repete automaticamente escritas idempotentes após oscilações de rede. Defina timeouts razoáveis para evitar conexões presas.

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 e Bibliotecas de Nível Mais Alto

ODMs (Object Document Mappers) adicionam schemas, validação e uma API de nível mais alto. Mongoose (Node.js) é o mais popular — impõe a estrutura que o MongoDB não tem nativamente. Beanie é o principal ODM assíncrono Python. ODMs são ótimos para desenvolvimento rápido e consistência de equipe, mas adicionam custo e podem esconder o poder do MongoDB. Para apps críticos de desempenho, use o driver cru.

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 e Arquivos Grandes

Básico de GridFS

GridFS guarda arquivos maiores que o limite de 16MB do documento BSON, dividindo-os em chunks (padrão 255KB) guardados em fs.chunks, com metadados em fs.files. É efetivamente um filesystem sobre o MongoDB. Use-o para arquivos que excedem 16MB, mas que ainda se beneficiam da replicação e do sharding do MongoDB. Para mídia realmente grande, considere S3 ou um CDN em vez disso.

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 pelos Drivers

Drivers expõem GridFS como uma API de streaming (GridFSBucket) — ideal para arquivos grandes, pois nunca são carregados inteiramente na memória. Upload/download são streams que você conecta a arquivos ou respostas HTTP com pipe. metadata nos uploads é consultável como qualquer campo de documento. Chunks do GridFS são remontados automaticamente no download. O nome do bucket ('fs' por padrão) é configurável.

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

Coleções de Série Temporal

Coleções de série temporal (5.0+) são otimizadas para dados sequenciais ordenados no tempo (sensores IoT, métricas, logs). Guardam os dados em formato parecido com colunar por baixo, alcançando 30-50% de compressão e consultas de intervalo mais rápidas que coleções comuns. granularity deve casar com o intervalo dos seus dados. TTL (expireAfterSeconds) purga dados antigos automaticamente. Use $dateTrunc para agregação por intervalo de tempo.

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

Coleções Capped

Coleções capped mantêm a ordem de inserção e sobrescrevem os documentos mais antigos quando cheias — perfeitas para logs, feeds de atividade recente e ring buffers. Suportam inserções de alto rendimento e cursores tailable (como tail -f). Limitações: não se pode deletar documentos individuais nem crescer documentos além do tamanho original. Change streams são a alternativa moderna para acompanhamento em tempo 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
})

Tamanho BSON e Limites de Documento

O limite de 16MB do documento BSON é um teto rígido — use Object.bsonsize() para verificar tamanhos de documentos. Arrays grandes (milhares de elementos) inflam documentos e retardam updates (o MongoDB reescreve o documento inteiro no update). Para dados sem limites (avaliações, comentários, entradas de log), use uma coleção separada com referência. Para blobs binários acima de 16MB, use GridFS ou armazenamento externo com uma referência de URL.

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

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

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

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

Comparação e Migração com SQL

Mapeamento SQL para MongoDB

Este mapeamento é a forma mais rápida para desenvolvedores SQL aprenderem MongoDB. A diferença-chave: MongoDB não tem schema fixo (documentos numa coleção podem diferir), e 'joins' são substituídos tanto por embutir dados relacionados quanto por $lookup (mais lento que joins SQL — projete seu schema para minimizá-los). GROUP BY do SQL mapeia para o estágio de agregação $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 } } }
])

Migrando do SQL

A migração não é um mapeamento 1:1 de tabela para coleção — o schema deve ser redesenhado para o modelo de documentos do MongoDB. Embuta dados pequenos, exclusivos e frequentemente acessados juntos (perfil + endereços de um usuário). Mantenha referências para dados grandes, compartilhados ou sem limites (pedidos de um cliente). A ferramenta Relational Migrator do MongoDB automatiza boa parte dessa análise. Planeje o schema, não apenas porte.

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

Transações vs ACID do SQL

MongoDB fornece ACID: operações de documento único são sempre atômicas (sem transação), e transações multi-documento (4.0+) fornecem ACID completo entre coleções. A diferença-chave: SQL assume ACID em cada instrução, enquanto MongoDB incentiva o design de schema que mantém dados relacionados num documento (atômico por padrão) e usa transações só quando realmente necessário. Prefira embutir para evitar o custo de transações.

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)

Normalização vs Desnormalização

SQL normaliza para evitar duplicação; MongoDB desnormaliza pela velocidade de leitura. A troca: dados desnormalizados são mais rápidos de ler, mas mais difíceis de atualizar (múltiplos documentos). Desnormalize dados que mudam raramente (nomes de países, catálogos de produtos) e referencie dados que mudam com frequência (preços, estoque). O equilíbrio certo depende da sua razão leitura/escrita — monitore e ajuste.

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

Quando Usar MongoDB vs SQL

Não existe um banco 'melhor' universal. MongoDB é excelente em schemas flexíveis, dados hierárquicos e escala horizontal. SQL é excelente em integridade relacional, joins complexos e cargas transacionais pesadas. Muitos apps modernos são poliglotas — MongoDB para catálogos/conteúdo/dados gerados por usuários, PostgreSQL para transações financeiras. Case o banco à carga de trabalho, não ao 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

Agregação Avançada

$merge e $out (Views Materializadas)

$out substitui uma coleção alvo pela saída do pipeline (destrutivo). $merge é mais flexível — pode inserir, substituir ou combinar com documentos existentes, habilitando views materializadas incrementais. $merge é preferido para atualizações agendadas: só dados novos/alterados são atualizados. Views materializadas pré-computam agregações caras para consultas de dashboard rápidas.

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

Funções de Janela ($setWindowFields)

$setWindowFields (5.0+) traz funções de janela do SQL para o MongoDB: totais móveis, rankings, médias móveis e lag/lead. partitionBy é PARTITION BY, sortBy é ORDER BY, e window define o quadro. Janelas de intervalo usam valores (ex.: últimos 7 dias), enquanto janelas de documentos usam contagens de linhas. Essencial para análises e relatórios de séries temporais.

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 e $reduce

$map, $filter e $reduce são operadores de array funcionais para transformações dentro do documento. $map transforma cada elemento, $filter mantém os elementos que casam, e $reduce agrega um array num único valor. A variável 'as' (padrão $$this) nomeia o elemento atual. Estes evitam $unwind para muitas operações de array — mais rápidos e mais limpos.

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 e Multi-Pipeline

$facet roda múltiplos sub-pipelines sobre a mesma entrada numa única consulta — perfeito para dashboards que precisam de várias visões dos dados (desdobramentos, estatísticas, top N). Cada sub-pipeline é independente. O resultado é um documento com um campo por sub-pipeline. Isso substitui múltiplas idas e voltas e garante um 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 e $bucketAuto

$bucket categoriza documentos em intervalos de valor explícitos (como CASE WHEN do SQL) — ótimo para faixas de preço, grupos de idade e histogramas. $bucketAuto deixa o MongoDB computar os limites para produzir um número alvo de buckets (bom para exploração de dados quando você não conhece a distribuição). Limites são inclusivos à esquerda, exclusivos à direita.

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

Monitoramento e Solução de Problemas

Métricas-Chave a Monitorar

Os quatro sinais dourados do MongoDB: conexões (aproximação do limite sinaliza vazamentos ou falta de pooling), taxa de acerto do cache (páginas lidas do disco indica pressão de RAM), atraso de replicação (um secundário atrasado arrisca perda de dados no failover) e profundidade de fila (contenção de travas). Defina alertas para os quatro. Uma taxa de acerto do cache caindo é o sinal de alerta de desempenho nº 1.

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

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

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

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

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

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

Resolvendo Contenção de Travas

MongoDB usa travas no nível de documento (WiredTiger), então contenção é rara — mas consultas sem índice, ordenações enormes e transações longas ainda bloqueiam. currentOp acha o culpado; killOp o interrompe. A causa raiz costuma ser um índice ausente (rode explain). Migrações de schema em coleções grandes podem travar por muito tempo — execute-as em lotes pequenos ou em tráfego baixo.

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álise de Memória e Disco

O cache do WiredTiger é a fronteira da memória — se está cheio de páginas sujas, as escritas ficam lentas (descarregando no disco). Se 'pages read into cache' está alto, adicione RAM ou índices para reduzir varreduras. Descarte índices não usados — consomem disco E memória E retardam escritas. Monitore o crescimento de armazenamento para prever necessidades de capacidade. Em clusters sharded, jumbo chunks (grandes demais para migrar) indicam uma shard key ruim.

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álise de Logs

O log do mongod registra operações lentas, eleições, erros e mais. Defina slowOpThresholdMs para capturar consultas acima do seu SLO. getLog recupera o ring buffer em memória; o log em disco persiste entre reinícios. logRotate arquiva o log atual (use com logrotate para rotação diária). Aumente temporariamente a verbosidade de componentes para depuração profunda (ex.: replication: 2 para problemas de eleição), depois redefina.

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

Erros Comuns e Soluções

Estes são os erros MongoDB mais comuns. Erros de chave duplicada vêm de violações de _id ou de índice único — trate-os no código do app. Limites de memória de agregação se resolvem com allowDiskUse (mais lento, mas funciona). WriteConflict em transações é normal sob contenção — repita. Timeouts de cursor significam que seu processamento em lote está lento demais — use lotes menores ou noCursorTimeout (mas sempre feche os 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?