UUIDv7 functions

UUIDv7 is a time-ordered UUID that includes a Unix timestamp (with millisecond precision) in its first 48 bits. Like other UUIDs, it uses 6 bits for version and variant info, and the remaining 74 bits are random.

Expand image

UUIDv7 is ideal anywhere you create lots of records over time, not only observability. Advantages are:

• No extra column required to partition by time with sortability: you can sort UUIDv7 instances by their value. This is useful for ordering records by creation time without the need for a separate timestamp column.
• Indexing performance: UUIDv7s increase with time, so new rows append near the end of a B-tree instead of This results in fewer page splits, less fragmentation, faster inserts, and efficient time-range scans.
• Easy keyset pagination: WHERE id > :cursor and natural sharding.
• UUID: safe across services, replicas, and unique across distributed systems.

UUIDv7 also increases query speed by reducing the number of chunks scanned during queries. For example, in a database with 25 million rows, the following query runs in 25 seconds:

WITH ref AS (SELECT now() AS t0)
SELECT count(*) AS cnt_ts_filter
FROM events e, ref
WHERE uuid_timestamp(e.event_id) >= ref.t0 - INTERVAL '2 days';

Copy

Using UUIDv7 excludes chunks at startup and reduces the query time to 550ms:

WITH ref AS (SELECT now() AS t0)
SELECT count(*) AS cnt_boundary_filter
FROM events e, ref
WHERE e.event_id >= to_uuidv7_boundary(ref.t0 - INTERVAL '2 days')

Copy

You use UUIDvs for events, orders, messages, uploads, runs, jobs, spans, and more.

• High-rate event logs for observability and metrics:

  UUIDv7 gives you globally unique IDs (for traceability) and time windows (“last hour”), without the need for a separate created_at column. UUIDv7 create less churn because inserts land at the end of the index, and you can filter by time using UUIDv7 objects.

  • Last hour:

    SELECT count(*) FROM logs WHERE id >= to_uuidv7_boundary(now() - interval '1 hour');

    Copy
  • Keyset pagination

    SELECT * FROM logs WHERE id > to_uuidv7($last_seen'::timestamptz, true) ORDER BY id LIMIT 1000;

    Copy

• Workflow / durable execution runs:

  Each run needs a stable ID for joins and retries, and you often ask “what started since X?”. UUIDs help by serving both as the primary key and a time cursor across services. For example:

  SELECT run_id, status
  FROM runs
  WHERE run_id >= to_uuidv7_boundary(now() - interval '5 minutes')

  Copy

• Orders / activity feeds / messages (SaaS apps):

  Human-readable timestamps are not mandatory in a table. However, you still need time-ordered pages and day/week ranges. UUIDv7 enables clean date windows and cursor pagination with just the ID. For example:

  SELECT * FROM orders
  WHERE id >= to_uuidv7('2025-08-01'::timestamptz, true)
  AND id <  to_uuidv7('2025-08-02'::timestamptz, true)
  ORDER BY id;

  Copy

• generate_uuidv7(): generate a version 7 UUID based on current time
• to_uuidv7(): create a version 7 UUID from a PostgreSQL timestamp
• to_uuidv7_boundary(): create a version 7 "boundary" UUID from a PostgreSQL timestamp
• uuid_timestamp(): extract a PostgreSQL timestamp from a version 7 UUID
• uuid_timestamp_micros(): extract a PostgreSQL timestamp with microsecond precision from a version 7 UUID
• uuid_version(): extract the version of a UUID