Arrow - ClickHouse Documentation

入力	出力	エイリアス
✔	✔

説明

Apache Arrow には、組み込みの列指向ストレージフォーマットが 2 種類あります。 ClickHouse はこれらのフォーマットの読み書きをサポートしています。 Arrow は Apache Arrow の「ファイルモード」フォーマットで、メモリ内でのランダムアクセス向けに設計されています。

データ型の対応

以下の表は、サポートされているデータ型と、INSERT クエリおよび SELECT クエリでそれらが ClickHouse の data types にどのように対応するかを示しています。

Arrow データ型 (`INSERT`)	ClickHouse データ型	Arrow データ型 (`SELECT`)
`BOOL`	Bool	`BOOL`
`UINT8`, `BOOL`	UInt8	`UINT8`
`INT8`	Int8/Enum8	`INT8`
`UINT16`	UInt16	`UINT16`
`INT16`	Int16/Enum16	`INT16`
`UINT32`	UInt32	`UINT32`
`INT32`	Int32	`INT32`
`UINT64`	UInt64	`UINT64`
`INT64`	Int64	`INT64`
`FLOAT`, `HALF_FLOAT`	Float32	`FLOAT32`
`DOUBLE`	Float64	`FLOAT64`
`DATE32`	Date32	`UINT16`
`DATE64`	DateTime	`UINT32`
`TIMESTAMP`	DateTime64	`TIMESTAMP`
`TIME32`, `TIME64`	Time64	`TIME32`, `TIME64`
`STRING`, `BINARY`	String	`BINARY`
`STRING`, `BINARY`, `FIXED_SIZE_BINARY`	FixedString	`FIXED_SIZE_BINARY`
`DECIMAL`	Decimal	`DECIMAL`
`DECIMAL256`	Decimal256	`DECIMAL256`
`LIST`	Array	`LIST`
`STRUCT`	Tuple	`STRUCT`
`MAP`	Map	`MAP`
`UINT32`	IPv4	`UINT32`
`FIXED_SIZE_BINARY`, `BINARY`	IPv6	`FIXED_SIZE_BINARY`
`FIXED_SIZE_BINARY`, `BINARY`	Int128/UInt128/Int256/UInt256	`FIXED_SIZE_BINARY`
`DURATION`	Interval (Nanosecond/Microsecond/Millisecond/Second)	`DURATION`
`INT64`	Interval (Minute/Hour/Day/Week/Month/Quarter/Year)	`INT64`

Array はネストでき、引数として Nullable 型の値を取ることもできます。Tuple 型と Map 型もネストできます。 DICTIONARY 型は INSERT クエリでサポートされています。SELECT クエリでは、output_format_arrow_low_cardinality_as_dictionary 設定により、LowCardinality 型を DICTIONARY 型として出力できます。LowCardinality の Dictionary には未使用の値が含まれる場合があり、その結果、出力される Arrow の DICTIONARY にも未使用の値が含まれる可能性がある点に注意してください。サポートされていない Arrow データ型:

JSON
ENUM.

ClickHouse テーブルのカラムのデータ型は、対応する Arrow のデータフィールドと一致している必要はありません。データを挿入する際、ClickHouse はまず上の表に従ってデータ型を解釈し、その後、データを ClickHouse テーブルのカラムに設定されたデータ型にキャストします。

使用例

以下の例では、ClickHouse SQL playground で利用可能な forex データセットを使用します。

データの選択

Playground から EUR/USD の為替レートの 1 日分を取得し、ローカルの forex_eurusd.arrow ファイルに保存します。HTTP インターフェイス経由で Playground にクエリを送信します。ホストは sql-clickhouse.clickhouse.com、ユーザーは demo (パスワードなし) です:

curl "https://sql-clickhouse.clickhouse.com:8443/?user=demo&database=forex" \
    --data-binary "
        SELECT
            concat(base, '.', quote) AS base_quote,
            datetime AS last_update,
            CAST(bid, 'Float32') AS bid,
            CAST(ask, 'Float32') AS ask,
            ask - bid AS spread
        FROM forex
        WHERE base = 'EUR' AND quote = 'USD'
            AND datetime >= '2020-01-01' AND datetime < '2020-01-02'
        ORDER BY datetime ASC
        FORMAT Arrow
        SETTINGS output_format_arrow_compression_method='zstd'" > forex_eurusd.arrow

ファイルを読み戻す

これで、clickhouse-local と file テーブル関数を使って、ローカルの Arrow ファイルを読み戻せます。このファイルは自己記述型なので、Arrow フォーマットがスキーマを自動的に推論します。

clickhouse-local --query "
    SELECT *
    FROM file('forex_eurusd.arrow', Arrow)
    ORDER BY last_update ASC
    LIMIT 5
    FORMAT PrettyCompact"

Response

   ┌─base_quote─┬─────────────last_update─┬─────bid─┬─────ask─┬────────────────spread─┐
│ EUR.USD    │ 2020-01-01 17:00:00.065 │  1.1212 │ 1.12172 │ 0.0005199909210205078 │
│ EUR.USD    │ 2020-01-01 17:00:10.447 │  1.1212 │ 1.12192 │ 0.0007200241088867188 │
│ EUR.USD    │ 2020-01-01 17:00:10.498 │ 1.12117 │ 1.12161 │ 0.0004400014877319336 │
│ EUR.USD    │ 2020-01-01 17:00:12.579 │  1.1212 │ 1.12161 │ 0.0004100799560546875 │
│ EUR.USD    │ 2020-01-01 17:00:12.630 │  1.1212 │ 1.12172 │ 0.0005199909210205078 │
   └────────────┴─────────────────────────┴─────────┴─────────┴───────────────────────┘

データの挿入

Arrow ファイルを ClickHouse テーブルに読み込むには、FORMAT Arrow を指定して clickhouse-client にパイプして渡します:

cat forex_eurusd.arrow | clickhouse-client --query="INSERT INTO some_table FORMAT Arrow"

フォーマット設定

設定	説明	デフォルト
`input_format_arrow_allow_missing_columns`	Arrow入力フォーマットの読み取り時に、欠落しているカラムを許可します。	`1`
`input_format_arrow_case_insensitive_column_matching`	ArrowのカラムとCHカラムの照合時に、大文字と小文字の違いを無視します。	`0`
`input_format_arrow_import_nested`	廃止された設定で、何も行いません。	`0`
`input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference`	Arrowフォーマットのスキーマ推論時に、未対応の型を持つカラムをスキップします。	`0`
`input_format_arrow_use_native_reader`	`Arrow` および `ArrowStream` フォーマットでは、Apache Arrowライブラリの代わりにClickHouseネイティブのリーダーを使用します。Apache Arrowライブラリのリーダーを使用するには `0` に設定します。	`1`
`output_format_arrow_compression_method`	Arrow出力フォーマットの圧縮方式です。サポートされるコーデック: lz4_frame, zstd, none (非圧縮)	`lz4_frame`
`output_format_arrow_fixed_string_as_fixed_byte_array`	FixedStringカラムでは、Binaryの代わりにArrowのFIXED_SIZE_BINARY型を使用します。	`1`
`output_format_arrow_low_cardinality_as_dictionary`	LowCardinality型をArrowのDictionary型として出力します。	`0`
`output_format_arrow_string_as_string`	Stringカラムでは、Binaryの代わりにArrowのString型を使用します。	`1`
`output_format_arrow_unsupported_types_as_binary`	Arrowに対応する型がない型 (たとえば `BFloat16`、`AggregateFunction`) を、生のバイナリデータとして出力します。`false` の場合、そのような型では例外が発生します。ネイティブライターとApache Arrowライブラリライターの両方に適用されます。	`1`
`output_format_arrow_use_64_bit_indexes_for_dictionary`	ArrowフォーマットのDictionaryインデックスには常に64ビット整数を使用します。	`0`
`output_format_arrow_use_native_writer`	`Arrow` および `ArrowStream` フォーマットでは、Apache Arrowライブラリの代わりにClickHouseネイティブのライターを使用します。Apache Arrowライブラリのライターを使用するには `0` に設定します。	`1`
`output_format_arrow_use_signed_indexes_for_dictionary`	ArrowフォーマットのDictionaryインデックスに符号付き整数を使用します。	`1`

​説明

​データ型の対応

​使用例

​データの選択

​ファイルを読み戻す

​データの挿入

​フォーマット設定

説明

データ型の対応

使用例

データの選択

ファイルを読み戻す

データの挿入

フォーマット設定