Documents & Collections

Anatomy of a Document

A document is an ordered set of key-value pairs, similar to a JavaScript object. Values can be strings, numbers, booleans, dates, arrays, nested sub-documents, or null. Because a document can nest other documents and arrays inside it, a single document can represent what would be several joined rows in a relational schema - a customer with an embedded array of addresses, for example.

Field names are case-sensitive, cannot contain a null character, and by convention avoid starting with "$" or containing "." (both have special meaning to the query language). Document size is capped at 16MB, which matters if you are tempted to embed unbounded amounts of data into a single document.

Collections vs. Tables

A collection groups documents that are conceptually similar - a "users" collection, an "orders" collection - but MongoDB does not enforce that every document in a collection has the same fields or types unless you add schema validation yourself. This is often summarized as MongoDB having a "flexible" or "dynamic" schema, in contrast to a relational table's fixed column definitions.

Collections are created implicitly the first time you insert into them, and MongoDB creates the containing database implicitly too, the first time you write to a collection inside it - there is no CREATE TABLE step required to get going.

db.users.insertMany([
  { name: "Ada", email: "ada@example.com" },
  { name: "Grace", email: "grace@example.com", phone: "555-0101" },
  { name: "Alan", nickname: "Al", roles: ["admin", "editor"] }
])

// All three live happily in the same "users" collection,
// even though their field sets differ.

The _id Field

Every document must have a unique "_id" field that serves as its primary key within the collection. If you do not supply one on insert, MongoDB automatically generates an ObjectId - a 12-byte value encoding a timestamp, a random machine/process identifier, and an incrementing counter, which makes it unique across a distributed system without any central coordination.

You can also supply your own "_id" (a string, a number, anything comparable) if it makes sense for your domain - for example using an email address as "_id" for a users collection to get uniqueness enforcement for free. Once set, "_id" is immutable; you cannot update it on an existing document.

db.users.insertOne({ name: "Ada Lovelace" })
// _id is auto-assigned, e.g. ObjectId("64f1c2a5e4b0a1b2c3d4e5f6")

db.users.insertOne({ _id: "ada@example.com", name: "Ada Lovelace" })
// _id is the string you supplied; inserting another document
// with the same _id will throw a duplicate key error

Flexible Schema Is a Tool, Not a Free Pass

The absence of an enforced schema does not mean you should design without one - it means schema enforcement moves from the database to your application (or to MongoDB's optional schema validation rules). Most real applications still have an implicit schema in mind for each collection; MongoDB just does not stop you from violating it accidentally, so disciplined application code and, ideally, validation rules matter more than they would in a relational system.