MongoDB binary subtype 4 explained

October 16, 2026 · 14 min read

In MongoDB, Binary subtype 4 (written 0x04 or UUID in Extended JSON) means “these sixteen bytes are a UUID in RFC 4122 byte order.” Drivers, Compass, and aggregation operators interpret subtype 4 consistently - unlike arbitrary Binary subtype 0 blobs or legacy subtype 3 GUID encoding.

What subtype 4 means

BSON Binary stores a subtype byte plus length plus payload. For UUIDs the payload is always 16 octets. Subtype 4 tells clients not to guess endianness: decode as RFC, render as canonical 8-4-4-4-12 lowercase hex with hyphens.

Greenfield applications should default to subtype 4. Subtype 3 remains for legacy .NET GUID compatibility - see the dedicated comparison article.

The 16-byte layout

RFC 4122 splits 128 bits into five fields. In subtype 4 binary storage, those fields appear as contiguous bytes in standard order - no hyphens on disk. Version and variant bits live in time_hi_and_version and clock_seq_hi; validators use them to reject garbage lengths that happen to be 16 bytes.

Field names you will see in docs

• time_low - 4 bytes
• time_mid - 2 bytes
• time_hi_and_version - 2 bytes (includes version nibble)
• clock_seq - 2 bytes (includes variant bits)
• node - 6 bytes (often MAC-derived in v1, random in v4/v7)

Educational diagrams break the hex into these names so endianness swaps are visible - when the first twelve bytes permute but node bytes match, you are comparing subtype 3 vs 4, not different UUIDs.

// Extended JSON (canonical)
{ "_id": { "$binary": { "base64": "VQ6EAOKbQdSnFkRmVUQAAA==", "subType": "04" } } }

// Same logical ID as string:
// 550e8400-e29b-41d4-a716-446655440000

Subtype 4 vs string UUID columns

Strings waste index space and invite case/hyphen inconsistencies. Subtype 4 gives bytewise equality and smaller indexes. Tools export base64 in JSON; use a converter to human form for tickets.

How to read and write subtype 4

Node UUID class, Java UuidRepresentation.STANDARD, and Python BSON UUID types write subtype 4 by default on modern versions. Validate inbound strings, convert once, store binary. Use the MongoDB UUID converter and UUID validator when debugging exports.

Related: MongoDB binary UUID explained · Subtype 03 vs 04 · Internal UUID storage

Browse all tools