Definition

Time precision in UUID context refers to how finely a UUID encodes its creation timestamp — affecting how many UUIDs can be distinguished purely by their time component before random or sequential bits are needed for uniqueness.

Timestamp precision by UUID version

VersionEpochPrecisionBits
UUID v1Oct 15, 1582 (Gregorian)100 nanoseconds60
UUID v6Oct 15, 1582 (Gregorian)100 nanoseconds60
UUID v7Jan 1, 1970 (Unix)1 millisecond48
UUID v8Implementation-definedImplementation-definedUp to 122

UUID v7 — millisecond precision

UUID v7 stores floor(unix_time_ms) in the leading 48 bits. The maximum timestamp it can represent is 2^48 - 1 milliseconds from the Unix epoch — approximately 8,925 years into the future (year 10,895), well beyond any practical concern.

// Extract millisecond timestamp from UUID v7
function extractMs(uuidV7) {
  return parseInt(uuidV7.replace(/-/g, '').slice(0, 12), 16);
}

// Convert to Date
new Date(extractMs('018fbe3a-4c5d-7b12-8abc-0123456789ab'));
// → exact creation time to the nearest millisecond

Two UUID v7 values generated 0.5ms apart will have identical timestamp prefixes — differentiated only by the rand_a and rand_b fields. This is why the monotonic counter (RFC 9562 §6.2 Method 1) matters for within-millisecond ordering: it replaces the random rand_a bits with a counter that increments for each UUID in the same millisecond.

UUID v1 and v6 — 100-nanosecond precision

UUID v1 and v6 use a 60-bit timestamp counting 100-nanosecond intervals since October 15, 1582 (the start of the Gregorian calendar). Theoretical capacity: 163 million unique UUID v1 values per second on a single node before the clock sequence wraps.

In practice, most operating systems provide millisecond or at best microsecond resolution — so the extra precision in v1/v6 is not usable. UUID v6 reorders the same fields for lexicographic sortability but precision is unchanged. See Time-Based UUID.

UUID v8 — custom precision

UUID v8 leaves 122 bits implementation-defined. An application can encode a nanosecond Unix timestamp in the leading bits:

// Custom UUID v8 with nanosecond precision (approximate via hrtime)
function uuidV8Nano() {
  const ns = process.hrtime.bigint(); // actual nanosecond counter
  const nsHex = ns.toString(16).padStart(15, '0');
  // ... pack into UUID v8 format
}

See UUID v8 — Custom Layout for the full implementation.

Why milliseconds are enough

For the primary use case — database primary keys — millisecond precision is sufficient because:

  1. The monotonic counter handles within-millisecond ordering on a single node (up to 4,096 ordered values per millisecond)
  2. Cross-node ordering to sub-millisecond precision requires clock synchronisation tighter than NTP typically provides
  3. Collision probability within a millisecond is negligible — 74 random bits across different milliseconds, counter-based ordering within

See UUID v4 vs v7 and UUID Byte Layout for the full bit-level detail.

External references

Frequently asked questions

How precise is the timestamp in UUID v7?

UUID v7 uses a 48-bit Unix millisecond timestamp — precision to 1 millisecond since the Unix epoch (January 1, 1970 UTC). Two UUID v7 values generated within the same millisecond have the same timestamp prefix; they are distinguished by the 12-bit rand_a field (a counter or random bits) and the 62-bit rand_b field. The monotonic counter option (RFC 9562 §6.2 Method 1) ensures strict ordering within a millisecond on a single node. See UUID Byte Layout.

Can I get sub-millisecond precision from a UUID?

Not from UUID v7 directly — its timestamp field is 48 bits of milliseconds with no sub-millisecond component. For sub-millisecond precision, use UUID v8 (custom layout) to encode a microsecond or nanosecond timestamp in the 122 available bits. Alternatively, combine a UUID v7 with a separate high-resolution timestamp column. See UUID v8 — Custom Layout.