メインコンテンツまでスキップ
メインコンテンツまでスキップ

Avro

InputOutputAlias
✔✔

説明​

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

データ型のマッピング​

以下の表は、Apache Avro形式がサポートするすべてのデータ型と、それに対応するClickHouseのdata typesにおけるINSERTおよびSELECTクエリの対応表です。

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タイプは、フィールド値としてnullを暗黙的に受け入れるため、例えばAvroのunion(T1, T2, null)はVariant(T1, T2)に変換されます。その結果、ClickHouseからAvroを生成する際には、スキーマ推論中に実際にどの値がnullであるか分からないため、常にAvroのunion型集合にnullタイプを含める必要があります。

*** Avro論理タイプ

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

  • time-millis
  • time-micros
  • duration

フォーマット設定​

設定説明デフォルト
input_format_avro_allow_missing_fieldsスキーマにフィールドが見つからなかった場合、エラーを投げる代わりにデフォルト値を使用するかどうか。0
input_format_avro_null_as_default非 Nullable カラムに null 値を挿入する場合、エラーを投げる代わりにデフォルト値を使用するかどうか。0
output_format_avro_codecAvro 出力ファイルに対する圧縮アルゴリズム。可能な値：null、deflate、snappy、zstd。
output_format_avro_sync_intervalAvro ファイル内の同期マーカーの頻度（バイト数単位）。16384
output_format_avro_string_column_patternAvro 文字列型マッピングのための String カラムを識別する正規表現。デフォルトでは、ClickHouse の String カラムは Avro bytes 型として書き込まれます。
output_format_avro_rows_in_fileAvro 出力ファイルあたりの最大行数。この制限に達すると、新しいファイルが作成されます（ストレージシステムがファイル分割をサポートしている場合）。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           │              │                    │         │                  │                │
└────────────────────────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘