Avro

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

Описание

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` в столбец, не допускающий `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​