Avro
| 入力 | 出力 | エイリアス |
|---|---|---|
| ✔ | ✔ |
説明
Apache Avroは、ApacheのHadoopプロジェクト内で開発された行指向データシリアライゼーションフレームワークです。
ClickHouseのAvro形式は、Avroデータファイルの読み取りと書き込みをサポートしています。
データ型の一致
The table below shows all data types supported by the Apache Avro format, and their corresponding ClickHouse data types in INSERT and SELECT queries.
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タイプ はフィールド値として null を暗黙的に受け入れるため、たとえば Avro の union(T1, T2, null) は Variant(T1, T2) に変換されます。その結果、ClickHouseからAvroを生成する際には、スキーマ推論中に実際に値が null であるかどうかわからないため、常に null 型をAvroの union 型セットに含める必要があります。
*** Avro論理型
サポートされていない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形式の場合：ヌルおよび非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 |