Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 70 ยท Documents and BSON

_id and ObjectId

Understand the MongoDB _id rule, how an ObjectId is built from a timestamp, random value and counter, and when to use custom ids, UUIDs or natural keys.

Every MongoDB document has an _id field. It is the document's primary key: unique within its collection, always indexed, and the fastest way to fetch one specific document. If you insert a document without an _id, MongoDB creates one for you, and the value it creates is almost always an ObjectId.

This lesson explains the rules for _id, takes an ObjectId apart so you can see what its 24 hex characters mean, and compares your choices: the default ObjectId, a UUID, a natural key such as an email address, or a compound value. The practice engine in this tutorial uses simple counters for _id; here you build an ObjectId decoder and generator of your own to see how the real thing works.

The _id rules

Unique No two documents in a collection share an _id.
Immutable You cannot change an _id after insert.
Indexed Lookups by _id are always fast.
Any type Except an array.
1 / 2

The _id rules

  • Every document in a collection has exactly one _id.
  • It must be unique in the collection. MongoDB maintains a unique index on _id for you and you cannot drop it.
  • It is immutable: to change it you insert a new document and delete the old one.
  • It can be almost any BSON type (number, string, ObjectId, UUID, even an embedded document), but not an array.
  • If you do not supply one, the driver (not the server) normally generates an ObjectId on the client and places _id first in the document.

Because the driver creates the id, you know it as soon as you call insertOne, before the server answers. The result also returns it: { acknowledged: true, insertedId: ObjectId("...") }. In mongosh it looks like this:

JavaScript
db.users.insertOne({ name: "Mia" })
// { acknowledged: true, insertedId: ObjectId('65e5a1f0f1c2d3e4a51a2b3d') }

db.users.find({ _id: ObjectId("65e5a1f0f1c2d3e4a51a2b3d") })

Note the ObjectId(...) wrapper in the filter. { _id: "65e5a1f0f1c2d3e4a51a2b3d" } compares against a string and finds nothing, since an ObjectId and a string with the same characters are different BSON types (BSON Types). Forgetting the conversion is the most common "my document is there but find returns nothing" bug when ids arrive from a URL or JSON body.

What is inside an ObjectId

An ObjectId is 12 bytes, written as 24 hexadecimal characters. The layout in current MongoDB versions is:

Bytes Hex characters Meaning
4 first 8 Seconds since the Unix epoch (big-endian)
5 next 10 A random value generated once per process
3 last 6 A counter, starting at a random number and incrementing

This design gives several useful properties without any coordination between servers:

  • Uniqueness without a central counter. Two application servers create ids at the same time and do not collide, because their 5-byte random values differ and each keeps its own counter. The counter makes ids unique within one process in the same second.
  • Roughly time-ordered. Because the timestamp comes first, newer ids sort after older ids, and inserts land near the end of the _id index, which is cheap for the index.
  • The creation time is built in. You can read it back with ObjectId("...").getTimestamp() in the shell, or decode it yourself.

The caveat is "roughly". Ids made in the same second by different machines have no defined order among themselves, so do not use _id as an exact insertion sequence. Also, an ObjectId reveals when a document was created, which matters if you expose it in public URLs and the creation time is sensitive.

The first stand-in decodes ObjectIds into their three parts:

JS Decoding an ObjectId

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The first two ids share a timestamp, so they were created in the same second by the same process, and only the counter differs. The third was created 228 seconds later.

Generating ObjectIds

A generator only needs those three ingredients. The second stand-in builds ids from a timestamp, a fixed per-process random part and a counter, so you can see why ids are unique and sort by time. (Real drivers pick the random part and the counter's starting value at random, once per process. The values are fixed here so the output stays the same on every run.)

JS A tiny ObjectId generator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The sort check works because a fixed-width hexadecimal timestamp sorts correctly as text, and because the counter increases within a second. That is also why _id order is a decent proxy for creation order, although never a guarantee across machines.

Choosing your own _id

You are free to set _id yourself. The choice depends on your data.

Default ObjectId. The right choice for most collections. It is compact (12 bytes), generated on the client, and time-ordered.

UUID. Useful when ids must be created in many places and exposed to other systems that already use UUIDs. Store them as the binary UUID type (16 bytes), not as 36-character strings, which more than double the size in the index. Random UUIDs (version 4) are not time-ordered, so inserts scatter across the _id index, which costs more for very write-heavy collections than ObjectIds do.

Natural key. A value that already identifies the thing, such as an email, an ISBN or a country code. It saves an extra unique index and one field. The danger is that natural keys change (people change email addresses), and _id cannot be changed, so a change means copying the document and updating every reference. Use a natural key only for values that are truly stable.

Surrogate key. A meaningless generated id, like an ObjectId. It never needs to change, which is why it is the safe default. You can still enforce uniqueness of the natural value with a unique index on a normal field (Index Types).

Compound _id. An embedded document such as { tenant: "acme", n: 1 }. It works, and equality on it depends on field order (Documents, JSON and Field Types), so it is easy to get wrong. Prefer a normal _id plus a compound unique index.

The third stand-in shows the duplicate-key behaviour when two documents try to share an _id, with each kind of key.

JS Unique _id and duplicate keys

Press Run (or Ctrl + Enter) to see the console output here.

No output.

On a real server the failure is a MongoServerError with code 11000 (E11000 duplicate key error). The same error appears for any unique index, not just _id, and an unordered bulk insert reports it per document (Inserting Documents).

Ids in your application

  • Treat ids as opaque. Do not parse them to make decisions, other than reading the timestamp for debugging.
  • Convert ids at the boundary: a string from a URL or JSON body becomes new ObjectId(string) before it reaches a query. Validate it first, because an invalid string throws.
  • In JSON APIs, an ObjectId is usually serialised as its 24-character hex string.
  • Never reuse an _id after deleting a document if other documents still refer to the old one.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A document exists with _id ObjectId('65e5a1f0f1c2d3e4a51a2b3d'). Why does find({ _id: '65e5a1f0f1c2d3e4a51a2b3d' }) return nothing?

    Types matter in equality. Wrap the value as an ObjectId in the filter.
  2. 2. Which part of an ObjectId makes ids from different servers unlikely to collide without coordination?

    The 5-byte random value differs per process and the 3-byte counter distinguishes ids made in the same second, so no central coordination is needed.
  3. 3. Why is an email address a risky _id?

    An _id cannot be modified. If the natural key changes, you must copy the document and fix every reference.
  4. 4. What can you say about ordering ObjectIds?

    The leading timestamp makes them sort by creation second, but ids from different processes in the same second have no defined order.

Summary

  • _id is the unique, immutable, always-indexed primary key of a document; it can be any type except an array.
  • If you omit it, the driver generates an ObjectId and it is placed first in the document.
  • An ObjectId is 12 bytes: 4 of timestamp, 5 of per-process random, 3 of counter. It is roughly time-ordered.
  • Filter with ObjectId("..."), not with a plain string.
  • Prefer surrogate ids. Use natural keys only when they never change, and store UUIDs as binary.
  • A duplicate _id or unique-index value raises error code 11000.

Now put documents into a collection with Inserting Documents.