説明
データ型の対応
Parquet ファイルへの書き込み時には、対応する Parquet 型がないデータ型は、利用可能な最も近い型に変換されます。
Array はネストでき、引数として
Nullable 型の値を取ることもできます。Tuple 型と Map 型もネストできます。
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、LineString、Polygon、MultiLineString、またはMultiPolygonとして宣言されたカラムは、対応する ClickHouse の Geo 型として読み取られます。- 複数の geometry types を持つカラム、または geometry type が不明なカラムは、サポートされているすべての Geo 型に対する
VariantであるGeometry型として読み取られます。 - 要求されたカラム型が
Stringの場合、GeoParquet のメタデータは無視され、エンコード済みの生のジオメトリ payload がそのまま返されます。返されるのは、GeoParquet カラムで宣言されているエンコードに応じた WKB または WKT のバイト列です。これは、設定input_format_parquet_allow_geoparquet_parserが0に設定されている場合も同様です。
書き込み動作
Point、LineString、Polygon、MultiLineString、または MultiPolygon のトップレベルのカラムは BYTE_ARRAY (WKB) としてエンコードされ、適切な geo JSON メタデータが Parquet ファイルのフッターに追加されます。トップレベルの Geometry Variant も WKB の BYTE_ARRAY payload としてエンコードされます (その下位の値は WKB に変換され、Nullable(String) カラムとして保存されます) が、これについては geo メタデータが出力されないため、読み取り時に結果は GeoParquet の geometry カラムとして認識されません。Ring などのその他の geo 関連型は、GeoParquet メタデータを付与せず、ネイティブな内部表現のまま書き込まれます。この動作は output_format_parquet_geometadata を 0 に設定することで完全に無効化できます。この場合、サポートされている geo 型であってもネイティブな内部表現 (Point は Tuple(Float64, Float64)、LineString は Array(Point)、Polygon は Array(Array(Point)) など) を使って書き込まれ、GeoParquet メタデータも出力されません。
Geometry カラムはスキーマのルートに置くか、Tuple (struct) の内側にネストする必要があります。Array や Map の内側にネストすることはサポートされていません。また、geo カラムに対する Nullable もサポートされていません。
使用例
データの挿入
football.parquet という名前の、次のデータを含む Parquet ファイルを使用します。
データの読み取り
Parquetフォーマットを使用してデータを読み取ります。
HDFS テーブルエンジン を使用できます。