Последнее обновление 16 окт. 2026 г.

Тип данных UUID

Описание

UUID хранит 128-битный универсальный уникальный идентификатор в 16 байтах. Используйте его для идентификаторов, которым нужны компактное хранение, фильтрация по равенству, соединения или сортировка. Текстовый вывод всегда использует каноническую форму в нижнем регистре: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Синтаксис и формат ввода

UUID

Свойство	Поведение
Хранение	Значение фиксированного размера 16 байт; каноническая текстовая форма содержит 36 символов
Канонический ввод	32 шестнадцатеричные цифры с дефисами по схеме `8-4-4-4-12`
Компактный ввод	32 шестнадцатеричные цифры без дефисов
Регистр букв	Принимаются шестнадцатеричные цифры в верхнем и нижнем регистре; вывод всегда в нижнем регистре
Диапазон значений	От `00000000-0000-0000-0000-000000000000` до `ffffffff-ffff-ffff-ffff-ffffffffffff`
Проверка	Проверяется текстовый формат без требования определённой версии или варианта UUID
NULL	Поддерживается для столбцов, допускающих NULL; UUID, состоящий из нулей, является допустимым значением, отличным от `NULL`
Порядок сортировки	Сравнение как беззнаковых 128-битных значений в каноническом порядке байтов, эквивалентное лексикографическому сравнению нормализованной канонической текстовой формы

Основы использования

CREATE DATABASE IF NOT EXISTS uuid_demo;
USE uuid_demo;

CREATE TABLE uuid_events (
    id INT NOT NULL,
    event_id UUID NULL,
    generated_id UUID NOT NULL DEFAULT UUID_V7()
)
DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 1
PROPERTIES ('replication_num' = '1');

INSERT INTO uuid_events (id, event_id) VALUES
    (1, '550E8400E29B41D4A716446655440000'),
    (2, '00000000-0000-0000-0000-000000000000'),
    (3, NULL);

SELECT id, event_id, UUID_VERSION(generated_id) AS generated_version
FROM uuid_events ORDER BY id;

+----+--------------------------------------+-------------------+
| id | event_id                             | generated_version |
+----+--------------------------------------+-------------------+
| 1  | 550e8400-e29b-41d4-a716-446655440000 | 7                 |
| 2  | 00000000-0000-0000-0000-000000000000 | 7                 |
| 3  | NULL                                 | 7                 |
+----+--------------------------------------+-------------------+

Для каждого пропущенного generated_id генерируется значение. Его точное текстовое представление меняется при каждом выполнении.

SELECT id FROM uuid_events
WHERE event_id = CAST('550e8400-e29b-41d4-a716-446655440000' AS UUID);

+----+
| id |
+----+
| 1  |
+----+

Функции и преобразование

Функция	Результат и назначение
UUID_V4	Случайный UUID v4 нативного типа; псевдонимы `GENERATE_UUID_V4()` и `GENERATEUUIDV4()`
UUID_V7	UUID v7 нативного типа, содержащий метку времени с точностью до миллисекунд; псевдонимы `GENERATE_UUID_V7()` и `GENERATEUUIDV7()`
UUID_VERSION	Поле версии типа `TINYINT` (0–15), без проверки варианта
TO_UUID_OR_NULL	Разбирает текст; для некорректного текста и `NULL` возвращает `NULL`
TO_UUID_OR_ZERO	Разбирает текст; для некорректного текста возвращает UUID, состоящий из нулей, а `NULL` остаётся `NULL`
TO_UUID_OR_DEFAULT	Разбирает текст; для некорректного текста или `NULL` использует заданное резервное значение UUID, по умолчанию UUID, состоящий из нулей
UUID_V7_TO_DATETIME	Извлекает метку времени как `DATETIME(3)` в выбранном часовом поясе
DATETIME_TO_UUID_V7	Генерирует UUID v7 из даты и времени, интерпретируемых в часовом поясе сеанса
UUID	Существующая функция, возвращающая `VARCHAR`, а не нативный тип UUID

Используйте CAST(text AS UUID) для разбора текста и CAST(uuid AS STRING) для вывода в канонической форме. При enable_strict_cast = true некорректный текст вызывает ошибку; если эта настройка отключена, для некорректного текста возвращается NULL. TRY_CAST(text AS UUID) возвращает NULL для некорректного текста в любом режиме. Прямое приведение между UUID и целочисленными типами, типами с плавающей точкой, типами даты/времени или IP невозможно. Сведения о неявном преобразовании, VARIANT и правилах миграции см. в разделе Преобразование UUID.

Существующая функция IS_UUID() принимает некоторые текстовые формы, например канонические UUID в фигурных скобках, которые нативный парсер отклоняет. Используйте TO_UUID_OR_NULL() или TRY_CAST для проверки текста, предназначенного для столбца UUID.

Проектирование таблиц и ограничения

Столбцы UUID могут быть ключевыми столбцами в таблицах Duplicate, Unique и Aggregate, а также столбцами хеш-распределения.
Столбцы UUID нельзя использовать для секционирования RANGE или LIST, в том числе при секционировании по нескольким столбцам или с помощью AUTO PARTITION BY LIST. Динамическое секционирование по столбцам UUID также не поддерживается.
Значения UUID поддерживают сравнение, IN, сортировку, группировку, соединения, MIN, MAX и COUNT(DISTINCT ...). UUID не является числовым типом: арифметические операции и числовые агрегатные функции, такие как SUM и AVG, не поддерживаются.
Столбцы значений типа UUID в таблицах Aggregate поддерживают MIN, MAX, REPLACE и REPLACE_IF_NOT_NULL.
UUID может быть элементом ARRAY, ключом или значением MAP либо полем STRUCT. Существующие ограничения внешнего сложного типа по-прежнему действуют.
UUID поддерживает префиксные индексы, ZoneMap, BloomFilter и инвертированные индексы. Для инвертированного индекса используйте поиск по равенству или диапазону без текстового парсера. UUID не поддерживает NGRAM_BF и векторные индексы.
UUID нельзя использовать для столбца AUTO_INCREMENT или столбца Sequence.
При создании таблицы столбцы UUID поддерживают литеральные значения по умолчанию и динамические значения по умолчанию UUID_V4() / UUID_V7(), включая их псевдонимы. Динамические значения UUID по умолчанию допустимы только для столбцов UUID.
ALTER TABLE ADD COLUMN принимает литеральное значение UUID по умолчанию, но отклоняет генераторы UUID в качестве значений по умолчанию, поскольку существующие строки нельзя заполнить независимыми сгенерированными значениями, сохраняемыми в данных. Изменение схемы не поддерживает прямое преобразование столбца другого типа в UUID или столбца UUID в другой тип. Вместо этого создайте новый столбец или таблицу и выполняйте преобразование при вставке.

Загрузка, экспорт и клиенты

При вводе CSV передавайте текст UUID в поле; при вводе JSON передавайте его как строку JSON или null. Принимаются как каноническая, так и компактная текстовые формы. Чтобы явно выбрать резервное значение, загрузите исходные данные как текст и используйте одну из функций TO_UUID_OR_* в сопоставлении столбцов.

Структурированные интерфейсы передают 16-байтное значение вместо его текстовой формы: Arrow IPC и Arrow Flight SQL используют стандартное расширение arrow.uuid поверх fixed_size_binary(16), а при экспорте в Parquet и ORC двоичное значение записывается вместе с метаданными типа. Столбцы STRING это не затрагивает: строка, содержащая текст UUID, по-прежнему передаётся и экспортируется как текст.

Интерфейс или формат	Представление UUID
Протокол MySQL	Канонический текст; клиент может сообщать о строковом типе, даже если столбец Doris имеет тип UUID
Arrow Flight SQL	Нативный UUID в виде стандартного расширения `arrow.uuid` поверх 16-байтного значения `fixed_size_binary(16)` с порядком байтов big-endian, включая элементы UUID, вложенные в ARRAY, MAP или STRUCT. При использовании драйвера Arrow Flight SQL JDBC тип столбца определяется как `Types.OTHER`, `getObject()` возвращает `java.util.UUID`, `getString()` возвращает канонический текст, а `getBytes()` возвращает 16 байт
Вывод в CSV, JSON и Hive Text	Канонический текст; JSON представляет значения UUID как строки
`OUTFILE` / `EXPORT` в Parquet	`FIXED_LEN_BYTE_ARRAY(16)` с логической аннотацией UUID формата Parquet, в каноническом порядке байтов big-endian, включая вложенные элементы UUID. Версия dev также восстанавливает нативный UUID при определении схемы TVF
`OUTFILE` / `EXPORT` в ORC	`BINARY` с атрибутом Doris `doris.logical_type=uuid`, включая вложенные элементы UUID. В ORC нет стандартного типа UUID, поэтому другие инструменты видят обычные двоичные данные
Чтение нативных UUID из Parquet	Поддерживает `FIXED_LEN_BYTE_ARRAY(16)` с аннотацией UUID в каноническом порядке байтов big-endian, включая вложенные элементы. Версия dev определяет нативный тип `UUID` независимо от `enable_mapping_varbinary`; TVF в версии 4.1.5 используют STRING / VARBINARY в зависимости от этой настройки
Чтение ORC	Столбец `BINARY` с атрибутом `doris.logical_type=uuid` считывается обратно как нативный UUID, в том числе для вложенных элементов и в обоих модулях чтения ORC; TVF указывает `uuid`, `array<uuid>` и `struct<k:uuid>` для таких столбцов. В версии dev немаркированный `BINARY` сопоставляется с `VARBINARY`, а `STRING` остаётся `STRING`
Iceberg	Версия dev сопоставляет UUID в Iceberg непосредственно с нативным UUID в Doris независимо от `enable.mapping.varbinary`. Doris 4.1.5 сопоставляет его с `VARBINARY(16)`. При записи в Parquet сохраняется логическая аннотация UUID
ClickHouse JDBC Catalog	UUID в ClickHouse сопоставляется с нативным UUID в Doris; ранее документированные выпуски сопоставляют его со STRING
Python UDF	SQL UUID сопоставляется с `uuid.UUID`, а `NULL` сопоставляется с `None` в скалярных, векторизованных (`list` и `pandas.Series`), агрегатных и табличных функциях, включая элементы UUID, вложенные в ARRAY, MAP или STRUCT. Функция, возвращающая UUID, должна возвращать объект `uuid.UUID` или `None`
Java UDF	SQL UUID сопоставляется с `java.util.UUID`, в том числе внутри поддерживаемых сложных типов

Описание​

Синтаксис и формат ввода​

Основы использования​

Функции и преобразование​

Проектирование таблиц и ограничения​

Загрузка, экспорт и клиенты​

Рекомендации по использованию​