Get the timestamp out of a UUID

Which versions carry a clock#

RFC 9562 § 6.1 · Timestamp ConsiderationsWhat the standard says a timestamp in an identifier may and may not be relied on for

Why a v4 has no date#

A v4 is 122 random bits, plus the six the version and variant take. There is no clock in it, so a tool that offers to decode a date from one is decoding noise. If you need the creation time and only have v4 identifiers, the time has to come from a column next to it, or the identifiers have to become v7.

What the decoded time actually tells you#

It tells you what the clock on the generating machine said. That machine may have been wrong, may have been a container starting with a skewed clock, and in the case of v7 may have deliberately spent the sub-millisecond bits on a counter instead of on precision. Treat the value as strong evidence and weak proof: good for debugging and for ordering, unsuitable as an audit timestamp.

RFC 9562 § 6.2 · Monotonicity and CountersMonotonic counters, and why two v7s from the same millisecond still order correctly

Doing it in code#

// v7: the first 48 bits are Unix milliseconds
const ms = Number(BigInt("0x" + id.replace(/-/g, "").slice(0, 12)));
const when = new Date(ms);

// v1 and v6: 100-nanosecond ticks since 1582-10-15
const GREGORIAN = 12219292800000n;   // milliseconds between the two epochs
const unixMs = ticks / 10000n - GREGORIAN;

The constant is the whole trick for v1: 12219292800 seconds separate 1582-10-15 from 1970-01-01, and the ticks are tenths of a microsecond rather than milliseconds.

ULID and v7 share a clock#

A ULID is the same 48-bit millisecond field followed by 80 random bits, printed in Crockford base32. That is why converting a v7 to a ULID keeps the timestamp intact: only the random tail and the alphabet change. The converter shows both, so a log full of ULIDs and a database full of v7 identifiers can be lined up on the same axis.