Avro

入力	出力	エイリアス
✔	✔

説明

Apache Avro は、効率的なデータ処理のためにバイナリエンコーディングを使用する行指向のシリアライゼーションフォーマットです。Avro フォーマットは、Avroデータファイルの読み取りと書き込みをサポートします。このフォーマットは、スキーマが埋め込まれた自己記述型メッセージを前提としています。Avro をスキーマレジストリとともに使用する場合は、AvroConfluent フォーマットを参照してください。

データ型マッピング

次の表は、Apache Avro フォーマットでサポートされるすべてのデータ型と、INSERT および SELECT クエリでそれぞれに対応する ClickHouse のデータ型を示しています。

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` または `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) に変換されます。そのため、ClickHouse から Avro を生成する際には、Avro の union 型の候補に常に null 型を含める必要があります。これは、スキーマ推論の時点では、実際に null となる値があるかどうか分からないためです。 *** Avro 論理型サポートされていない Avro 論理データ型:

time-millis
time-micros
duration

フォーマット設定

設定	説明	デフォルト
`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`

例

Avroデータの読み取り

AvroファイルからClickHouseのテーブルにデータを読み込むには:

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

取り込まれる Avro ファイルのルートスキーマは、record 型でなければなりません。テーブルのカラムと Avro スキーマのフィールドの対応関係を特定するために、ClickHouse はそれらの名前を比較します。この比較では大文字と小文字が区別され、使用されないフィールドはスキップされます。 ClickHouse テーブルのカラムのデータ型は、挿入される Avro データ内の対応するフィールドと異なる場合があります。データを挿入する際、ClickHouse は上の表に従ってデータ型を解釈し、その後、データを対応するカラム型にCASTします。データのインポート中に、スキーマ内にフィールドが見つからず、かつ設定 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 ファイルの推定フォーマットをすばやく確認できます。この例には、ClickHouse の S3 パブリックバケットで公開されている Avro ファイルの URL が含まれています。

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

SQLリファレンス

データ型

エンジン

関数

フォーマット

設定

システムテーブル

データレイク

説明

データ型マッピング

フォーマット設定

例

Avroデータの読み取り

Avroデータの書き込み

Avro スキーマの推定

​説明

​データ型マッピング

​フォーマット設定

​例

​Avroデータの読み取り

​Avroデータの書き込み

​Avro スキーマの推定

説明

データ型マッピング

フォーマット設定

例

Avroデータの読み取り

Avroデータの書き込み

Avro スキーマの推定