UUIDs in MongoDB

The two subtypes#

The legacy subtype predates any agreement on layout, and the drivers still name the conventions after themselves. CSHARP_LEGACY writes the mixed-endian form, JAVA_LEGACY reverses each of the two 8-byte halves, and PYTHON_LEGACY writes the bytes straight through. All three produce subtype 3, and nothing in the stored value says which of them wrote it.

How the mismatch shows up#

• A query by UUID returns nothing, although the document is visibly there.
• The same logical identifier appears as two distinct binary values in one collection.
• An aggregation groups by UUID and produces double the expected number of buckets.
• An export to JSON shows base64 that does not match the identifier the application prints.

Moving to subtype 4#

Set the driver to the standard representation, then rewrite the affected documents: read each legacy value with the convention that wrote it, decode it to a UUID, and store it back as subtype 4. Do it once, verify the counts, and add a check that no subtype 3 values remain. A mixed collection is worse than either convention alone.

// mongosh: find documents still holding a legacy binary UUID
db.orders.find({ id: { $type: "binData" } })
    .toArray()
    .filter(doc => doc.id.sub_type === 3)
    .length;

RFC 9562 § 4 · UUID FormatThe byte order subtype 4 follows

UUID or ObjectId#

MongoDB's own ObjectId is 12 bytes: a 4-byte timestamp in seconds, a 5-byte value random per process, and a 3-byte counter. The timestamp leads, so ObjectIds sort by creation time. If identifiers never leave MongoDB, it is smaller and simpler. Use a UUID when the same identifier has to exist in other systems too: that is the one property ObjectId cannot give you.

• The BSON specificationBinary subtypes, including 3 and 4
• MongoDB: BSON typesHow binary data and ObjectId are stored