UUID V7 Generator

What is UUID Version-7 (UUIDv7)

UUID Version 7 (UUIDv7) is a new version of UUID that is time-based and combines the concepts of timestamps and random number generators to provide more orderly and efficient unique identifiers.

Core Features of UUIDv7

UUIDv7 is a new addition to the UUID specification, and its core feature is the combination of timestamps and incrementing counters to produce more orderly and efficient unique identifiers. The design of UUIDv7 takes into account temporal relevance and monotonicity, and its structure is divided into several fields, including:

• A 48-bit Unix timestamp, accurate to the millisecond, ensuring the relationship between the identifier and time.
• A 4-bit version number, set to 0111, indicating that this is UUIDv7.
• A 42-bit counter to ensure IDs generated within the same millisecond are sequentially increasing.
• A 2-bit variable field, set to 10.
• A 32-bit random number to enhance uniqueness.

This design allows for fast sorting and efficient searching, while the counter prevents duplicates and maintains the continuity of the generation order in the event of system clock regression.

Application Scenarios for UUID Version 7

UUIDv7 can be widely applied in various fields, such as unique identification of database records, identification of distributed system nodes, file naming, and tracking of log entries. Due to its time-based characteristics, it is particularly suitable for systems that need to operate or retrieve based on temporal order.

Advantages of UUID Version 7

• Efficient and Ordered: Utilizing timestamps and incrementing counters, UUIDv7 can generate identifiers arranged in chronological order.
• Security: The random number part ensures high uniqueness, making it suitable for applications with high security requirements.
• Cross-platform Support: It can be used in both Node.js environments and run directly in browsers and Deno.
• Flexible Interface: In addition to basic UUIDv7 generation, it also provides UUIDv4 generation and object representation.
• Rich API: Provides the V7Generator class, which supports independent counter management and prevents significant clock rollbacks.

Format of UUID Version 7

The structure of UUIDv7 is as follows:

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       unix_ts_ms (48 bits)                       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  ver (4 bits)  |         rand_a (12 bits)                        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| var (2 bits)   |                rand_b (62 bits)                 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

This structure gives UUIDv7 good temporal clustering within a certain period, meaning that the size of UUIDs generated within a range is always similar, which meets the requirements for primary keys, and the 74 bits of randomness also ensure very good randomness.

In summary, UUIDv7 provides a unique and orderly identifier by combining timestamps and random numbers, making it suitable for scenarios that require chronological order and high-concurrency generation of unique identifiers.