Avro
| Входные данные | Выходные данные | Псевдоним |
|---|---|---|
| ✔ | ✔ |
Описание
Apache Avro — это фреймворк сериализации данных, ориентированный на строки, разработанный в рамках проекта Hadoop от Apache.
Формат Avro в ClickHouse поддерживает чтение и запись файлов данных Avro.
Сопоставление типы данных
Таблица ниже показывает все поддерживаемые типы данных формата Apache Avro и соответствующие типы данных ClickHouse в INSERT и SELECT запросах.
Avro тип данных INSERT | ClickHouse тип данных | Avro тип данных SELECT |
|---|---|---|
boolean, int, long, float, double | Int(8\16\32), UInt(8\16\32) | int |
boolean, int, long, float, double | Int64, UInt64 | long |
boolean, int, long, float, double | Float32 | float |
boolean, int, long, float, double | Float64 | double |
bytes, string, fixed, enum | String | bytes или string * |
bytes, string, fixed | FixedString(N) | fixed(N) |
enum | Enum(8\16) | enum |
array(T) | Array(T) | array(T) |
map(V, K) | Map(V, K) | map(string, K) |
union(null, T), union(T, null) | Nullable(T) | union(null, T) |
union(T1, T2, …) ** | Variant(T1, T2, …) | union(T1, T2, …) ** |
null | Nullable(Nothing) | null |
int (date) *** | Date, Date32 | int (date) *** |
long (timestamp-millis) *** | DateTime64(3) | long (timestamp-millis) *** |
long (timestamp-micros) *** | DateTime64(6) | long (timestamp-micros) *** |
bytes (decimal) *** | DateTime64(N) | bytes (decimal) *** |
int | IPv4 | int |
fixed(16) | IPv6 | fixed(16) |
bytes (decimal) *** | Decimal(P, S) | bytes (decimal) *** |
string (uuid) *** | UUID | string (uuid) *** |
fixed(16) | Int128/UInt128 | fixed(16) |
fixed(32) | Int256/UInt256 | fixed(32) |
record | Tuple | record |
* bytes по умолчанию, контролируется установкой output_format_avro_string_column_pattern
** Тип Variant неявно принимает null как значение поля, поэтому, например, Avro union(T1, T2, null) будет преобразован в Variant(T1, T2). В результате, при создании Avro из ClickHouse, мы всегда должны включать тип null в набор типов Avro union, так как мы не знаем, является ли любое значение на самом деле null во время вывода схемы.
Неподдерживаемые логические типы данных Avro:
time-millistime-microsduration
Пример использования
Вставка данных
Чтобы вставить данные из файла Avro в таблицу ClickHouse:
Корневой схема загружаемого файла Avro должна быть типа record.
Чтобы найти соответствие между колонками таблицы и полями схемы Avro, ClickHouse сравнивает их имена. Это сравнение чувствительно к регистру, и неиспользуемые поля пропускаются.
Типы данных колонок таблицы ClickHouse могут отличаться от соответствующих полей вставляемых данных Avro. При вставке данных ClickHouse интерпретирует типы данных согласно таблице выше, а затем приводит типы данных к соответствующему типу колонки.
При импорте данных, когда поле не найдено в схеме и настройка input_format_avro_allow_missing_fields включена, будет использовано значение по умолчанию вместо генерации ошибки.
Выбор данных
Чтобы выбрать данные из таблицы ClickHouse в файл Avro:
Имена колонок должны:
- Начинаться с
[A-Za-z_] - Следовать только символами из
[A-Za-z0-9_]
Сжатие выходного файла Avro и интервал синхронизации можно настроить с помощью настроек output_format_avro_codec и output_format_avro_sync_interval соответственно.
Пример данных
Используя функцию ClickHouse DESCRIBE, вы можете быстро просмотреть определенный формат файла Avro, например, следующий.
Этот пример включает URL общедоступного файла Avro в публичном хранилище S3 ClickHouse:
Настройки формата
| Настройка | Описание | По умолчанию |
|---|---|---|
input_format_avro_allow_missing_fields | Для формата Avro/AvroConfluent: если поле не найдено в схеме, использовать значение по умолчанию вместо ошибки | 0 |
input_format_avro_null_as_default | Для формата Avro/AvroConfluent: вставить значение по умолчанию в случае null и не Nullable колонки | 0 |
format_avro_schema_registry_url | Для формата AvroConfluent: URL реестра схем Confluent. | |
output_format_avro_codec | Кодек сжатия, используемый для вывода. Возможные значения: 'null', 'deflate', 'snappy', 'zstd'. | |
output_format_avro_sync_interval | Интервал синхронизации в байтах. | 16384 |
output_format_avro_string_column_pattern | Для формата Avro: регулярное выражение для колонок String, которые следует выбрать как AVRO строку. | |
output_format_avro_rows_in_file | Максимальное количество строк в файле (если разрешено хранилищем) | 1 |