# UUID functions

UUID functions generate identifiers and inspect their version or embedded timestamp. Generation returns a native UUID, which can be stored in a UUID column or used as a key.

Version 4 identifiers use random bits. Version 7 identifiers include a timestamp; extraction returns NULL for UUID versions or variants that do not carry a supported timestamp. The generated identifier itself is nondeterministic.

## Example: Checking generated UUID versions

```sql
SELECT uuid_extract_version(gen_random_uuid()), uuid_extract_version(uuidv7())
FORMAT csv;
```

```text
4,7
```

## gen_random_uuid

Generate an RFC 9562 random UUID version 4 from operating-system entropy.

### Syntax

```text
gen_random_uuid()
```

### Arguments

No arguments. Nondeterministic; independent of setseed.

### Returned value

Native UUID version 4; an unavailable entropy source raises IO_ERROR.

### Example

```sql
SELECT uuid_extract_version(gen_random_uuid()) FORMAT csv;
```

```text
4
```

## uuid_extract_timestamp

Extract the UTC timestamp carried by an RFC 9562 UUID version 1 or 7.

### Syntax

```text
uuid_extract_timestamp(uuid)
```

### Arguments

Native UUID or accepted UUID text. Version 1 drops submicrosecond digits; version 7 exposes its millisecond timestamp. Other versions/variants and SQL NULL return NULL.

### Returned value

Native UTC DateTime64(6), or NULL when no supported timestamp is present.

### Example

```sql
SELECT date_part('year',uuid_extract_timestamp('019535d9-3df7-79fb-b466-fa907fa17f9e')) FORMAT csv;
```

```text
2025.0
```

## uuid_extract_version

Extract the version nibble from an RFC 9562 variant UUID.

### Syntax

```text
uuid_extract_version(uuid)
```

### Arguments

Native UUID or accepted UUID text; SQL NULL propagates. Other UUID variants return NULL.

### Returned value

INTEGER version from zero through fifteen, or NULL for a non-RFC variant.

### Example

```sql
SELECT uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d') FORMAT csv;
```

```text
4
```

## uuidv7

Generate an RFC 9562 time-ordered UUID version 7 with an ascending submillisecond fraction.

### Syntax

```text
uuidv7([shift])
```

### Arguments

Optional native/text interval or make_interval span shifts UTC time with calendar semantics. SQL NULL propagates. Timestamp must fit unsigned 48-bit Unix milliseconds; random bits use OS entropy.

### Returned value

Native UUID version 7. Unshifted calls ascend within one connection; shifted calls follow the supplied interval.

### Example

```sql
SELECT uuid_extract_version(uuidv7()) FORMAT csv;
```

```text
7
```