Skip to content

MongoDB Шпаргалка

NoSQL-база данных документов для хранения больших объёмов данных.

01

С чего начать

Подключение к MongoDB

mongosh — современная оболочка MongoDB Shell (заменяет устаревшую mongo). Строка подключения соответствует формату URI mongodb://[user:pass@]host[:port]/[db][?options]. База /admin используется для аутентификации по умолчанию. Можно подключиться сразу к нужной базе, дописав её имя в 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()

Основы работы с базами

MongoDB создаёт базы и коллекции лениво: они появляются только после вставки первого документа. Команда 'use mydb' переключает контекст, но не создаёт базу до записи данных. show dbs не показывает пустые базы. dropDatabase безвозвратно удаляет все коллекции и их данные.

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

Коллекции

Коллекции — аналог таблиц в SQL, они хранят документы. Они создаются автоматически при первой вставке, но createCollection позволяет задать параметры, например capped (коллекции фиксированного размера, перезаписывающие старые документы — удобно для логов). stats() показывает размер хранения, число документов и сведения об индексах.

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

Типы данных BSON

BSON расширяет JSON типами, важными для приложений: ObjectId (12-байтные уникальные идентификаторы), ISODate, NumberDecimal (точная десятичная дробь для денег — без ошибок округления float), NumberLong (64-битные целые), BinData (двоичные данные) и другие. Использование NumberDecimal для валюты избавляет от классических ошибок с плавающей точкой.

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
}

Хелперы оболочки и справка

mongosh поддерживает полноценный JavaScript, поэтому в оболочке можно писать циклы, функции и переменные. .pretty() форматирует вывод для читаемости (в mongosh это поведение по умолчанию). load() выполняет .js-файл в контексте оболочки — удобно для повторяющихся админских скриптов. db.collection.help() перечисляет все доступные методы.

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

CRUD-операции

Вставка документов

MongoDB автоматически генерирует _id (ObjectId), если вы его не указали. _id должен быть уникальным в коллекции: дубликат вызывает ошибку записи. ordered:false позволяет insertMany продолжить вставку оставшихся документов после ошибки, повышая пропускную способность массовой загрузки.

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() возвращает курсор (вычисляемый лениво), findOne() возвращает один документ или null. Проекция управляет тем, какие поля вернуть: нельзя смешивать включение и исключение (кроме _id). Используйте 1 для включения, 0 для исключения. countDocuments точен; старый count() устарел для подсчёта с фильтром.

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

Обновление документов

updateOne/updateMany используют операторы обновления ($set, $inc и др.) для изменения отдельных полей. replaceOne заменяет весь документ, кроме _id. upsert:true создаёт новый документ, если совпадений нет, — удобно для шаблона «создать или обновить». Всегда используйте $set для обновления полей: «голый» объект заменяет документ (устаревшее поведение).

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

Операторы обновления

Операторы обновления меняют поля атомарно на уровне документа. $inc безопасен при конкурентности (нет гонки «чтение-изменение-запись»). $min/$max обновляют, только если новое значение меньше/больше. $currentDate удобен для меток «последнее изменение». Несколько операторов можно объединить в одном обновлении.

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

Удаление документов

deleteOne удаляет первое совпадение, deleteMany — все. deleteMany({}) очищает коллекцию, но сохраняет индексы (быстрее, чем drop + пересоздание, если нужно сохранить определения индексов). findOneAndDelete атомарно возвращает удалённый документ. Удаление необратимо — всегда тщательно проверяйте фильтр.

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

Операторы для массивов

$push добавляет в конец (допускает дубликаты), $addToSet — без дубликатов. $pull удаляет элементы, подходящие под условие. Позиционный оператор ($) ссылается на первый элемент массива, совпавший с запросом, — необходим для обновления конкретных элементов без знания индекса. $[] обновляет все элементы массива.

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

Запросы к документам

Операторы сравнения

Операторы сравнения — фундамент запросов. $in значительно эффективнее, чем несколько условий $or по одному полю. На одном поле можно комбинировать несколько операторов (например, $gte и $lte для диапазона). $exists:true находит документы с полем, $exists:false — без него.

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

Логические операторы

Неявное AND (запятая в фильтре) — самый частый и эффективный вариант. Явный $and нужен только для нескольких условий по одному полю (неявное AND по одному полю перекрывает более ранние условия). $or выполняет отдельные сканирования индексов и объединяет результаты — убедитесь, что поля в $or проиндексированы.

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

Операторы элементов и вычислений

$type фильтрует по типу BSON (полезно для полей смешанного типа). $regex поддерживает опции вроде 'i' (без учёта регистра), но regex без якоря в начале не может эффективно использовать индекс. $expr позволяет сравнивать поля документа между собой, чего обычные операторы не умеют. Используйте $expr умеренно: он может обходить индексы.

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

Операторы запросов к массивам

$all находит массивы, содержащие все указанные значения (порядок не важен). $elemMatch необходим, когда один элемент массива должен одновременно удовлетворять нескольким условиям (обычный запрос сопоставил бы элементы по отдельности). $size подходит только для точной длины: диапазона в $size нет, поэтому заранее вычисляйте и храните длину отдельным полем.

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

Методы курсора и сортировка

skip+limit реализует пагинацию, но skip становится медленным на больших смещениях (он сканирует все пропущенные документы). Для глубокой пагинации используйте keyset-пагинацию: фильтр по полю сортировки больше последнего увиденного значения. sort() может использовать индекс, чтобы избежать сортировки в памяти, — всегда индексируйте поля сортировки в больших коллекциях.

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

Индексирование

Создание индексов

Индексы резко ускоряют запросы, но замедляют запись и занимают диск. Одиночные индексы поддерживают запросы по этому полю в любом направлении сортировки. Составные индексы следуют правилу ESR (Equality, Sort, Range) для оптимального порядка. TTL-индексы автоматически удаляют документы по истечении срока — идеально для сессий и логов.

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

Просмотр и управление индексами

getIndexes перечисляет все индексы с ключами и опциями. hideIndex/unhideIndex позволяет проверить влияние удаления индекса, не удаляя его: планировщик игнорирует скрытые индексы. Если производительность не изменилась, индекс можно безопасно удалить. Всегда запускайте explain() до и после изменения индексов.

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

Особые типы индексов

Индексы 2dsphere обеспечивают геозапросы ($near, $geoWithin). Хешированные индексы поддерживают шардирование по хешу для равномерного распределения данных. Wildcard-индексы ($**) покрывают непредсказуемые и переменные имена полей — полезно для полиморфных данных. Частичные индексы индексируют только подходящие документы, экономя место, когда запросы идут лишь по подмножеству.

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 и планы запросов

explain() — основной инструмент производительности. COLLSCAN (сканирование коллекции) означает, что индекс не использовался, — тревожный знак для больших коллекций. IXSCAN означает использование индекса. totalDocsExamined >> nReturned говорит о плохом индексе (просматривается много документов ради немногих). hint() принудительно выбирает конкретный индекс, чтобы проверить выбор планировщика.

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

Практика индексирования

Правило ESR (Equality, Sort, Range) — важнейший принцип проектирования составных индексов: сначала поля с равенством, затем поля сортировки, затем диапазонные. Покрывающий запрос (все поля есть в индексе) не обращается к документу — это самый быстрый возможный запрос. Избегайте неиспользуемых индексов: каждый добавляет накладные расходы на запись.

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

Фреймворк агрегации

Основы конвейера агрегации

Конвейер агрегации обрабатывает документы последовательно по стадиям. $match в начале конвейера уменьшает рабочий набор (и может использовать индексы). $group — аналог SQL GROUP BY. $count — сокращение для $group + $project. Порядок важен: сначала фильтрация, затем группировка, затем сортировка, затем ограничение.

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

Всегда ставьте $match как можно раньше: он сокращает документы для всех последующих стадий и может использовать индексы. $project перестраивает документы и вычисляет новые поля с помощью выражений. Переименование и вычисление полей в $project часто делают перед $group. $unset — сокращение для исключения полей.

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 и аккумуляторы

$group — ключевая стадия агрегации. _id задаёт ключ группировки (null означает агрегировать все документы). $push собирает массив значений по группе, $addToSet убирает дубликаты. $first/$last ссылаются на порядок документов в группе — вызывайте $sort перед $group, если порядок важен. Лимит памяти — 100 МБ на стадию (для больших наборов используйте allowDiskUse).

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 (соединения)

$lookup выполняет левое внешнее соединение — как SQL LEFT JOIN. Соединённые данные попадают в поле-массив, имя которого задаёт 'as'. Форма с конвейером позволяет фильтровать и преобразовывать присоединённые документы. $unwind разворачивает поля-массивы (один выходной документ на элемент массива) — часто используется после $lookup для «уплощения» результатов. В 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 и $facet

$facet запускает несколько подконвейеров на одном входе — идеально для дашбордов, которым нужны несколько агрегаций (топ N, счётчики, разбивки) за один запрос. $bucket автоматически раскладывает значения по диапазонам. $unwind с preserveNullAndEmptyArrays сохраняет документы с пустым или отсутствующим массивом — полезно, чтобы не терять данные в конвейере.

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

Транзакции

ACID-транзакции

Многодокументные транзакции дают гарантии ACID между коллекциями (требуется реплика-сет или шардированный кластер). Передавайте сессию в каждую операцию транзакции. commitTransaction делает изменения постоянными и видимыми; abortTransaction откатывает все изменения. Держите транзакции короткими: они удерживают блокировки и влияют на производительность.

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 в транзакциях

Read concern определяет «свежесть» и согласованность чтения. 'snapshot' даёт транзакционно согласованный снимок между шардами — идеально для отчётности. Write concern управляет долговечностью: w:majority гарантирует репликацию до подтверждения (переживает смену primary), j:true ждёт записи в журнал. Более строгие уровни безопаснее, но медленнее.

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

Повторы и ошибки

MongoDB помечает повторяемые ошибки метками errorLabels: TransientTransactionError (повторять всю транзакцию) и UnknownCommitResult (повторять только commit). Продакшен-драйверы предлагают встроенные повторы. Всегда проектируйте транзакции идемпотентными, где это возможно. Избегайте долгих транзакций, удерживающих блокировки и блокирующих другие операции.

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

Атомарные операции над одним документом

Операции над одним документом атомарны по умолчанию — транзакция не нужна. findOneAndUpdate/findOneAndReplace/findOneAndDelete атомарно возвращают документ (удобно для генерации последовательных ID). Для многих задач встраивание связанных данных в один документ и атомарные операторы ($inc, $push) вовсе избавляют от необходимости в многодокументных транзакциях.

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

Двухфазный коммит (шаблон)

Шаблон двухфазного коммита имитирует распределённые транзакции без нативных многодокументных транзакций. Он отслеживает состояние 'pending', чтобы процесс восстановления мог продолжить или откатить операцию при сбое посреди перевода. Когда нативные транзакции доступны, используйте их: этот шаблон сложен и подвержен ошибкам, его сохраняют в основном для обучения и поддержки legacy-систем.

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

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

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

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

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

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

Моделирование данных

Встраивание против ссылок

Главное решение в моделировании MongoDB: встраивайте данные, к которым обращаются вместе и которые редко меняются; ссылайтесь на крупные, общие или независимо обновляемые данные. Встраивайте, когда связь «имеет» эксклюзивна (адреса пользователя). Ссылайтесь, когда данные переиспользуются (товар во многих заказах) или растут без ограничений (миллионы записей лога у пользователя).

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

Связи «один ко многим»

Для связей «немного» встраивайте. Для «много» ссылайтесь со стороны дочернего документа (ID родителя в каждом дочернем). Для «очень много» (миллионы) используйте шаблон корзин: группируйте дочерние документы в корзины, принадлежащие родителю (например, по месяцам), чтобы сбалансировать размер документа и скорость запросов. Так вы избегаете и неограниченных массивов, и избытка дочерних документов.

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

Связи «многие ко многим»

Для «многие ко многим» выбирайте подход по шаблонам запросов и объёму данных. Двусторонние массивы быстры, но требуют двойного сопровождения. Коллекция-связка (таблица соответствий) наиболее гибка и лучше масштабируется: она может хранить метаданные связи (дату зачисления, оценку) и не раздувает родительские документы.

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

Шаблоны проектирования схем

Шаблон атрибутов работает с сущностями с переменным набором атрибутов (товары с разными характеристиками): он избегает разреженных полей и позволяет динамические атрибуты. Полиморфный шаблон хранит родственные, но разные структуры в одной коллекции с дискриминатором типа. Шаблон выбросов обрабатывает исключительные документы (знаменитость с миллионами подписчиков), используя ссылки вместо встраивания.

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

Валидация схемы

Валидация схемы проверяет структуру документов при записи — ответ MongoDB на фиксированные схемы. validationLevel 'strict' проверяет все записи, 'moderate' — только вставки и полные обновления. validationAction 'error' отклоняет неверные документы, 'warn' пишет в лог, но принимает их. Валидация дополняет, а не заменяет валидацию на уровне приложения.

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

Реплика-сеты

Основы реплика-сета

Реплика-сет обеспечивает высокую доступность и масштабирование чтения. Только один член является primary (принимает записи), остальные реплицируют асинхронно. При отказе primary выборы автоматически повышают secondary. Нечётное число голосующих членов (минимум 3) избегает ничьих на выборах. rs.status() показывает здоровье, состояние и отставание репликации каждого члена.

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

Предпочтение чтения

Предпочтение чтения балансирует согласованность и нагрузку. primary гарантирует чтение последних записей. secondary/secondaryPreferred снимает чтения с primary, но данные могут быть устаревшими (отставание репликации, обычно миллисекунды). nearest минимизирует задержку — идеально для географически распределённых приложений. Аналитические и отчётные задачи стоит выполнять на secondary.

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

Write concern обменивает скорость на безопасность. w:1 подтверждает, как только записал primary (быстро, но есть риск потери данных при падении primary до репликации). w:majority гарантирует репликацию — запись переживает отказ одного узла (рекомендуется для важных данных). j:true ждёт сброса журнала на диск. Задайте разумное значение по умолчанию на уровне кластера.

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

Арбитры и выборы

Арбитры дают голос для достижения большинства, не храня данные, — полезно для развёртываний из двух узлов, но третий узел с данными предпочтительнее. Члены с priority 0 никогда не становятся primary (подходят для выделенных аналитических или DR-узлов). Скрытые члены исключены из read preference 'nearest' и идеальны для бэкапов. Отстающие члены запаздывают, что позволяет восстановиться после случайных удалений.

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 и внутренности репликации

Oplog (журнал операций) — capped-коллекция, записывающая каждую операцию: secondary применяют эти записи по порядку для репликации. Если secondary отстал сильнее, чем позволяет окно oplog, нужна полная ресинхронизация. printReplicationInfo показывает временной диапазон oplog, printSecondaryReplicationInfo — отставание каждого secondary. Больший oplog допускает более долгие простои.

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

Шардирование

Основы шардирования

Шардирование горизонтально масштабирует коллекцию на несколько шардов. Ключ шарда определяет распределение данных и неизменяем после шардирования. Хешированное шардирование распределяет равномерно (хорошо для монотонно растущих ключей вроде ObjectId); диапазонное позволяет адресные запросы, но может создавать горячие точки. Выбирайте ключ шарда внимательно — позже его трудно изменить.

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

Выбор ключа шарда

Ключ шарда — важнейшее решение при шардировании. Он должен поддерживать типичные запросы (запросы без ключа шарда идут на все шарды — scatter-gather). Высокая кардинальность предотвращает неперемещаемые огромные чанки. Монотонные ключи (метки времени, ObjectId) направляют все вставки на один шард — для них используйте хешированное шардирование. В составном ключе первым должно идти самое селективное поле.

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

Зоны и шардирование по тегам

Зоны (шардирование по тегам) направляют определённые диапазоны данных на конкретные шарды — это позволяет соблюдать требования к хранению данных (GDPR требует хранить данные ЕС в ЕС), обеспечивать геолокальность (быстрые региональные чтения) или уровни оборудования (горячие данные на SSD, холодные на HDD). Балансировщик учитывает диапазоны зон при миграции чанков. Сначала задайте теги шардов, затем диапазоны тегов.

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

Управление чанками

Чанки — единица перемещения данных между шардами. Балансировщик автоматически разделяет и мигрирует чанки, поддерживая баланс шардов. Огромные чанки превышают лимит размера и не могут мигрировать — избегайте их благодаря хорошей кардинальности ключа шарда. Размер чанка по умолчанию 128 МБ балансирует скорость миграции и накладные расходы. Ручные операции с чанками нужны для диагностики, а не в рутине.

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

Компоненты шардированного кластера

Шардированный кластер состоит из трёх компонентов: config-серверы (метаданные, развёрнутые как реплика-сет), маршрутизаторы mongos (несостоятельные маршрутизаторы запросов, к которым подключаются клиенты) и шарды (каждый — реплика-сет с частью данных). Клиенты никогда не подключаются к шардам напрямую. Удаление шарда запускает миграцию данных на оставшиеся шарды — медленный процесс, который нужно контролировать.

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

Безопасность и аутентификация

Аутентификация и пользователи

Аутентификация подтверждает личность. Создайте администратора до включения аутентификации, иначе вы потеряете доступ. Встроенные роли охватывают диапазон от чтения до полного администрирования. Используйте passwordPrompt() в оболочке, чтобы в истории не оставалось паролей в открытом виде. Каждый пользователь привязан к базе, но может иметь роли в других базах. В продакшене включайте TLS (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")

Встроенные и пользовательские роли

Встроенные роли покрывают типовые случаи, пользовательские позволяют реализовать минимальные привилегии. Привилегия связывает ресурс (база/коллекция) с разрешёнными действиями (find, insert, update и т. д.). Выдавайте минимум необходимого: пользователю для отчётов нужен только 'find' на конкретных коллекциях. Пользовательские роли хранятся в базе admin и переиспользуются между пользователями.

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

Шифрование TLS/SSL

TLS шифрует данные в пути — обязательно для продакшена. requireTLS отклоняет соединения без TLS. Для внутреннего PKI используйте аутентификацию по сертификатам x.509 (без паролей: сертификат и есть учётные данные). Пользователи x.509 хранятся в базе $external. В продакшене всегда используйте настоящий CA (или внутренний CA); самоподписанные сертификаты — только для тестов.

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

Сеть и аудит

bindIp ограничивает сетевые интерфейсы, на которых слушает MongoDB, — никогда не выставляйте MongoDB напрямую в интернет (bindIp: 0.0.0.0 без аутентификации стал причиной бесчисленных взломов). Аудит (только Enterprise) логирует операции, важные для безопасности и соответствия требованиям. В community-редакции можно использовать инструменты ОС (auditd) или логирование на уровне приложения.

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

Шифрование на уровне полей (CSFLE)

CSFLE шифрует чувствительные поля на клиенте, поэтому сервер, резервные копии и логи никогда не содержат открытый текст — сильнейшая защита данных. Детерминированное шифрование поддерживает запросы на равенство; случайное безопаснее, но не позволяет искать по значению. Автошифрование (через схему драйвера) прозрачно для кода приложения. Ключи шифрования хранятся в KMS (AWS KMS, локальный ключ и т. п.).

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

Резервное копирование и восстановление

mongodump и mongorestore

mongodump создаёт логическую резервную копию (файлы BSON): она переносима, но медленна для больших наборов и без --oplog не согласована по моменту времени между коллекциями. --drop удаляет существующие коллекции перед восстановлением. --archive + --gzip дают один сжатый файл. Для больших продакшен-бэкапов предпочитайте снимки файловой системы или Percona Backup, а не 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 и mongoimport

mongoexport/mongoimport работают с JSON/CSV — для обмена данными с другими системами, а не для бэкапов (они теряют типы BSON вроде ObjectId и точность Date). Для бэкапов используйте mongodump. Экспорт в CSV удобен для таблиц и BI-инструментов. Всегда указывайте --fields для предсказуемого порядка колонок в CSV. По умолчанию JSON-экспорт содержит один документ на строку (--jsonArray — один массив).

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

Снимки файловой системы

Снимки файловой системы — самый быстрый способ бэкапа больших наборов: они согласованно захватывают весь каталог данных. fsyncLock ненадолго блокирует записи и сбрасывает данные на диск, чтобы снимок был согласованным. Снимки почти мгновенны независимо от размера данных. Восстановление — просто копирование файлов обратно, гораздо быстрее mongorestore. Лучше всего работает на LVM, ZFS или облачных блочных хранилищах (снимки 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)

Восстановление на момент времени (oplog)

Восстановление на момент времени (PITR) восстанавливает состояние базы на конкретный момент — необходимо после случайных удалений или неудачных миграций. Делайте регулярные базовые бэкапы с --oplog, затем проигрывайте oplog до нужной метки времени (--oplogLimit останавливается прямо перед плохой операцией). PITR требует реплика-сета (oplog существует только на членах реплика-сета).

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

Atlas Backup и облачные варианты

MongoDB Atlas предлагает управляемые непрерывные бэкапы с восстановлением на момент времени — самый простой вариант для облака. Percona Backup for MongoDB (PBM) — ведущий открытый инструмент для самостоятельных кластеров: физические бэкапы и PITR для реплика-сетов и шардированных кластеров. Всегда проверяйте процедуру восстановления: бэкап, который нельзя восстановить, не является бэкапом.

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

Производительность и оптимизация

Профилирование медленных запросов

Профилировщик базы пишет операции медленнее slowms (по умолчанию 100 мс) в system.profile (capped-коллекция). Уровень 2 пишет всё — полезно для отладки, но влияет на производительность. Смотрите millis (длительность), nreturned (число документов) и docsExamined, чтобы найти неэффективные запросы. Отключайте профилирование, когда закончите.

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

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

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

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

# get current profiling level
db.getProfilingStatus()

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

explain() подробно

explain() — основной инструмент настройки. COLLSCAN означает полное сканирование коллекции — добавьте индекс. Отношение docsExamined к nReturned — ключевая метрика эффективности: если вы просматриваете 10000 документов, чтобы вернуть 10, индекс плохой. allPlansExecution показывает, почему планировщик выбрал свой план. Индексируйте поля равенства, сортировки и диапазона вашего запроса (правило 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

Рабочий набор и память

Производительность зависит от того, помещается ли рабочий набор (часто используемые данные) в RAM. Если wiredTiger.cache 'pages read into cache' велик, вы упираетесь в диск — добавьте RAM или индексы, чтобы сократить сканирования. mongotop показывает коллекции с высокой нагрузкой ввода-вывода; mongostat показывает частоты запросов, вставок, обновлений и отказов страниц. compact возвращает место, потраченное на удалённые и обновлённые документы.

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

Пулы соединений

Каждое соединение с MongoDB расходует память сервера — тысячи соединений ухудшают производительность. Используйте пул соединений (драйверы держат переиспользуемый пул) с maxPoolSize под вашу нагрузку (обычно 50–100). Делите один MongoClient на всё приложение — никогда не создавайте его на каждый запрос. Задайте maxIdleTimeMS, чтобы перерабатывать устаревшие соединения за балансировщиками.

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 }

Массовые записи и размеры пачек

Массовые записи группируют операции в один сетевой обход — гораздо быстрее отдельных операций. unordered:true максимизирует пропускную способность (продолжает после ошибок, распараллеливает на шардированных кластерах). Для больших импортов группируйте по 1000–5000 документов, балансируя память и число обходов. insertMany с ordered:false — самый быстрый способ загрузки данных.

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

Отслеживание изменений

Change streams позволяют приложениям реагировать на изменения данных в реальном времени, читая oplog. Каждое событие содержит тип операции, полный документ (для вставок и обновлений с опцией fullDocument) и токен возобновления. Сохраняйте токен, чтобы после перезапуска продолжить без пропусков и дубликатов событий. Требуется реплика-сет или шардированный кластер.

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

Фильтрация событий

Фильтруйте change streams конвейером агрегации: до приложения доходят только подходящие события, что снижает шум. По умолчанию обновления содержат только изменённые поля, а не полный документ; fullDocument:'updateLookup' подтягивает текущий документ (дополнительный запрос на каждое событие). fullDocumentBeforeChange (6.0+) включает документ до изменения — полезно для журналов аудита.

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 на базе и кластере

Change streams могут наблюдать за одной коллекцией, всей базой или всем кластером. Потоки уровня базы и кластера включают в каждое событие namespace (ns), чтобы было понятно, где произошло изменение. Используйте startAtOperationTime, чтобы воспроизвести изменения с конкретной точки oplog — полезно для бэкфилла или восстановления пропущенных событий после простоя.

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

Токены возобновления и надёжность

Токены возобновления гарантируют доставку как минимум один раз: сохраняйте их после обработки каждого события, чтобы после перезапуска продолжить ровно с того места. resumeAfter и startAfter похожи, но startAfter работает даже после событий инвалидации коллекции (например, drop). Всегда обрабатывайте ошибки и переподключайтесь с последним токеном. Токен непрозрачен — считайте его чёрным ящиком.

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

Сценарии использования Change Streams

Change streams питают архитектуры реального времени: инвалидацию кеша (удаление устаревших записей), живые уведомления (push через WebSocket), журналирование аудита (запись каждого изменения для соответствия требованиям) и ETL/синхронизацию (репликация в Elasticsearch, хранилище данных или другую систему). Они заменяют ручной опрос и триггеры чистой событийной моделью.

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

Администрирование и инструменты

Состояние сервера и мониторинг

serverStatus() — основной источник мониторинга: следите за соединениями, opcounters, долей попаданий в кеш и отставанием репликации. currentOp показывает выполняющиеся операции; killOp прекращает долгий запрос по его opid. Настройте агент мониторинга (Prometheus, Datadog, Atlas) для непрерывного сбора метрик. Ключевые алерты: число соединений приближается к лимиту, доля попаданий в кеш падает, отставание репликации растёт.

mongodb
# overall server status
db.serverStatus()

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

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

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

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

Статистика баз и коллекций

stats() показывает детали хранения: dataSize (логический), storageSize (физический, после сжатия WiredTiger — часто на 50–80% меньше) и indexSize. estimatedDocumentCount мгновенен (из метаданных коллекции), но приблизителен; countDocuments({}) точен, но сканирует. Используйте приблизительные счётчики для дашбордов, а точные — для биллинга. Следите за трендами роста хранения для планирования ёмкости.

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

WiredTiger переиспользует освобождённое место, поэтому compact нужен редко — только после удаления большой части коллекции. compact блокирует операции с коллекцией (до 4.4) или работает онлайн (4.4+). repairDatabase — разрушительное средство последней надежды, переписывающее все данные; всегда сначала делайте бэкап. Для возврата места в реплика-сете переселите secondary (удалите его данные и дайте ему заново реплицироваться).

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

mongostat даёт обзор нагрузки сервера в реальном времени (вставки, запросы, использование кеша, соединения) — как top/vmstat для MongoDB. mongotop показывает, какие коллекции потребляют больше всего времени ввода-вывода, — бесценно для поиска горячих коллекций. Оба поставляются с MongoDB. Для продакшен-мониторинга отправляйте лог mongod и метрики serverStatus в систему мониторинга для исторического анализа.

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

Конфигурация и запуск

Продакшен-MongoDB запускается через конфигурационный файл (mongod.conf в YAML). Ключевые настройки: cacheSizeGB ограничивает RAM для WiredTiger (по умолчанию 50% RAM — задайте явно на общих серверах), bindIp ограничивает сетевой доступ, authorization включает аутентификацию, replSetName/clusterRole включают репликацию/шардирование. Всегда проверяйте и версионируйте mongod.conf. serverCmdLineOpts показывает действующую конфигурацию.

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

Драйверы и интеграция

Драйвер Node.js

Драйвер Node.js построен на async/await и полностью поддерживает ES6+. Всегда используйте пул соединений (один MongoClient на приложение, переиспользуемый). Курсоры — асинхронные итераторы. Используйте for-await-of, чтобы перебирать их, не загружая все документы в память. Закрывайте клиент при остановке. Драйвер поддерживает транзакции, change streams и всю агрегацию.

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

Драйвер Python (PyMongo)

PyMongo — официальный драйвер Python. Он синхронный; для async используйте Motor (asyncio) или Beanie (ODM). Документы в PyMongo — обычные словари Python, специальные объекты не нужны. Конвейеры агрегации — списки словарей. Шаблон транзакции через контекстный менеджер обеспечивает автоматический commit/abort. Всегда используйте пул соединений (MongoClient по умолчанию пулит соединения).

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)

Индексы из драйверов

Создавайте индексы в скриптах установки или миграции приложения, а не при каждом запросе. createIndexes (во множественном числе) создаёт несколько индексов за один вызов. В продакшене построение индексов на больших коллекциях может быть медленным — MongoDB 4.2+ по умолчанию строит индексы неблокирующе. Версионируйте скрипты создания индексов вместе с миграциями схемы.

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

Параметры строки подключения

Строка подключения несёт всю конфигурацию клиента в виде параметров запроса. mongodb+srv использует DNS SRV-записи для обнаружения хостов — Atlas применяет этот формат; он упрощает строки подключения и автоматически обновляется при смене узлов. retryWrites=true (по умолчанию в современных драйверах) автоматически повторяет идемпотентные записи после сетевых сбоев. Задавайте разумные таймауты, чтобы избежать зависших соединений.

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

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

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

ODM и библиотеки верхнего уровня

ODM (Object Document Mapper) добавляют схемы, валидацию и API более высокого уровня. Mongoose (Node.js) — самый популярный: он навязывает структуру, которой у MongoDB нативно нет. Beanie — ведущий async-ODM для Python. ODM хороши для быстрой разработки и единообразия в команде, но добавляют накладные расходы и могут скрывать мощь MongoDB. Для критичных к производительности приложений используйте драйвер напрямую.

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 и крупные файлы

Основы GridFS

GridFS хранит файлы больше 16 МБ — лимита BSON-документа, разбивая их на чанки (по умолчанию 255 КБ) в fs.chunks с метаданными в fs.files. По сути это файловая система поверх MongoDB. Используйте её для файлов, которые превышают 16 МБ, но выигрывают от репликации и шардирования MongoDB. Для действительно крупных медиафайлов лучше подумать об S3 или CDN.

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

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

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

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

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

GridFS из драйверов

Драйверы предоставляют GridFS как потоковый API (GridFSBucket) — идеально для больших файлов, так как они никогда не загружаются в память целиком. Загрузка и скачивание — потоки, которые вы направляете в файлы или HTTP-ответы. metadata при загрузке доступна для запросов, как любое поле документа. Чанки GridFS автоматически собираются при скачивании. Имя корзины ('fs' по умолчанию) настраивается.

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

Коллекции временных рядов

Коллекции временных рядов (5.0+) оптимизированы для последовательных данных, упорядоченных по времени (датчики IoT, метрики, логи). Внутри они хранят данные в колоночном формате, достигая сжатия 30–50% и более быстрых диапазонных запросов, чем обычные коллекции. granularity должна соответствовать интервалу ваших данных. TTL (expireAfterSeconds) автоматически удаляет старые данные. Для агрегации по временным корзинам используйте $dateTrunc.

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

Capped-коллекции

Capped-коллекции сохраняют порядок вставки и перезаписывают самые старые документы при заполнении — идеально для логов, лент последней активности и кольцевых буферов. Они поддерживают высокую пропускную способность вставок и tailable-курсоры (как tail -f). Ограничения: нельзя удалять отдельные документы или увеличивать документы сверх исходного размера. Change streams — современная альтернатива для слежения в реальном времени.

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

Размер BSON и лимиты документов

Лимит BSON-документа в 16 МБ — жёсткий предел; проверяйте размеры через Object.bsonsize(). Большие массивы (тысячи элементов) раздувают документы и замедляют обновления (MongoDB перезаписывает весь документ при обновлении). Для неограниченных данных (отзывы, комментарии, записи логов) используйте отдельную коллекцию со ссылкой. Для двоичных объектов больше 16 МБ — GridFS или внешнее хранилище со ссылкой по 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

Сравнение с SQL и миграция

Соответствие SQL и MongoDB

Эта таблица соответствий — быстрый способ для SQL-разработчиков освоить MongoDB. Ключевое различие: в MongoDB нет фиксированной схемы (документы в коллекции могут различаться), а «соединения» заменяются встраиванием связанных данных или $lookup (медленнее SQL JOIN — проектируйте схему так, чтобы минимизировать их). SQL GROUP BY соответствует стадии агрегации $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 } } }
])

Миграция с SQL

Миграция — не взаимно однозначное отображение таблиц в коллекции: схему нужно перепроектировать под документную модель MongoDB. Встраивайте небольшие, эксклюзивные, часто читаемые вместе данные (профиль пользователя и адреса). Оставляйте ссылки для крупных, общих или неограниченно растущих данных (заказы клиента). Инструмент MongoDB Relational Migrator автоматизирует значительную часть анализа. Планируйте схему, а не просто переносите её.

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

Транзакции против SQL ACID

MongoDB обеспечивает ACID: операции над одним документом всегда атомарны (транзакция не нужна), а многодокументные транзакции (4.0+) дают полный ACID между коллекциями. Ключевое различие: SQL по умолчанию применяет ACID к каждому оператору, а MongoDB поощряет схему, где связанные данные лежат в одном документе (атомарность по умолчанию), и транзакции используются только при реальной необходимости. Предпочитайте встраивание, чтобы избежать накладных расходов транзакций.

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)

Нормализация против денормализации

SQL нормализует, чтобы избежать дублирования; MongoDB денормализует ради скорости чтения. Компромисс: денормализованные данные быстрее читать, но труднее обновлять (несколько документов). Денормализуйте редко меняющиеся данные (названия стран, каталоги товаров) и ссылайтесь на часто меняющиеся (цены, остатки). Правильный баланс зависит от соотношения чтений и записей — измеряйте и корректируйте.

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

Когда MongoDB, а когда SQL

Универсально «лучшей» базы нет. MongoDB сильна в гибких схемах, иерархических данных и горизонтальном масштабировании. SQL силён в реляционной целостности, сложных соединениях и тяжёлых транзакционных нагрузках. Многие современные приложения полиглотны: MongoDB для каталогов, контента и пользовательских данных, PostgreSQL для финансовых транзакций. Подбирайте базу под нагрузку, а не под хайп.

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

Продвинутая агрегация

$merge и $out (материализованные представления)

$out заменяет целевую коллекцию результатом конвейера (разрушительно). $merge гибче: он умеет вставлять, заменять или объединять с существующими документами, что позволяет строить инкрементальные материализованные представления. $merge предпочтителен для обновлений по расписанию: обновляются только новые и изменённые данные. Материализованные представления заранее вычисляют дорогие агрегации для быстрых запросов дашбордов.

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

Оконные функции ($setWindowFields)

$setWindowFields (5.0+) приносит оконные функции SQL в MongoDB: накопительные итоги, ранжирование, скользящие средние и lag/lead. partitionBy — это PARTITION BY, sortBy — ORDER BY, а window задаёт рамку. Диапазонные окна используют значения (например, последние 7 дней), а оконные по документам — число строк. Необходимо для аналитики временных рядов и отчётности.

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

$map, $filter и $reduce — функциональные операторы массивов для преобразований внутри документа. $map преобразует каждый элемент, $filter оставляет подходящие, $reduce сворачивает массив в одно значение. Переменная 'as' (по умолчанию $$this) задаёт имя текущего элемента. Это избавляет от $unwind во многих операциях с массивами — быстрее и чище.

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 и несколько конвейеров

$facet запускает несколько подконвейеров на одном входе в одном запросе — идеально для дашбордов, которым нужны разные срезы данных (разбивки, статистика, топ N). Каждый подконвейер независим. Результат — один документ с полем на каждый подконвейер. Это заменяет несколько сетевых обходов и гарантирует согласованный снимок.

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

$bucket раскладывает документы по явно заданным диапазонам значений (как SQL CASE WHEN) — отлично для ценовых уровней, возрастных групп и гистограмм. $bucketAuto позволяет MongoDB самим вычислить границы, чтобы получить заданное число корзин (удобно для исследования данных, когда распределение неизвестно). Границы включают левый край и исключают правый.

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

Мониторинг и диагностика

Ключевые метрики

Четыре главных сигнала для MongoDB: соединения (приближение к лимиту говорит об утечке или отсутствии пула), доля попаданий в кеш (чтение страниц с диска указывает на нехватку RAM), отставание репликации (отстающий secondary грозит потерей данных при переключении) и глубина очереди (конкуренция за блокировки). Настройте алерты на все четыре. Падение доли попаданий в кеш — главный признак проблем с производительностью.

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

Устранение конкуренции за блокировки

MongoDB блокирует на уровне документов (WiredTiger), поэтому конкуренция редка, но запросы без индексов, огромные сортировки и долгие транзакции всё равно блокируют. currentOp находит виновника; killOp его останавливает. Корень обычно в отсутствующем индексе (запустите explain). Миграции схемы на больших коллекциях могут блокировать надолго — выполняйте их небольшими пачками или при низкой нагрузке.

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

Анализ памяти и диска

Кеш WiredTiger — граница памяти: если он заполнен грязными страницами, запись замедляется (сброс на диск). Если 'pages read into cache' велик, добавьте RAM или индексы, чтобы сократить сканирования. Удаляйте неиспользуемые индексы: они занимают диск И память И замедляют запись. Следите за ростом хранения для прогноза ёмкости. В шардированных кластерах огромные чанки (слишком большие для миграции) указывают на плохой ключ шарда.

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

Анализ логов

Лог mongod фиксирует медленные операции, выборы, ошибки и многое другое. Задайте slowOpThresholdMs, чтобы захватывать запросы выше вашего SLO. getLog читает кольцевой буфер в памяти; лог на диске сохраняется между перезапусками. logRotate архивирует текущий лог (используйте с logrotate для ежедневной ротации). Временно повышайте подробность компонентов для глубокой отладки (например, replication: 2 при проблемах с выборами), затем возвращайте обратно.

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

Частые ошибки и решения

Это самые частые ошибки MongoDB. Ошибки дублирующегося ключа возникают из-за нарушения уникальности _id или уникального индекса — обрабатывайте их в коде приложения. Лимит памяти агрегации лечится allowDiskUse (медленнее, но работает). WriteConflict в транзакциях нормален при конкуренции — повторяйте. Таймауты курсора означают, что пакетная обработка слишком медленная: уменьшите пачки или используйте noCursorTimeout (но всегда закрывайте курсоры).

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?