Definition

UInt128 (unsigned 128-bit integer) is the numeric interpretation of a UUID. A UUID is 128 bits of data — when treated as an integer, it occupies the same memory as two 64-bit integers laid end-to-end.

The mapping between UUID string and UInt128 uses big-endian byte order:

UUID string: 018fbe3a-4c5d-7b12-8f3e-1a2b3c4d5e6f
Hex:         018fbe3a4c5d7b128f3e1a2b3c4d5e6f
UInt128:     2156066685038756261... (decimal, very large number)

UUID v7 as UInt128: natural sort order

UUID v7’s 48-bit Unix millisecond timestamp occupies the most significant bits. As a UInt128, newer UUID v7 values are always numerically larger than older ones — integer comparison (>, <, =) gives chronological order without string parsing.

UUID v7 at t=1000ms:  0000000003E8-7xxx-... → UInt128: small
UUID v7 at t=2000ms:  0000000007D0-7xxx-... → UInt128: larger
UUID v7 at t=3000ms:  000000000BB8-7xxx-... → UInt128: largest

Rust: uuid crate and u128

use uuid::Uuid;

let id = Uuid::now_v7();

// Convert to u128
let n: u128 = id.as_u128();

// Extract timestamp from u128 (top 48 bits)
let timestamp_ms = n >> 80;
println!("Created at: {}ms", timestamp_ms);

// Convert back
let id2 = Uuid::from_u128(n);
assert_eq!(id, id2);

// Comparison works as integer comparison
let earlier = Uuid::now_v7();
let later   = Uuid::now_v7();
assert!(earlier.as_u128() < later.as_u128());

See UUID in Rust for the uuid crate overview.

Go: big.Int representation

import (
    "math/big"
    "github.com/google/uuid"
)

id, _ := uuid.NewV7()

// UUID to big.Int (UInt128 equivalent in Go)
b := id[:]
n := new(big.Int).SetBytes(b)

// Timestamp extraction
tsMs := new(big.Int).Rsh(n, 80).Int64()

// Back to UUID
var bytes [16]byte
copy(bytes[:], n.Bytes())
id2 := uuid.UUID(bytes)

ClickHouse: UUID as UInt128 arithmetic

-- ClickHouse stores UUID as 128-bit integer internally
-- reinterpretAsUInt128 gives the numeric value
SELECT
    id,
    reinterpretAsUInt128(id) AS id_uint128,
    -- Extract timestamp: top 48 bits of UUID v7 = ms since Unix epoch
    bitShiftRight(reinterpretAsUInt128(id), 80) AS timestamp_ms,
    fromUnixTimestamp64Milli(
        toInt64(bitShiftRight(reinterpretAsUInt128(id), 80))
    ) AS created_at
FROM events
LIMIT 5;

See UUID v7 in ClickHouse.

Storage comparison

RepresentationSizeSortableHuman-readable
String (TEXT)36 bytesYes (lexicographic)Yes
Binary (BYTES)16 bytesYes (byte order)No
UInt12816 bytesYes (integer)No

UInt128 and Binary offer the same storage size — the difference is in how the host language treats the value (integer arithmetic vs byte array). For UUID v7, all three representations sort chronologically.

Frequently asked questions

What is UInt128 in the context of UUIDs?

UInt128 is a 128-bit unsigned integer — the same width as a UUID. When a UUID is interpreted as a UInt128, the bytes are read in big-endian order: the most significant byte is the first byte of the UUID. UUID v7 as a UInt128 naturally sorts chronologically because the 48-bit Unix timestamp occupies the most significant bits.

How is UInt128 used for UUIDs in Rust?

Rust's u128 type is a 128-bit unsigned integer. The uuid crate provides Uuid::as_u128() and Uuid::from_u128() for converting between the Uuid type and u128. Storing a UUID v7 as u128 allows integer arithmetic on the timestamp prefix and efficient comparison without string parsing.

Does ClickHouse use UInt128 for UUIDs?

ClickHouse has a dedicated UUID column type that stores UUIDs as 128-bit integers internally. generateUUIDv7() returns a UUID type, which ClickHouse represents internally as two UInt64 values (high and low 64-bit halves). UUID v7 values sort correctly as ClickHouse UUID types because the 48-bit timestamp occupies the most significant bits. See UUID v7 in ClickHouse.