Документ
и BSON

Категория

Модель данных

Уровень

Начальный

Связанные темы

Вставка, типы в фильтрах, проекция

Зачем это знать

Понимать, что именно лежит в базе и почему "65000" и 65000 — разные значения

§1Документ: пары «поле — значение»

Документ — это набор пар «поле — значение». Значением может быть число, строка, дата, массив или другой документ. Поэтому карточка товара помещается в один документ целиком, а не разносится по шести таблицам.

Ниже — документ товара из базы курса:

В этом документе видны три свойства модели. specs — массив строк, он лежит прямо в документе: отдельной таблицы «характеристики» нет. stock — массив документов, вложенность может быть любой глубины. Поле discount есть у этого товара и может отсутствовать у соседнего — коллекция это допускает.

§2BSON: не текст, а двоичная запись

Выглядит документ как JSON, но хранится иначе. Формат называется BSON — Binary JSON, двоичная запись документа. Отличия от JSON:

Следствие для практики: тип значения хранится вместе со значением. Строка "21990" и число 21990 — разные значения, и запрос «дороже 20000» найдёт только второе. Разбирается это в модуле 2, но возникает здесь, на уровне хранения.

§3Типы значений

Полный список типов BSON длинный, в работе встречается десяток. В таблице ниже — как тип называется в базе и во что он превращается в Python.

Проверить тип каждого поля можно прямо из Python — драйвер уже перевёл значения в объекты языка:

one = db["products"].find_one({"_id": "p-012"})

for name, value in one.items():
    print(f"{name:10} {type(value).__name__}")

auto doc = products.find_one(make_document(kvp("_id", "p-012")));

for (const auto& element : doc->view()) {
    std::cout << std::left << std::setw(10) << element.key()
              << bsoncxx::to_string(element.type()) << std::endl;
}

var raw bson.Raw
products.FindOne(ctx, bson.D{{Key: "_id", Value: "p-012"}}).Decode(&raw)

elements, _ := raw.Elements()
for _, element := range elements {
    fmt.Printf("%-10s %s\n", element.Key(), element.Value().Type)
}

one = products.find({ "_id" => "p-012" }).first

one.each { |name, value| puts format("%-10s %s", name, value.class) }

_id        str
sku        str
title      str
brand      str
category   str
price      int
specs      list
stock      list
rating     float
reviews    int
added      datetime
discount   int

_id       string
sku       string
title     string
brand     string
category  string
price     int32
specs     array
stock     array
rating    double
reviews   int32
added     date
discount  int32

_id        string
sku        string
title      string
brand      string
category   string
price      32-bit integer
specs      array
stock      array
rating     double
reviews    32-bit integer
added      UTC datetime
discount   32-bit integer

_id        String
sku        String
title      String
brand      String
category   String
price      Integer
specs      Array
stock      Array
rating     Float
reviews    Integer
added      Time
discount   Integer

§4Сколько весит документ

Размер документа считает сама база — оператором $bsonSize. По нему оценивают, сколько места займёт коллекция, когда документов станет много.

db.products.aggregate([
  { $match: { _id: { $in: ["p-012", "p-020"] } } },
  { $project: { title: 1, size: { $bsonSize: "$$ROOT" } } }
])

[
  { _id: 'p-012', title: 'Монитор Dell P2422H', size: 314 },
  { _id: 'p-020', title: 'Кабель USB-C 2 м', size: 323 }
]

У кабеля название вдвое короче, а документ на девять байт больше: размер определяется структурой — числом полей, элементов массива и вложенных объектов. Служебные байты длины и типа тоже занимают место.

Предел в 16 МБ на документ выглядит недостижимым, но он ставит границу подходу «положим всё в один документ»: список из миллиона заказов клиента в его карточку не поместится. Как выбирают между вложением и ссылкой, разобрано в модуле 6.

§5Поле _id

В каждом документе есть поле _id — первичный ключ. Правила у него три:

• оно обязательное: если вы его не указали, сервер добавит его сам;
• оно уникальное внутри коллекции: индекс по _id создаётся автоматически и снять его нельзя;
• его нельзя изменить у существующего документа — только удалить документ и записать заново.

Значением _id может быть что угодно: строка, число, дата, вложенный документ. В нашей базе это осмысленные строки — "p-012", "o-0001", "c-003": по такому ключу видно, что перед вами, ещё до чтения документа. Если же _id не задать, сервер поставит ObjectId — 12-байтовый идентификатор.

result = box.insert_one({
    "sku": "SKU-AC-022", "title": "Коврик для мыши XL", "price": 1290,
})

print("присвоенный _id:", result.inserted_id)
print("тип:", type(result.inserted_id).__name__)
print("время создания:", result.inserted_id.generation_time)

auto result = box.insert_one(make_document(
    kvp("sku", "SKU-AC-022"),
    kvp("title", "Коврик для мыши XL"),
    kvp("price", 1290)));

auto oid = result->inserted_id().get_oid().value;
std::cout << "присвоенный _id: " << oid.to_string() << std::endl;
std::cout << "время создания: " << oid.get_time_t() << std::endl;

res, err := box.InsertOne(ctx, bson.D{
    {Key: "sku", Value: "SKU-AC-022"},
    {Key: "title", Value: "Коврик для мыши XL"},
    {Key: "price", Value: 1290},
})
if err != nil {
    log.Fatal(err)
}

oid := res.InsertedID.(bson.ObjectID)
fmt.Println("присвоенный _id:", oid.Hex())
fmt.Printf("тип: %T\n", oid)
fmt.Println("время создания:", oid.Timestamp().UTC())

result = box.insert_one({
  "sku" => "SKU-AC-022", "title" => "Коврик для мыши XL", "price" => 1290
})

oid = result.inserted_id
puts "присвоенный _id: #{oid}"
puts "тип: #{oid.class}"
puts "время создания: #{oid.generation_time}"

присвоенный _id: 6aa71d38b90e39ca06d0652f
тип: ObjectId
время создания: 2026-09-13 22:01:28+00:00

присвоенный _id: 6aa720f5a9158e554300ecd1
время создания: 1789337845

присвоенный _id: 6aa720b3dc05457956c79cee
тип: bson.ObjectID
время создания: 2026-09-13 22:16:19 +0000 UTC

присвоенный _id: 6aa7760bf7cda459834ce6ad
тип: BSON::ObjectId
время создания: 2026-09-14 04:20:27 UTC

§6ObjectId по байтам

ObjectId — 12 байт с фиксированной структурой. Записывается он как 24 шестнадцатеричных знака: каждый байт — два знака. Разберём по байтам один из полученных выше — 6aa08c51503a4f190a669c88.

Из устройства следуют два практических вывода. Первый: ObjectId примерно упорядочен по времени — сортировка по _id почти совпадает с сортировкой по дате создания, и отдельное поле «когда создан» иногда не нужно. Второй: ObjectId выдаёт время создания записи — это не всегда желательно, если идентификатор виден снаружи, в адресной строке.

§7Одна коллекция — разные формы

Коллекция не требует, чтобы документы были одинаковыми. Схемы у неё нет — по умолчанию сервер примет документ любой формы. В нашей коллекции товаров это видно сразу:

Это свойство даёт свободу — новое поле добавляется без миграции всей коллекции, — и оно же оставляет опечатку незамеченной: опечатка в имени поля не будет замечена. Запись salaryy вместо salary создаст новое поле. Как поставить базе правила и заставить её проверять форму документа, разберём в главе 3.1.

§8Типы в Compass

Тот же документ в Compass. Тип здесь виден по тому, как записано значение: строки в кавычках, числа без кавычек, дата — как ISODate с расшифровкой рядом, массив — как Array (3) со свёрнутым содержимым.

Явно тип пишется в табличном виде — это третья кнопка в правом верхнем углу списка. Там Compass ставит тип в шапку каждого столбца: _id String, price Int32, rating Double. И если в столбце встретится несколько типов, он покажет их списком — так опечатка вроде цены, записанной строкой, находится глазами, без единого запроса.

§9Частые ошибки

§10Проверьте себя

§11Шпаргалка

Итог главы

Документ — это пары «поле — значение», где значением может быть массив или другой документ; хранится он в двоичном формате BSON, который помнит тип каждого значения и длину каждой части. Поле _id есть всегда: заданное вами или сгенерированный сервером ObjectId, в первых байтах которого лежит время создания. Форма документов внутри коллекции может различаться: это даёт свободу при развитии проекта и оставляет опечатку в имени поля незамеченной. В следующей главе начнём класть документы в базу сами.