> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Avro

> Документация по формату Avro

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

## Описание

[Apache Avro](https://avro.apache.org/) — это строчно-ориентированный формат сериализации, использующий двоичное кодирование для эффективной обработки данных. Формат `Avro` поддерживает чтение и запись [файлов данных Avro](https://avro.apache.org/docs/current/specification/#object-container-files). Этот формат предполагает самоописываемые сообщения со встроенной схемой. Если вы используете Avro с реестром схем, обратитесь к формату [`AvroConfluent`](https://clickhouse.com/docs/ru/reference/formats/Avro/AvroConfluent).

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

В таблице ниже приведены все типы данных, поддерживаемые форматом Apache Avro, и соответствующие им [типы данных](https://clickhouse.com/docs/ru/reference/data-types/index.md) ClickHouse в запросах `INSERT` и `SELECT`.

| Avro data type `INSERT` | ClickHouse data type | Avro data type `SELECT` |
| - | - | - |
| `boolean`, `int`, `long`, `float`, `double` | [Int(8\16\32)](https://clickhouse.com/docs/ru/reference/data-types/int-uint.md), [UInt(8\16\32)](https://clickhouse.com/docs/ru/reference/data-types/int-uint.md) | `int` |
| `boolean`, `int`, `long`, `float`, `double` | [Int64](https://clickhouse.com/docs/ru/reference/data-types/int-uint.md), [UInt64](https://clickhouse.com/docs/ru/reference/data-types/int-uint.md) | `long` |
| `boolean`, `int`, `long`, `float`, `double` | [Float32](https://clickhouse.com/docs/ru/reference/data-types/float.md) | `float` |
| `boolean`, `int`, `long`, `float`, `double` | [Float64](https://clickhouse.com/docs/ru/reference/data-types/float.md) | `double` |
| `bytes`, `string`, `fixed`, `enum` | [String](https://clickhouse.com/docs/ru/reference/data-types/string.md) | `bytes` or `string` \* |
| `bytes`, `string`, `fixed` | [FixedString(N)](https://clickhouse.com/docs/ru/reference/data-types/fixedstring.md) | `fixed(N)` |
| `enum` | [Enum(8\16)](https://clickhouse.com/docs/ru/reference/data-types/enum.md) | `enum` |
| `array(T)` | [Array(T)](https://clickhouse.com/docs/ru/reference/data-types/array.md) | `array(T)` |
| `map(V, K)` | [Map(V, K)](https://clickhouse.com/docs/ru/reference/data-types/map.md) | `map(string, K)` |
| `union(null, T)`, `union(T, null)` | [Nullable(T)](https://clickhouse.com/docs/ru/reference/data-types/date.md) | `union(null, T)` |
| `union(T1, T2, …)` \*\* | [Variant(T1, T2, …)](https://clickhouse.com/docs/ru/reference/data-types/variant.md) | `union(T1, T2, …)` \*\* |
| `null` | [Nullable(Nothing)](https://clickhouse.com/docs/ru/reference/data-types/special-data-types/nothing.md) | `null` |
| `int (date)` \*\*\* | [Date](https://clickhouse.com/docs/ru/reference/data-types/date.md), [Date32](https://clickhouse.com/docs/ru/reference/data-types/date32.md) | `int (date)` \*\*\* |
| `long (timestamp-millis)` \*\*\* | [DateTime64(3)](https://clickhouse.com/docs/ru/reference/data-types/datetime.md) | `long (timestamp-millis)` \*\*\* |
| `long (timestamp-micros)` \*\*\* | [DateTime64(6)](https://clickhouse.com/docs/ru/reference/data-types/datetime.md) | `long (timestamp-micros)` \*\*\* |
| `bytes (decimal)`  \*\*\* | [DateTime64(N)](https://clickhouse.com/docs/ru/reference/data-types/datetime.md) | `bytes (decimal)`  \*\*\* |
| `int` | [IPv4](https://clickhouse.com/docs/ru/reference/data-types/ipv4.md) | `int` |
| `fixed(16)` | [IPv6](https://clickhouse.com/docs/ru/reference/data-types/ipv6.md) | `fixed(16)` |
| `bytes (decimal)` \*\*\* | [Decimal(P, S)](https://clickhouse.com/docs/ru/reference/data-types/decimal.md) | `bytes (decimal)` \*\*\* |
| `string (uuid)` \*\*\* | [UUID](https://clickhouse.com/docs/ru/reference/data-types/uuid.md) | `string (uuid)` \*\*\* |
| `fixed(16)` | [Int128/UInt128](https://clickhouse.com/docs/ru/reference/data-types/int-uint.md) | `fixed(16)` |
| `fixed(32)` | [Int256/UInt256](https://clickhouse.com/docs/ru/reference/data-types/int-uint.md) | `fixed(32)` |
| `record` | [Tuple](https://clickhouse.com/docs/ru/reference/data-types/tuple.md) | `record` |

* `bytes` is default, controlled by setting [`output_format_avro_string_column_pattern`](https://clickhouse.com/docs/ru/reference/settings/formats/output-format#output_format_avro_string_column_pattern)

\*\*  [Тип Variant](https://clickhouse.com/docs/ru/reference/data-types/variant.md) неявно допускает `null` в качестве значения поля, поэтому, например, Avro `union(T1, T2, null)` будет преобразован в `Variant(T1, T2)`.
В результате при генерации Avro из ClickHouse нам всегда нужно включать тип `null` в набор типов Avro `union`, поскольку во время вывода схемы мы не знаем, является ли какое-либо из значений фактически `null`.

\*\*\* [Логические типы Avro](https://avro.apache.org/docs/1.12.0/specification/#logical-types)

Неподдерживаемые логические типы данных 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:

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

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

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

Типы данных столбцов таблицы ClickHouse могут отличаться от соответствующих полей вставляемых данных Avro. При вставке данных ClickHouse интерпретирует типы данных в соответствии с таблицей выше, а затем [приводит](https://clickhouse.com/docs/ru/reference/functions/regular-functions/type-conversion-functions.md#CAST) данные к соответствующему типу столбца.

При импорте данных, если поле не найдено в схеме и включена настройка [`input_format_avro_allow_missing_fields`](https://clickhouse.com/docs/ru/reference/settings/formats/input-format#input_format_avro_allow_missing_fields), вместо ошибки будет использовано значение по умолчанию.

### Запись данных в формате Avro

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

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

Имена столбцов должны:

* Начинаться с `[A-Za-z_]`
* Содержать далее только `[A-Za-z0-9_]`

Сжатие вывода и интервал синхронизации для файлов Avro можно настроить с помощью параметров [`output_format_avro_codec`](https://clickhouse.com/docs/ru/reference/settings/formats/output-format#output_format_avro_codec) и [`output_format_avro_sync_interval`](https://clickhouse.com/docs/ru/reference/settings/formats/output-format#output_format_avro_sync_interval) соответственно.

### Определение схемы Avro

С помощью функции ClickHouse [`DESCRIBE`](https://clickhouse.com/docs/ru/reference/statements/describe-table) можно быстро просмотреть автоматически выведенную схему файла Avro, как в следующем примере.
В этом примере используется URL общедоступного файла Avro из публичного бакета S3 ClickHouse:

```sql theme={null}
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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```
