Avro
| Input | Output | Alias |
|---|---|---|
| ✔ | ✔ |
説明
Apache Avro は、Apache の Hadoop プロジェクト内で開発された行指向のデータシリアル化フレームワークです。
ClickHouse の Avro フォーマットは、Avro データファイルの読み書きをサポートしています。
データ型の対応
以下のテーブルは、Apache Avro フォーマットがサポートするすべてのデータ型と、それに対応する ClickHouse のdata types を 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 type はフィールド値として null を暗黙的に受け入れるため、例えば Avro の union(T1, T2, null) は Variant(T1, T2) に変換されます。
その結果、ClickHouse から Avro を生成する際には、スキーマ推論中に実際に値が null であるかどうかわからないため、常に Avro union 型セットに null 型を含める必要があります。
サポートされていない Avro 論理データ型:
time-millistime-microsduration
使用例
データの挿入
Avro ファイルから ClickHouse テーブルにデータを挿入するには：
取り込む Avro ファイルのルートスキーマは record タイプでなければなりません。
テーブルのカラムと Avro スキーマのフィールドの対応を見つけるために、ClickHouse はそれらの名前を比較します。 この比較は大文字小文字を区別し、未使用のフィールドはスキップされます。
ClickHouse テーブルカラムのデータ型は、挿入される Avro データの対応するフィールドと異なる場合があります。データを挿入する際、ClickHouse は上記のテーブルに従ってデータ型を解釈し、その後にキャストして対応するカラムタイプに変換します。
データをインポートする際に、スキーマにフィールドが見つからず、設定 input_format_avro_allow_missing_fields が有効になっている場合、エラーをスローするのではなく、デフォルト値が使用されます。
データの選択
ClickHouse テーブルから Avro ファイルにデータを選択するには：
カラム名は以下の条件を満たさなければなりません：
[A-Za-z_]で始まる- 続けて
[A-Za-z0-9_]のみが使用される
出力 Avro ファイルの圧縮と同期間隔は、設定 output_format_avro_codec および output_format_avro_sync_interval によってそれぞれ構成できます。
例データ
ClickHouse の DESCRIBE 関数を使用することで、次の例のように Avro ファイルの推測フォーマットを迅速に表示できます。
この例には、ClickHouse S3 パブリックバケットにある公開アクセス可能な Avro ファイルの URL が含まれています：
フォーマット設定
| 設定 | 説明 | デフォルト |
|---|---|---|
input_format_avro_allow_missing_fields | Avro/AvroConfluent フォーマット用：スキーマにフィールドが見つからない場合、エラーの代わりにデフォルト値を使用 | 0 |
input_format_avro_null_as_default | Avro/AvroConfluent フォーマット用：null と非 Nullable カラムの場合にデフォルトを挿入する | 0 |
format_avro_schema_registry_url | AvroConfluent フォーマット用：Confluent スキーマレジストリ URL。 | |
output_format_avro_codec | 出力に使用される圧縮コーデック。可能な値：'null', 'deflate', 'snappy', 'zstd'。 | |
output_format_avro_sync_interval | バイト単位の同期間隔。 | 16384 |
output_format_avro_string_column_pattern | Avro フォーマット用：AVRO 文字列として選択する String カラムの正規表現。 | |
output_format_avro_rows_in_file | ファイル内の最大行数（ストレージが許可する場合） | 1 |
