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;
Storage comparison
| Representation | Size | Sortable | Human-readable |
|---|---|---|---|
| String (TEXT) | 36 bytes | Yes (lexicographic) | Yes |
| Binary (BYTES) | 16 bytes | Yes (byte order) | No |
| UInt128 | 16 bytes | Yes (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.
Related terms
- UUID Bit Fields — Version and Variant
- UUID String Format — Canonical Hex
- UUID Byte Layout — visual bit map
- UUID v7 in ClickHouse
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.