Avro - ClickHouse Documentation

Ввод	Вывод	Псевдоним
✔	✔

Описание

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

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

В таблице ниже приведены все типы данных, поддерживаемые форматом Apache Avro, и соответствующие им типы данных ClickHouse в запросах INSERT и SELECT.

Avro data type `INSERT`	ClickHouse data type	Avro data type `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` or `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 is default, controlled by setting 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` в столбец, не допускающий `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. По умолчанию столбцы ClickHouse `String` записываются как тип Avro `bytes`.
`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 из публичного бакета S3 ClickHouse:

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