README.md

Minimal Python UUID 7 Implementation

This implementation uses scaled-down nanoseconds for the rand_a part. See RFC 9562 draft for more conext.

How to Run

> uv run uuid7.py
┌──────────────────────────────────────┬──────────────────────────────────────┐
│                  id                  │                 data                 │
│                 uuid                 │               varchar                │
├──────────────────────────────────────┼──────────────────────────────────────┤
│ 019c8beb-820e-74c5-8d48-b3e628f9dd36 │ 019c8beb-820b-7d13-b9eb-1af579288dff │
│ 019c8beb-820f-7c16-b5a9-92cec7223adf │ 019c8beb-820b-7d5b-989d-d6d423f288da │
│ 019c8beb-8210-7b7c-a898-13200a6cce2b │ 019c8beb-820b-7d7a-8769-e63977782fd2 │
│ 019c8beb-8211-750f-9b38-8ed62c35ba94 │ 019c8beb-820b-7d8b-b352-5a8eb5f6a906 │
│ 019c8beb-8212-7776-8177-58811499976e │ 019c8beb-820b-7d98-a646-74883b02754a │
│ 019c8beb-8212-78bd-8418-4852582024e9 │ NULL                                 │
│ 019c8beb-8212-7902-8576-4d1cfc5e0bbb │ NULL                                 │
│ 019c8beb-8212-7916-a3b3-f01e3d12cd12 │ NULL                                 │
│ 019c8beb-8212-7927-8dff-d460390894c5 │ NULL                                 │
│ 019c8beb-8212-7933-bcaa-9dcd9f263da2 │ NULL                                 │
├──────────────────────────────────────┴──────────────────────────────────────┤
│ 10 rows                                                           2 columns │
└─────────────────────────────────────────────────────────────────────────────┘

uuid7.py

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "duckdb>=1.4.4",
# ]
# ///

import secrets
import time
from uuid import UUID


def uuid7(timestamp: float | None = None) -> UUID:
    """
    UUIDv7 features a time-ordered value field derived from the widely
    implemented and well-known Unix Epoch timestamp source, the number of
    milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded.
    Generally, UUIDv7 has improved entropy characteristics over UUIDv1 or UUIDv6.

    Implementations SHOULD utilize UUIDv7 instead of UUIDv1 and UUIDv6 if possible.

    ```
    ┌───────────────────────────────────────────────────────────────┐
    │                           unix_ts_ms                          │
    ├───────────────────────────────┬───────┬───────────────────────┤
    │          unix_ts_ms           │  ver  │       rand_a          │
    ├───┬───────────────────────────┴───────┴───────────────────────┤
    │var│                        rand_b                             │
    ├───┴───────────────────────────────────────────────────────────┤
    │                            rand_b                             │
    └───────────────────────────────────────────────────────────────┘
    ```
    """

    nanoseconds = time.time_ns() if timestamp is None else int(timestamp * 1e9)
    milliseconds, ns_part = divmod(nanoseconds, 10**6)
    ns_part_12_bit = int(ns_part / 10**6 * 2**12)  # scale nanoseconds [0..999_999] down to 12 bit [0..4095]

    unix_ts_ms = milliseconds & 0xFFFFFFFFFFFF  # 48 bits
    version = 7  # 4 bits
    rand_a = ns_part_12_bit & 0x0FFF  # 12 bits
    variant = 0b10  # 2 bits
    rand_b = secrets.randbits(62)

    uuid_int = unix_ts_ms << 80 | version << 76 | rand_a << 64 | variant << 62 | rand_b << 0

    return UUID(int=uuid_int)


def main() -> None:
    import duckdb

    duckdb.sql("create or replace table foo (id uuid primary key default (uuidv7()), data varchar);")
    duckdb.executemany("insert into foo (data) values (?)", [[uuid7()] for _ in range(5)])
    duckdb.executemany("insert into foo (id) values (?)", [[uuid7()] for _ in range(5)])

    print(duckdb.sql("select * from foo order by data, id"))


if __name__ == "__main__":
    main()