UUID functions

8 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

uuid_from_uint128

Reinterprets an unsigned 128-bit integer as a UUID without changing its bits.

uuid_from_uint128(value:uint128) -> uuid

Converts the big-endian integer representation into the canonical sixteen UUID bytes. Every uint128 pattern is preserved, including the all-zero identifier, and NULL returns NULL. Inputs outside the required descriptor raise TYPE_MISMATCH; the operation does not manufacture a version or variant.

Example

uuid_from_uint128(cast(0 AS UINT128))
-- → 00000000-0000-0000-0000-000000000000

uuid_generate

Creates a fresh random UUID for a one-shot query.

uuid_generate() -> uuid

Produces a new version-four UUID without input arguments or SQL NULL propagation. Random generation is volatile, so continuous replay plans reject the call with INVALID_ARGUMENT under the current admission contract. The result has the native uuid type rather than text; randomness availability failures remain explicit engine errors.

Example

length(cast(uuid_generate() AS STRING))
-- → 36

uuid_generate_v7

Creates a time-ordered version-seven identifier from wall-clock milliseconds and randomness.

uuid_generate_v7() -> uuid

Combines the current millisecond timestamp with UUIDv7 version, variant and random bits to produce a native uuid value. It has no nullable input and does not promise a repeatable value on replay. The operation is one-shot only; continuous-plan admission raises INVALID_ARGUMENT and runtime generation failures are not replaced by NULL.

Example

length(cast(uuid_generate_v7() AS STRING))
-- → 36

uuid_num_to_string

Formats a sixteen-byte UUID representation as hyphenated identifier text.

uuid_num_to_string(value:fixed_string(16)) -> string
uuid_num_to_string(value:fixed_string(16),variant:uint8) -> string

Uses the selected byte-order convention to reconstruct canonical UUID display text. The default variant is RFC order, and Microsoft order is selected by variant two; other variants raise INVALID_ARGUMENT. NULL arguments yield NULL, while a value outside fixed_string(16) raises TYPE_MISMATCH.

Example

uuid_num_to_string(
  cast(X '00000000000000000000000000000001' AS fixed_string(16))
)
-- → '00000000-0000-0000-0000-000000000001'

uuid_string_to_num

Parses canonical UUID text into sixteen bytes with a chosen byte-order convention.

uuid_string_to_num(text:string) -> fixed_string(16)
uuid_string_to_num(text:string,variant:uint8) -> fixed_string(16)

Requires canonical hyphenated UUID text and accepts variant one for RFC order or variant two for Microsoft order. Variant one is the default; a different variant raises INVALID_ARGUMENT and malformed UUID text raises INVALID_ENCODING. NULL propagates and the returned fixed_string(16) is raw storage rather than display text.

Example

hex_encode(uuid_string_to_num('00000000-0000-0000-0000-000000000001'))
-- → '00000000000000000000000000000001'

uuid_to_num

Serializes a typed UUID into fixed-length bytes under the requested variant.

uuid_to_num(value:uuid) -> fixed_string(16)
uuid_to_num(value:uuid,variant:uint8) -> fixed_string(16)

Exports sixteen bytes from a native UUID using RFC byte order by default or Microsoft order for variant two. The UUID value is not regenerated or interpreted as a textual number. NULL produces NULL; incompatible variants raise INVALID_ARGUMENT and non-UUID inputs raise TYPE_MISMATCH.

Example

hex_encode(uuid_to_num(cast('00000000-0000-0000-0000-000000000001' AS UUID)))
-- → '00000000000000000000000000000001'

uuid_to_uint128

Reads the canonical UUID bytes as one big-endian unsigned integer.

uuid_to_uint128(value:uuid) -> uint128

Returns an exact uint128 interpretation of all sixteen UUID bytes. This operation is reversible through the matching integer-to-UUID conversion and does not discard version bits. NULL produces NULL and non-UUID input raises TYPE_MISMATCH unless explicitly cast first.

Example

uuid_to_uint128(cast('00000000-0000-0000-0000-000000000001' AS UUID))
-- → 1

uuid_v7_to_datetime

Extracts a UUIDv7 identifier’s embedded millisecond timestamp.

uuid_v7_to_datetime(value:uuid) -> datetime64(3,tz)
uuid_v7_to_datetime(value:uuid,timezone:string) -> datetime64(3,tz)

Reads the version-seven time field into datetime64 with precision three, using UTC unless a timezone is supplied. A non-v7 UUID or invalid timezone raises INVALID_ARGUMENT rather than inventing a timestamp. NULL arguments propagate; changing the display timezone does not alter the encoded instant.

Example

uuid_v7_to_datetime(cast('00000000-0000-7000-8000-000000000000' AS UUID))
-- → 1970-01-01 00:00:00.000 UTC