> ## 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/ja/reference/formats/Avro/AvroConfluent) フォーマットを参照してください。

<div id="data-type-mapping">
  ## データ型マッピング
</div>

次の表は、Apache Avro フォーマットでサポートされるすべてのデータ型と、`INSERT` および `SELECT` クエリでそれぞれに対応する ClickHouse の[データ型](/docs/ja/reference/data-types/index)を示しています。

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

* `bytes` がデフォルトで、設定 [`output_format_avro_string_column_pattern`](/docs/ja/reference/settings/formats#output_format_avro_string_column_pattern) で制御されます

\*\*  [Variant 型](/docs/ja/reference/data-types/variant) は `null` をフィールド値として暗黙的に受け入れるため、たとえば Avro の `union(T1, T2, null)` は `Variant(T1, T2)` に変換されます。
そのため、ClickHouse から Avro を生成する際には、Avro の `union` 型の候補に常に `null` 型を含める必要があります。これは、スキーマ推論の時点では、実際に `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` 値を Nullable ではないカラムに挿入する際に、エラーを返す代わりにデフォルト値を使用するかどうか。                                                    | `0`     |
| `output_format_avro_codec`                 | Avro 出力ファイルの圧縮アルゴリズム。設定可能な値: `null`, `deflate`, `snappy`, `zstd`。                                               |         |
| `output_format_avro_sync_interval`         | Avro ファイル内の同期マーカーの同期間隔 (バイト単位) 。                                                                                | `16384` |
| `output_format_avro_string_column_pattern` | Avro の文字列型への型マッピングに使用する `String` カラムを識別するための正規表現。デフォルトでは、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 は上の表に従ってデータ型を解釈し、その後、データを対応するカラム型に[CAST](/docs/ja/reference/functions/regular-functions/type-conversion-functions#CAST)します。

データのインポート中に、スキーマ内にフィールドが見つからず、かつ設定 [`input_format_avro_allow_missing_fields`](/docs/ja/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/ja/reference/settings/formats#output_format_avro_codec) 設定と [`output_format_avro_sync_interval`](/docs/ja/reference/settings/formats#output_format_avro_sync_interval) 設定を使用して構成できます。

<div id="inferring-the-avro-schema">
  ### Avro スキーマの推定
</div>

ClickHouse の [`DESCRIBE`](/docs/ja/reference/statements/describe-table) 関数を使うと、次の例のように、Avro ファイルの推定フォーマットをすばやく確認できます。
この例には、ClickHouse の S3 パブリックバケットで公開されている Avro ファイルの URL が含まれています。

```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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```