Avro

Input	Output	Alias
✔	✔

Описание

Apache Avro — это ориентированный на строки формат сериализации, который использует бинарное кодирование для эффективной обработки данных. Формат Avro поддерживает чтение и запись файлов данных Avro. Этот формат ожидает самоописывающие сообщения с встроенной схемой. Если вы используете Avro с реестром схем, обратитесь к формату AvroConfluent.

Сопоставление типов данных

Таблица ниже показывает все типы данных, поддерживаемые форматом 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

Не поддерживаемые логические типы данных Avro:

time-millis
time-micros
duration

Настройки формата

Настройка	Описание	По умолчанию
`input_format_avro_allow_missing_fields`	Использовать ли значение по умолчанию вместо генерации ошибки, если поле не найдено в схеме.	`0`
`input_format_avro_null_as_default`	Использовать ли значение по умолчанию вместо генерации ошибки при вставке значения `null` в ненулевую колонку.	`0`
`output_format_avro_codec`	Алгоритм сжатия для выходных файлов Avro. Возможные значения: `null`, `deflate`, `snappy`, `zstd`.
`output_format_avro_sync_interval`	Частота синхронизации маркеров в файлах Avro (в байтах).	`16384`
`output_format_avro_string_column_pattern`	Регулярное выражение для идентификации колонок `String` для сопоставления типа строки Avro. По умолчанию колонки `String` ClickHouse записываются как тип `bytes` Avro.
`output_format_avro_rows_in_file`	Максимальное количество строк на один выходной файл Avro. Когда этот лимит достигается, создается новый файл (если файловая система поддерживает разбиение файла).	`1`

Примеры

Чтение данных Avro

Чтобы прочитать данные из файла Avro в таблицу ClickHouse:

$ cat file.avro | clickhouse-client --query="INSERT INTO {some_table} FORMAT Avro"

Корневая схема импортируемого файла Avro должна быть типа record.

Чтобы найти соответствие между колонками таблицы и полями схемы Avro, ClickHouse сравнивает их имена. Это сравнение чувствительно к регистру, и неиспользуемые поля пропускаются.

Типы данных колонок таблицы ClickHouse могут отличаться от соответствующих полей вставленных данных Avro. При вставке данных ClickHouse интерпретирует типы данных согласно таблице выше, а затем приводит к типу данных к соответствующему типу колонки.

При импорте данных, когда поле не найдено в схеме, и включена настройка input_format_avro_allow_missing_fields, будет использовано значение по умолчанию вместо генерации ошибки.

Запись данных Avro

Чтобы записать данные из таблицы ClickHouse в файл Avro:

$ clickhouse-client --query="SELECT * FROM {some_table} FORMAT Avro" > file.avro

Имена колонок должны:

Начинаться с [A-Za-z_]
Далее могут содержать только [A-Za-z0-9_]

Сжатие выхода и интервал синхронизации для файлов Avro могут быть настроены с помощью настройки output_format_avro_codec и настройки output_format_avro_sync_interval соответственно.

Вывод схемы Avro

С помощью функции ClickHouse DESCRIBE вы можете быстро просмотреть выведенный формат файла Avro, как в следующем примере. Этот пример включает URL общедоступного файла Avro в публичной корзине ClickHouse S3:

DESCRIBE url('https://clickhouse-public-datasets.s3.eu-central-1.amazonaws.com/hits.avro','Avro);

┌─name───────────────────────┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ WatchID                    │ Int64           │              │                    │         │                  │                │
│ JavaEnable                 │ Int32           │              │                    │         │                  │                │
│ Title                      │ String          │              │                    │         │                  │                │
│ GoodEvent                  │ Int32           │              │                    │         │                  │                │
│ EventTime                  │ Int32           │              │                    │         │                  │                │
│ EventDate                  │ Date32          │              │                    │         │                  │                │
│ CounterID                  │ Int32           │              │                    │         │                  │                │
│ ClientIP                   │ Int32           │              │                    │         │                  │                │
│ ClientIP6                  │ FixedString(16) │              │                    │         │                  │                │
│ RegionID                   │ Int32           │              │                    │         │                  │                │
...
│ IslandID                   │ FixedString(16) │              │                    │         │                  │                │
│ RequestNum                 │ Int32           │              │                    │         │                  │                │
│ RequestTry                 │ Int32           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

Описание​

Сопоставление типов данных​

Настройки формата​

Примеры​

Чтение данных Avro​

Запись данных Avro​

Вывод схемы Avro​