How UUID v7 Works

The timestamp portion

UUID v7 begins with a Unix timestamp in milliseconds. Because that timestamp is placed at the beginning of the value, ordinary string sorting usually follows generation time when the UUIDs use the same canonical format.

The timestamp is not metadata stored beside the UUID; it is part of the identifier itself. If you expose the UUID to users or logs, you are also exposing that time signal.

The random portion

After the timestamp and required version/variant bits, UUID v7 uses random data. Good implementations use cryptographic browser or operating system randomness for those bytes.

Randomness is still important. The timestamp alone is not enough because many IDs may be generated in the same millisecond across one or many machines.

Sorting behavior

UUID v7 is designed so newer values normally compare after older values. That makes it more convenient for logs, event tables, and sorted database indexes than a purely random UUID.

Sorting still depends on preserving the normal UUID byte/string layout. If you remove hyphens, uppercase the value, or store it in a UUID-aware database column, ordering should remain consistent. If a system transforms bytes into a custom layout, verify the behavior before relying on it.

What UUID v7 does not guarantee

• It does not prove that an event actually happened at the embedded time.
• It does not replace authorization, signatures, or audit controls.
• It does not hide creation time from people who can read the identifier.
• It does not guarantee perfect monotonic order when clocks move or multiple systems generate IDs concurrently.

Bit-level example

018cc251-f400-7abc-8def-1234567890ab
^^^^^^^^^^^^  48-bit Unix millisecond timestamp
             7 = version 7
                  8..b = RFC variant

Implementation review

• Write the timestamp as six big-endian bytes.
• Seed the remaining bits with cryptographic randomness.
• Set version and variant bits after filling random bytes.
• Decide whether same-millisecond monotonic ordering is required.
• Never use Math.random for the random portion.

Walking through one value

The first 48 bits carry Unix time in milliseconds using network byte order. The version nibble is set to 7, the RFC variant occupies the high bits of the appropriate byte, and the remaining bits supply randomness or a documented monotonic strategy. Parsing the first twelve hexadecimal digits gives the time signal; it does not require access to a database or a second metadata field.

Implementations should fill random bytes with a cryptographic source before overwriting the version and variant bits. Browser code can use crypto.getRandomValues. A generator that fills the random region with Math.random weakens collision behavior and makes the implementation unsuitable even though the final string still resembles a valid UUID.

Ordering under difficult clocks

Two values created in different milliseconds naturally compare by their timestamp prefix. Multiple values created inside one millisecond need enough random entropy, and applications that require strict local ordering may increment a monotonic random field. That additional behavior must handle overflow rather than silently reusing a value.

Clock rollback is a separate problem. A host whose clock moves backward can produce a valid v7 value that sorts before a recently generated value. Distributed hosts can also disagree about time. Treat ordering as a convenient property for indexes and rough chronology, not an authoritative sequence number or a replacement for a transactional event position.

Implementation tests worth keeping

• Decode known timestamps at the Unix epoch and at a recent UTC instant.
• Assert the version nibble and RFC variant bits after random bytes are filled.
• Generate a large same-millisecond sample with a controlled clock and check uniqueness.
• Exercise monotonic overflow and clock rollback behavior if the library promises monotonic output.
• Compare byte, canonical-string, compact-string, and database ordering.
• Document that the decoded time is untrusted generator input rather than audit evidence.

References

• RFC 9562, UUID Version 7
• RFC 9562, Monotonicity and Counters

FAQ

Related guides