> ## 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

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

<div id="description">
  ## Описание
</div>

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

<div id="data-type-mapping">
  ## Сопоставление типов данных
</div>

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

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

* `bytes` is default, controlled by setting [`output_format_avro_string_column_pattern`](/docs/ru/reference/settings/formats#output_format_avro_string_column_pattern)

\*\*  [Тип Variant](/docs/ru/reference/data-types/variant) неявно допускает `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`

<div id="format-settings">
  ## Настройки формата
</div>

| Настройка                                  | Описание                                                                                                                                                                      | По умолчанию |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `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`          |

<div id="examples">
  ## Примеры
</div>

<div id="reading-avro-data">
  ### Чтение данных в формате Avro
</div>

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

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

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

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

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

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

<div id="writing-avro-data">
  ### Запись данных в формате Avro
</div>

Чтобы записать данные из таблицы 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`](/docs/ru/reference/settings/formats#output_format_avro_codec) и [`output_format_avro_sync_interval`](/docs/ru/reference/settings/formats#output_format_avro_sync_interval) соответственно.

<div id="inferring-the-avro-schema">
  ### Определение схемы Avro
</div>

С помощью функции ClickHouse [`DESCRIBE`](/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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```