説明
データ型の対応
Parquet ファイルへの書き込み時には、対応する Parquet 型がないデータ型は、利用可能な最も近い型に変換されます。
Array はネストでき、引数として
Nullable 型の値を取ることもできます。Tuple 型と Map 型もネストできます。
ワイド整数
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 型がありません。これらは次のように読み取られます。
TIME(時刻) は timestamp として読み取られます。例:10:23:13.000は1970-01-01 10:23:13.000になります。isAdjustedToUTC=falseのTIMESTAMP/TIMEはローカルの wall-clock time (どの time zone がローカルと見なされるかにかかわらず、ローカル timezone における年、月、日、時、分、秒、および秒未満の各フィールドを持つ時刻) で、SQLTIMESTAMP 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 file でエンコードされた時間間隔の生のバイナリ表現を持つFixedString(12)として読み取られます。
Geo types (GeoParquet)
BYTE_ARRAY ペイロードとして保存され、ファイルレベルの Parquet メタデータには、各 ジオメトリカラム のエンコーディング、ジオメトリ型、CRS を記述する JSON の geo キーが含まれます。
読み取り時の挙動
Point、MultiPoint、LineString、Polygon、MultiLineString、またはMultiPolygonとして宣言されたカラムは、対応する ClickHouse の Geo 型として読み取られます。- 複数の geometry types を持つカラム、または geometry type が不明なカラムは、サポートされているすべての Geo 型に対する
VariantであるGeometry型として読み取られます。 - 要求されたカラム型が
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 メタデータが出力されないため、読み取り時に結果は GeoParquet のジオメトリカラムとして認識されません。Ring などのその他の geo 関連型は、GeoParquet メタデータを付与せず、ネイティブな内部表現のまま書き込まれます。この動作は output_format_parquet_geometadata を 0 に設定することで完全に無効化できます。この場合、サポートされている geo 型であってもネイティブな内部表現 (Point は Tuple(Float64, Float64)、LineString は Array(Point)、Polygon は Array(Array(Point)) など) を使って書き込まれ、GeoParquet メタデータも出力されません。
ジオメトリカラムはスキーマのルートに置くか、Tuple (struct) の内側にネストする必要があります。Array や Map の内側にネストすることはサポートされていません。また、geo カラムに対する Nullable もサポートされていません。
使用例
データの挿入
football.parquet という名前の、次のデータを含む Parquet ファイルを使用します。
データの読み取り
Parquetフォーマットを使用してデータを読み取ります。
HDFS テーブルエンジン を使用できます。