Part of Familiars: the small, sharp libraries I carved out of Xapiand. This one is an identifier that weighs less than it should: cuuid.
A UUID is 128 bits, and the reason we love it is that we can pretend those bits are random: generate one anywhere, never coordinate, and trust that it will not collide. That is the right mental model for a version-4 UUID, which really is random. It is quietly wrong for a time-based UUID, the kind you reach for when you also want ids that sort by when they were made. A time UUID is not random at all. It is a 60-bit timestamp, a 14-bit clock sequence, and a 48-bit node identifier, packed into the same 128 bits and dressed up in the familiar hyphenated hex.
That distinction is worth money on the wire, because a stream of these from one server is enormously repetitive. The node is identical for every id the machine ever mints. The high bits of the timestamp barely move from one id to the next. Storing all sixteen bytes, every time, is storing the same node and nearly the same timestamp prefix over and over. cuuid is the value type that stops doing that. This post is about the format it mints today, v6: an 8-byte, time-sortable, coordination-free id. There is an older v1 format underneath it, and I will get to why it is still there.
Condensing the structure
Section titled “Condensing the structure”cuuid does the ordinary things a UUID type should: generate, parse, format to the canonical string, validate, expose the field accessors. Its interesting move is serialization. The plain form is honest and simple, a tag byte 0x01 then the sixteen UUID bytes. But when the fields can be represented in less space, it emits a condensed encoding instead, packing them smaller and dropping what is redundant, so the same identifier goes onto the wire in fewer bytes. unserialise() reverses it exactly; the round-trip is byte-for-byte identical to the value you started with.
How small? 8 bytes for any present-day timestamp, half of UUIDv7’s sixteen and equal to a 64-bit Snowflake, and unlike Snowflake it needs no worker-id registry to get there. The folklore 4-byte figure is real only for timestamps within a year or so of cuuid’s 2016 epoch: the trick strips leading zero bytes off a rebased timestamp, and today’s timestamps have few left to strip.
This matters in a search engine specifically, because ids are everywhere: every document has one, every posting references one, they are stored, indexed, replicated, and shipped across the cluster constantly. Shaving bytes off the id is not a one-time win, it is a saving that recurs on every document in the system.
Sorting, and the 1.64 ms floor
Section titled “Sorting, and the 1.64 ms floor”Can it sort by time, the way a Snowflake does? Two answers, because there are two forms.
On the wire, yes: the condensed bytes put the timestamp most-significant-first, so a raw lexicographic sort of the encoded ids is a sort by creation time, down to a resolution floor of about 1.64 milliseconds. That floor is not arbitrary, and it is worth understanding because it is a direct consequence of the size trick. To reach 8 bytes, the compact form does not store the low 14 bits of the 100-nanosecond timestamp; it folds them into the clock field to save the space. What is left sorts cleanly only down to 2 to the 14th ticks, and 2 to the 14th times 100 nanoseconds is 1.6384 milliseconds. Above that, order is exact; below it, the low bits are hiding inside a scrambled clock field, and two ids from the same 1.64 ms window can come back in either order. It is the same class of floor UUIDv7 and ULID have below their millisecond resolution, and you buy past it only by spending bytes: keeping a real sub-millisecond tie-breaker costs the space the fold just saved.
In the canonical sixteen-byte form, v6 sorts by time too, timestamp first, at the same 1.64 ms floor: the minted id already carries the folded clock field, so the low bits are scrambled in both forms. That order is a big part of why v6 exists, because the older v1 layout was the opposite. Sort raw v1 bytes and you get a full-range backward jump every seven minutes, when the low 32 bits of the timestamp wrap and yank the sort back to the start. That wart is exactly what UUIDv6 was standardized to cure, by moving the timestamp to the front, and it is the layout cuuid stores now. So the 8-byte wire and the 16-byte canonical form both sort to 1.64 ms, and you index whichever representation fits.
The node, and the dice
Section titled “The node, and the dice”Rebuilding the shared node on decode is where cuuid used to embarrass itself. The compact form does not store the 48-bit node; it stores a 7-bit salt and reconstructs a synthetic node deterministically from the timestamp, clock, and salt. That reconstruction needs a mixing function, and the original code reached for the obvious one: seed a std::mt19937 and pull two draws. Constructing a Mersenne Twister initializes its whole 624-word state, every single time, on both encode and decode, and it dominated everything. Building that engine alone takes about 930 nanoseconds today, and the compact path paid it each way, two to three orders of magnitude more than Snowflake, UUIDv7, or ULID.
The node’s actual value is arbitrary; it only has to be deterministic, carry the salt, and set the multicast bit. So I swapped the Mersenne Twister for a splitmix64 mixer that does the identical job from the same seed, and the whole compact path fell with it: about 11 nanoseconds to encode and 12 to decode on an Apple M4 Pro. (Decode owed a little more to a byte-at-a-time loop unpacking the wire; folding that into a single machine byteswap took it from about 16 down to about 12.)
The old v1 codec got cheaper too, without changing a byte of its output. It still needs the Mersenne Twister’s first two draws, but those depend on only 399 of the 624 state words, so it now computes just those. That brings v1 to about 604 nanoseconds to encode and 610 to decode: better, and still about fifty times slower than v6, because the dice are still there.
Here is the compact path next to the other time-sortable ids, by wire size, sort resolution, and the cost to encode and decode one on the M4 Pro:
| wire size | sortable (wire) | encode + decode | |
|---|---|---|---|
| cuuid v6 | 8 bytes | yes, ~1.64 ms | ~11 ns + ~12 ns |
| cuuid v1 (legacy) | 8 bytes | yes, ~1.64 ms | ~604 ns + ~610 ns |
| Snowflake | 8 bytes | yes, 1 ms | ~1 ns + ~3 ns |
| UUIDv7 | 16 bytes | yes, 1 ms | ~0.8 ns + ~0.4 ns |
| UUIDv6 | 16 bytes | yes, 100 ns | ~0 ns |
A different mixer reconstructs a different node, so the wire bytes move with it: swapping the dice makes a new format. That is what makes this v6, told apart from v1 by the version nibble, rather than a silent change slipped under the old ids.
Two formats, one nibble
Section titled “Two formats, one nibble”So cuuid carries two condensed formats now, and tells them apart by the one field a UUID already has for the purpose: the version nibble. A v1 value stays version 1 and encodes with the Mersenne Twister; a v6 value is version 6, encodes with splitmix64, and lays its bytes out in UUIDv6 order. On encode the nibble picks the codec for free; the condensed wire carries no nibble, so on decode the running codec decides. The condenser underneath (the bit layout, the salt derivation, the variable-length fold) is shared between them, so v6 is a small, understandable delta on the code v1 already proved: the same machine, minus the dice, with the timestamp bytes reordered.
v1 is still in the box for one reason, compatibility. New ids are v6, but an old v1 id still resolves by its bytes, because lookups and the ~base59 text form never crack the fields open. What changes is its canonical rendering: decoded as v6 it prints a v6 string, not the v1 string it was born with. That is a real, deliberate break, scoped to the field-decoding representations and written into the upgrade notes; it buys never carrying two decoders in the hot path. A deployment that cannot take it starts with --legacy-ids, which pins the pure v1 codec at both ends and is byte-for-byte what it always was. Xapiand mints v6 by default.
The portable part
Section titled “The portable part”Minting the id in the first place is where the operating systems disagree, as they always do. cuuid uses the platform UUID backend rather than rolling its own: uuid/uuid.h (libuuid) on Linux and Darwin, the native uuid.h on FreeBSD, selected at build time. Its two small dependencies are other familiars in this series, endian for byte order and char-classify for hex, and the host-specific seams (tracing, exceptions, local-node salting) are override points so the core carries nothing it does not need.
Where it fits
Section titled “Where it fits”Reach for it when you want time-sortable unique ids and you care about their size on the wire or on disk, which in a storage or search system you should. Eight coordination-free bytes that sort by time to 1.64 ms, decoded in nanoseconds without rolling any dice, is a genuinely good place to be. In a greenfield service I would still reach for UUIDv7 first, the boring standard answer with a library in every language, or a Snowflake if a 64-bit id and a worker registry suit you. Skip cuuid if random v4 ids are what you want, since there is nothing structural to condense in true randomness, or if a plain UUID library already does what you need and the bytes are not worth counting. The full write-up, the wider field (ULID, KSUID, ObjectId, and the rest), and the numbers to reproduce live in the repo’s comparison write-up.
The next familiar is the maker of the other face a cuuid wears: the ~ and the string of base59 it turns into when a person has to read it. A base-N encoder that treats a blob as one big number and spells it out in an alphabet built for human eyes.