Cloud

uuid

The uuid data type represents a 128-bit universally unique identifier (UUID). Redpanda SQL exposes it to PostgreSQL clients as the uuid type.

Redpanda SQL surfaces a uuid column when it reads a UUID column from a Redpanda topic, whether from the topic’s Avro-encoded live records or from its Iceberg-committed history. See Query Iceberg-enabled topics.

An Avro field with the uuid logical type maps to uuid, regardless of whether the field is backed by string or fixed. Protobuf and JSON have no UUID type. For how record schema types translate into the Iceberg table, see Schema types translation.

Text representation

Redpanda SQL renders a UUID as the 36-character canonical form: 32 hexadecimal digits in five hyphen-separated groups (8-4-4-4-12).

a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11

Casting

The uuid type doesn’t cast implicitly to or from other types, and text and string functions don’t operate on uuid values directly. Cast a UUID explicitly:

Cast Result

id::text

The 36-character canonical form, for example a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11.

id::bytea

The raw 16-byte binary encoding of the UUID.

'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'::uuid

A uuid value parsed from text. Use this to compare against or filter on a UUID.

When casting text to uuid, Redpanda SQL accepts not only the 36-character canonical form, but also any variant accepted by PostgreSQL: hex digits can be upper- or lower-case, hyphens can be omitted or placed between any four-digit groups, and the value can be wrapped in braces. An invalid input fails with invalid input syntax for type uuid. When casting uuid to text or returning it from a SELECT, the output is always the canonical form.

You can also cast a 16-byte bytea value to uuid.

For example, to read a UUID column as text:

SELECT id::text FROM default_redpanda_catalog=>events;

To filter on a UUID value, cast the text literal to uuid:

SELECT * FROM default_redpanda_catalog=>events
WHERE id = 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'::uuid;

You can also write the literal with the uuid keyword:

WHERE id = uuid 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'

Generate a UUID

Generate a random version 4 UUID with gen_random_uuid() or its equivalent, uuidv4():

SELECT gen_random_uuid();