# UUID functions

> 8 UUID functions in NYXDB: names, aliases, signatures and behaviour.

{/* AUTO-GENERATED from the function catalog. DO NOT EDIT — overwritten on every build. */}

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.

| Function | Summary |
| --- | --- |
| [`uuid_from_uint128`](#uuid_from_uint128) | Reinterprets an unsigned 128-bit integer as a UUID without changing its bits. |
| [`uuid_generate`](#uuid_generate) | Creates a fresh random UUID for a one-shot query. |
| [`uuid_generate_v7`](#uuid_generate_v7) | Creates a time-ordered version-seven identifier from wall-clock milliseconds and randomness. |
| [`uuid_num_to_string`](#uuid_num_to_string) | Formats a sixteen-byte UUID representation as hyphenated identifier text. |
| [`uuid_string_to_num`](#uuid_string_to_num) | Parses canonical UUID text into sixteen bytes with a chosen byte-order convention. |
| [`uuid_to_num`](#uuid_to_num) | Serializes a typed UUID into fixed-length bytes under the requested variant. |
| [`uuid_to_uint128`](#uuid_to_uint128) | Reads the canonical UUID bytes as one big-endian unsigned integer. |
| [`uuid_v7_to_datetime`](#uuid_v7_to_datetime) | Extracts a UUIDv7 identifier’s embedded millisecond timestamp. |

## uuid_from_uint128

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

```text
uuid_from_uint128(value:uint128) -> uuid
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `uuid` |
| Aliases | `uint128_to_uuid` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## uuid_generate

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

```text
uuid_generate() -> uuid
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/nullary` |
| Returns | `uuid` |
| Aliases | `gen_random_uuid`, `generate_uuid`, `generateUUIDv4`, `uuid`, `uuid_generate_v4` |
| Streaming | One-shot only. |
| Determinism | Volatile — may differ on every call. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## uuid_generate_v7

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

```text
uuid_generate_v7() -> uuid
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/nullary` |
| Returns | `uuid` |
| Aliases | `generate_uuid_v7`, `generateUUIDv7` |
| Streaming | One-shot only. |
| Determinism | Volatile — may differ on every call. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## uuid_num_to_string

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

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..2-ary` |
| Returns | `string` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

```sql
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.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..2-ary` |
| Returns | `fixed_string(16)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

```sql
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.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..2-ary` |
| Returns | `fixed_string(16)` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

```sql
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.

```text
uuid_to_uint128(value:uuid) -> uint128
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `uint128` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## uuid_v7_to_datetime

Extracts a UUIDv7 identifier’s embedded millisecond timestamp.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/1..2-ary+timezone` |
| Returns | `datetime64(3,tz)` |
| Aliases | `uuidv7_to_datetime` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

---

Source: https://nyxdb.io/docs/functions/uuid/