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

説明

Apache Parquet は、Hadoop エコシステムで広く使われている列指向のストレージフォーマットです。ClickHouse は、このフォーマットの読み取りと書き込みをサポートしています。

データ型の対応

以下の表は、Parquet のデータ型が ClickHouse のデータ型にどのように対応しているかを示しています。 Parquet ファイルへの書き込み時には、対応する Parquet 型がないデータ型は、利用可能な最も近い型に変換されます。 Array はネストでき、引数として Nullable 型の値を取ることもできます。Tuple 型と Map 型もネストできます。

ワイド整数

デフォルトでは、ClickHouse は Int128、UInt128、Int256、UInt256 を、リトルエンディアンの注釈なし FIXED_LEN_BYTE_ARRAY(16/32) 値として書き込みます。このレガシー表現は、古い ClickHouse バージョンでもファイルを読み取れるようにするため、引き続きデフォルトとして使用されます。 標準の Parquet DECIMAL 表現を使用するには、代わりに output_format_parquet_wide_integer_as_decimal = 1 を設定します。 10 進数表現では、標準 Parquet のカラムチャンク統計とページインデックスで数値順序が提供されるため、ClickHouse は行グループおよびページの最小値/最大値による枝刈りを利用できます。ClickHouse は両方のエンコードを読み取ります。10 進精度 39 の場合、スキーマ推論は Decimal256 を基盤とする Decimal(39, 0) を返します。ワイド整数型を復元するには、明示的な Int128 または UInt128 の構造を指定してください。10 進精度 77 または 78 は ClickHouse Decimal256 の範囲を超えるため、これらのファイルを読み取るには、互換性のある Int256 または UInt256 の明示的な構造が必要です。明示的なワイド整数構造を指定すると、ClickHouse は任意の有効な幅の BYTE_ARRAY または FIXED_LEN_BYTE_ARRAY として保存された標準の 10 進値を受け入れ、符号拡張を削除した後にすべての値を範囲チェックします。 一部の Parquet クライアントは 10 進精度を 38 までしかサポートしておらず、Arrow の高水準 10 進型は精度を 76 までしかサポートしていません。このようなクライアントは、スキーマと 33 バイトの物理幅が Parquet に準拠していても、精度 77/78 の表現を拒否することがあります。ファイルを古い ClickHouse バージョンまたはより小さい 10 進数制限を持つクライアントで読み取る必要がある場合は、この設定を無効のままにしてください。 ClickHouse table のカラムのデータ型は、挿入される Parquet data の対応するフィールドと異なる場合があります。データを挿入する際、ClickHouse は上の表に従ってデータ型を解釈し、その後、データを ClickHouse table のカラムに設定されたデータ型にキャストします。たとえば、UINT_32 の Parquet カラムは IPv4 の ClickHouse カラムに読み込むことができます。 一部の Parquet 型には、厳密に対応する ClickHouse 型がありません。これらは次のように読み取られます。
  • isAdjustedToUTC=false の TIMESTAMP はローカルの wall-clock time (どの time zone がローカルと見なされるかにかかわらず、ローカル timezone における年、月、日、時、分、秒、および秒未満の各フィールドを持つ時刻) で、SQL TIMESTAMP WITHOUT TIME ZONE と同じです。しかし ClickHouse は、これを UTC の timestamp であるかのように読み取ります。例: 2025-09-29 18:42:13.000 (ローカルの時計の表示を表す値) は 2025-09-29 18:42:13.000 (時点を表す DateTime64(3, 'UTC')) になります。String に変換すると、年、月、日、時、分、秒、および秒未満の値は正しく表示されるため、それを UTC ではなく何らかのローカル timezone の値として解釈できます。直感に反しますが、型を DateTime64(3, 'UTC') から DateTime64(3) に変更しても改善しません。どちらの型も時計の表示ではなく時点を表すためです。ただし、DateTime64(3) はローカル timezone を使って誤ってフォーマットされます。
  • INTERVAL は現在、Parquet ファイルでエンコードされた時間間隔の生のバイナリ表現を持つ FixedString(12) として読み取られます。

Variant 型

ClickHouse は、Spark 4.0 などで書き込まれた Parquet の VARIANT エンコーディングで格納されたカラムを、Dynamic 型として読み取ります。VARIANT 論理型(仕様バージョン 1)のアノテーションが付いたグループは、variant カラムとして認識されます。ただし Spark 4.0 はこのアノテーションを付けずに variant カラムを書き込むため、BYTE_ARRAY 型の metadata フィールドと value フィールドのみを持つグループも variant として読み取られます。この動作は設定 input_format_parquet_detect_variant_by_structure で無効化できます。その場合、このようなグループは従来どおり 2 つの生フィールドからなる Tuple として読み取られます。なお、カラムに対して Dynamic 型または JSON 型を明示的に指定した場合は、この設定に関係なく variant として読み取られます。 各値はそれぞれ固有の型を保持します。variant のプリミティブ型は、対応する ClickHouse の型として読み取られます(例:int32 は Int32、decimal8 は Decimal(18, S)、timestamp は DateTime64(6, 'UTC')、timestamp_ntz は DateTime64(6)、binary と string は String、uuid は UUID)。variant の null は NULL として読み取られます。variant のオブジェクトは JSON として読み取られ、ネストされたオブジェクトはドット区切りのパスにフラット化されます(値が null のフィールドは存在しないものとして扱われます)。要素がすべてオブジェクトである variant の配列は Array(JSON) として、それ以外の variant の配列は Array(Dynamic) として読み取られます。variant の値はオブジェクトであるとは限らないため、最上位の型は JSON ではなく Dynamic になります。 variant カラムは、テーブル構造や file テーブル関数の structure 引数などで型を明示的に指定すれば、JSON として読み取ることもできます。この場合、すべての値がオブジェクトでなければならず、オブジェクト以外の値があると例外がスローされます。variant の null およびカラム全体の null は、空のオブジェクトとして読み取られます。指定した JSON 型の型指定されたパスはそれぞれの型に変換され、SKIP および SKIP REGEXP に列挙されたパスはスキップされます。 シュレッド化された variant(typed_value フィールドを持つグループ)は、現時点ではサポートされていません。このようなカラムを読み取ると例外がスローされますが、ファイル内の他のカラムは問題なく読み取れます。また、input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference が有効な場合、スキーマ推論ではそのカラムがスキップされます。なお、Dynamic カラムや JSON カラムを Parquet に VARIANT として書き込むこともサポートされていません。

ファイル参照

Parquet の FILE 論理型でアノテーションされたグループは、インラインまたは外部ファイルに保存されたバイト範囲への参照を表します。このグループは、ファイル内に存在するフィールドからなる名前付き Tuple として読み込まれ、各フィールドは Nullable になります。具体的には、uri、content_type、checksum は Nullable(String)、offset と size は Nullable(Int64)、inline は raw bytes を格納する Nullable(String) として読み込まれます。null のファイル参照は、すべての要素が NULL のタプルとして読み込まれます。他の Tuple と同様に、要素数の少ない Tuple を指定すればフィールドの部分集合のみを読み込むことができ、file.uri のように個々のフィールドをサブカラムとして読み込むこともできます。グループのスキーマは検証され、これらのフィールドのみを含み、すべてが OPTIONAL で、仕様で定義された型である必要があります。この条件を満たさない場合は例外がスローされます。一方、値は検証されません。有効な参照を構成しない値 (例えば uri のない offset) も、保存されたとおりに返されます。ClickHouse は参照を解決しません。つまり、外部ファイルの読み込みは行いません。 書き込み時には、このような Tuple (要素名が FILE フィールドの空でない部分集合で、offset と size が整数、その他の要素が String または FixedString であるもの) は、設定 output_format_parquet_write_file_logical_type が有効な場合に FILE アノテーション付きのグループとして書き込まれます。無効な場合は通常のグループとして書き込まれます。

幾何データ型 (GeoParquet)

ClickHouse は、GeoParquet 仕様および Parquet の GEOMETRY および GEOGRAPHY 論理型 に準拠した ジオメトリカラム の読み書きをサポートしています。ジオメトリカラム は、WKB (GeoParquet の読み取り時は WKT) でエンコードされた BYTE_ARRAY ペイロードとして保存されます。GeoParquet では、ファイルレベルの Parquet メタデータ内の JSON の geo キーに、各 ジオメトリカラム のエンコーディング、ジオメトリ型、CRS が記述されます。一方、論理型はカラム自体に付与され、カラムチャンクのメタデータには min/max 統計の代わりに GeospatialStatistics (バウンディングボックスとジオメトリ型の一覧) が含まれます。1 つのファイルに両方が含まれる場合もあります。

読み取り時の挙動

読み取り時には、ジオメトリカラム は対応する ClickHouse の幾何データ型にマッピングされます。
  • Point、MultiPoint、LineString、Polygon、MultiLineString、または MultiPolygon として宣言されたカラムは、対応する ClickHouse の 幾何データ型として読み取られます。
  • 複数の ジオメトリ型 を持つカラム、または ジオメトリ型 が不明なカラムは、サポートされているすべての 幾何データ型に対する Variant である Geometry 型として読み取られます。
  • GEOMETRY または GEOGRAPHY 論理型を持つカラムの場合、ファイルに GeoParquet メタデータがあれば、ジオメトリ型はそこから取得されます。メタデータがない場合は、すべてのカラムチャンクの GeospatialStatistics が同一の単一 2D ジオメトリ型を示していれば対応する 幾何データ型として、そうでなければ Geometry として読み取られます。幾何データ型が明示的に要求された場合、値はその型へ直接デコードされます。
  • ClickHouse には geography 専用の型がないため、GEOGRAPHY カラムは GEOMETRY と同じ 幾何データ型として読み取られ (座標は経度と緯度として扱われます) 、エッジ補間アルゴリズム (algorithm パラメータ) は保持されません。CRS (crs パラメータ、デフォルトは OGC:CRS84) も同様に保持されません。Z 座標または M 座標を持つジオメトリはサポートされていません。
  • GEOMETRY および GEOGRAPHY 論理型のソート順は未定義であるため、こうしたカラムの min/max 統計情報とカラムインデックスは無視されます。input_format_parquet_spatial_filter_push_down を有効にすると、GeospatialStatistics のバウンディングボックスを使って行グループがスキップされます。
  • 要求されたカラム型が String の場合、GeoParquet のメタデータと論理型は無視され、エンコード済みの生のジオメトリ ペイロード がそのまま返されます。返されるのは、GeoParquet カラムで宣言されているエンコードに応じた WKB または WKT のバイト列です。これは、設定 input_format_parquet_allow_geoparquet_parser が 0 に設定されており、かつ 幾何データ型が明示的に要求されていない場合も同様です。

書き込み動作

書き込み時には、型が Point、MultiPoint、LineString、Polygon、MultiLineString、または MultiPolygon のトップレベルのカラムは BYTE_ARRAY (WKB) としてエンコードされ、適切な geo JSON メタデータが Parquet ファイルのフッターに追加されます。トップレベルの Geometry Variant も WKB の BYTE_ARRAY ペイロード としてエンコードされます (その下位の値は WKB に変換され、Nullable(String) カラムとして保存されます) が、デフォルトではこれについて geo メタデータが出力されないため、String として読み込まれます。これらのカラムは、デフォルトでは min/max 統計情報付きの BYTE_ARRAY として書き込まれます。設定 output_format_parquet_geometry_logical_type を有効にすると、これらのカラムはすべて、デフォルトの CRS (OGC:CRS84) を指定した GEOMETRY 論理型で注釈付けされます。また、仕様の要求に従い、カラムチャンクのメタデータには GeospatialStatistics (バウンディングボックスとジオメトリ型) が含まれ、min/max 統計情報やカラムインデックスは含まれません。さらに、Geometry カラムは geo メタデータ内で空のジオメトリ型リストとともに記述されるため、Geometry として読み込まれます。この論理型に対応していないリーダー (例: バージョン 20 より前の Arrow C++ や pyarrow) ではファイル全体を開けなくなるため、この設定はデフォルトで無効になっています。Ring などのその他の geo 関連型は、GeoParquet メタデータを付与せず、ネイティブな内部表現のまま書き込まれます。この動作は output_format_parquet_geometadata を 0 に設定することで完全に無効化できます。この場合、サポートされている 幾何データ型であってもネイティブな内部表現 (Point は Tuple(Float64, Float64)、LineString は Array(Point)、Polygon は Array(Array(Point)) など) を使って書き込まれ、GeoParquet メタデータも出力されません。 ジオメトリカラムはスキーマのルートに置くか、Tuple (struct) の内側にネストする必要があります。Array や Map の内側にネストすることはサポートされていません。また、geo カラムに対する Nullable もサポートされていません。

使用例

データの挿入

football.parquet という名前の、次のデータを含む Parquet ファイルを使用します。
データを挿入します:

データの読み取り

Parquetフォーマットを使用してデータを読み取ります。
Parquet はバイナリフォーマットのため、端末上で人が読める形式では表示されません。Parquet ファイルを出力するには、INTO OUTFILE を使用します。
Hadoop とデータをやり取りするには、HDFS テーブルエンジン を使用できます。

フォーマット設定