Skip to main content

Module uuid

Module uuid 

Source
Expand description

Converting between a UUID’s textual bits and DuckDB’s vector storage.

A UUID column is physically a HUGEINT, but the 128 bits in the vector are not the 128 bits you see in the text form. DuckDB flips the top bit so that comparing the signed integers orders UUIDs the same way comparing their strings does (BaseUUID::FromUHugeint in src/common/types/uuid.cpp subtracts 2^63 from the upper half; that is a top-bit flip).

The consequence is easy to hit and silent when you do:

SELECT '11111111-2222-3333-4444-555555555555'::UUID
  vector storage : 0x91111111222233334444555555555555   <- read_i128
  textual bits   : 0x11111111222233334444555555555555   <- Value::as_uuid, uuid crates

VectorReader::read_uuid and VectorWriter::write_uuid apply the flip for you and speak in textual bits (u128), which is what every Rust Uuid type holds. These functions are for the raw path — when you have reached for read_i128 / write_i128 on a UUID column yourself.

Functions§

uuid_from_storage
Converts DuckDB’s vector storage for a UUID into the UUID’s textual 128 bits.
uuid_to_storage
Converts a UUID’s textual 128 bits into DuckDB’s vector storage.