メインコンテンツへスキップ
メインコンテンツへスキップ

Avro

入力出力エイリアス
✔✔

説明​

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

データ型マッピング​

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

Avro データ型 INSERTClickHouse データ型Avro データ型 SELECT
boolean, int, long, float, doubleInt(8\16\32), UInt(8\16\32)int
boolean, int, long, float, doubleInt64, UInt64long
boolean, int, long, float, doubleFloat32float
boolean, int, long, float, doubleFloat64double
bytes, string, fixed, enumStringbytes または string *
bytes, string, fixedFixedString(N)fixed(N)
enumEnum(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, …) **
nullNullable(Nothing)null
int (date) ***Date, Date32int (date) ***
long (timestamp-millis) ***DateTime64(3)long (timestamp-millis) ***
long (timestamp-micros) ***DateTime64(6)long (timestamp-micros) ***
bytes (decimal) ***DateTime64(N)bytes (decimal) ***
intIPv4int
fixed(16)IPv6fixed(16)
bytes (decimal) ***Decimal(P, S)bytes (decimal) ***
string (uuid) ***UUIDstring (uuid) ***
fixed(16)Int128/UInt128fixed(16)
fixed(32)Int256/UInt256fixed(32)
recordTuplerecord

* 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 logical types

サポートされていない Avro の論理データ型:

  • time-millis
  • time-micros
  • duration

フォーマット設定​

設定説明デフォルト
input_format_avro_allow_missing_fieldsスキーマ内にフィールドが存在しない場合にエラーとする代わりにデフォルト値を使用するかどうか。0
input_format_avro_null_as_defaultNULL 不可の列に null 値を挿入する際にエラーとする代わりにデフォルト値を使用するかどうか。0
output_format_avro_codecAvro 出力ファイルの圧縮アルゴリズム。指定可能な値: null, deflate, snappy, zstd.
output_format_avro_sync_intervalAvro ファイルにおける同期マーカーの頻度（バイト単位）。16384
output_format_avro_string_column_patternAvro の string 型にマッピングする対象となる String 列を識別するための正規表現。デフォルトでは、ClickHouse の String 列は Avro の bytes 型として書き出される。
output_format_avro_rows_in_file1 つの Avro 出力ファイルあたりの最大行数。この上限に達すると、新しいファイルが作成される（ストレージシステムがファイル分割をサポートしている場合）。1

例​

Avro データの読み取り​

Avro ファイルから ClickHouse テーブルにデータを読み込むには、次のとおりです。

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

取り込まれた Avro ファイルのルートスキーマは、record 型でなければなりません。

テーブルのカラムと Avro スキーマのフィールドを対応付けるために、ClickHouse はそれらの名前を比較します。 この比較は大文字と小文字を区別し、未使用のフィールドはスキップされます。

ClickHouse テーブルのカラムのデータ型は、挿入される Avro データの対応するフィールドと異なる場合があります。データを挿入する際、ClickHouse は上記のテーブルに従ってデータ型を解釈し、その後データを対応するカラム型にキャストします。

データをインポートする際、スキーマ内でフィールドが見つからず、設定 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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘