Skip to content
Qirava lowercase logo

The q* stdlib docs

quuid: UUID generation

quuid generates UUIDs from scratch with zero third-party dependencies. It offers two versions: uuid.v4 (fully random) and uuid.v7 (time-ordered, with a millisecond timestamp prefix that makes new IDs sort after older ones — ideal for database keys). Entropy comes from /dev/urandom, and both are formatted as the canonical 8-4-4-4-12 lowercase-hex string.

What it gives you#

FunctionArgumentsReturnsBehavior
uuid.v4noneStrRandom UUID, version 4.
uuid.v7noneStrTime-ordered UUID, version 7.

Both return a 36-character string in canonical form: five hyphen-separated hex groups of lengths 8, 4, 4, 4, and 12. The version nibble appears at the start of the third group (4 for v4, 7 for v7), and the variant bits make the first character of the fourth group one of 8, 9, a, or b.

v4 vs v7#

uuid.v4
All 16 bytes random, then the version nibble is set to 4 and the variant bits to 10. Best when you want no information leakage and no ordering.
uuid.v7
The first 48 bits are the big-endian Unix-millisecond timestamp, the rest is random, with version 7 and variant 10. The timestamp prefix makes IDs lexicographically time-ordered, which keeps B-tree index inserts near the tail — ideal for database keys.

Entropy source#

Each generation draws 16 bytes from /dev/urandom. If /dev/urandom is unavailable, quuid falls back to a splitmix64 mixer seeded by the highest-resolution clock available, so the build stays zero-dependency and works on every platform. (qcrypto's random_bytes uses the identical strategy.)

Resource budget#

Each call uses a fixed 16-byte entropy buffer plus a 36-character output string and a small read from /dev/urandom — fixed, modest work. Both uuid.* functions declare a 512-byte memory budget and zero storage.

Example#

uuid.v4 returns a random version-4 UUID; the value differs on every call. The shape below is illustrative of the format (8-4-4-4-12, version nibble 4, variant 8/9/a/b).

Request

uuid.v4()

# wire form: no arguments
{ }

Response

{ "result": { "Str": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } }

Output

f47ac10b-58cc-4372-a567-0e02b2c3d479  (random; version 4, variant a)

Request

uuid.v7()

Response

{ "result": { "Str": "018f6e2a-1c3d-7abc-89ef-0123456789ab" } }

Output

a version-7 UUID whose leading 48 bits encode the current Unix-ms time, so successive IDs sort in creation order