> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Parquet フォーマットに関するドキュメント
# Parquet
| 入力 | 出力 | エイリアス |
| -- | -- | ----- |
| ✔ | ✔ | |
## 説明
[Apache Parquet](https://parquet.apache.org/) は、Hadoop エコシステムで広く使われている列指向のストレージフォーマットです。ClickHouse は、このフォーマットの読み取りと書き込みをサポートしています。
## データ型の対応
以下の表は、Parquet のデータ型が ClickHouse の[データ型](/docs/ja/reference/data-types/index)にどのように対応しているかを示しています。
| Parquet 型 (logical, converted, or physical) | ClickHouse データ型 |
| ------------------------------------------- | ---------------------------------------------------------------------------------- |
| `BOOLEAN` | [Bool](/docs/ja/reference/data-types/boolean) |
| `UINT_8` | [UInt8](/docs/ja/reference/data-types/int-uint) |
| `INT_8` | [Int8](/docs/ja/reference/data-types/int-uint) |
| `UINT_16` | [UInt16](/docs/ja/reference/data-types/int-uint) |
| `INT_16` | [Int16](/docs/ja/reference/data-types/int-uint)/[Enum16](/docs/ja/reference/data-types/enum) |
| `UINT_32` | [UInt32](/docs/ja/reference/data-types/int-uint) |
| `INT_32` | [Int32](/docs/ja/reference/data-types/int-uint) |
| `UINT_64` | [UInt64](/docs/ja/reference/data-types/int-uint) |
| `INT_64` | [Int64](/docs/ja/reference/data-types/int-uint) |
| `DATE` | [Date32](/docs/ja/reference/data-types/date) |
| `TIMESTAMP`, `TIME` | [DateTime64](/docs/ja/reference/data-types/datetime64) |
| `FLOAT` | [Float32](/docs/ja/reference/data-types/float) |
| `DOUBLE` | [Float64](/docs/ja/reference/data-types/float) |
| `INT96` | [DateTime64(9, 'UTC')](/docs/ja/reference/data-types/datetime64) |
| `BYTE_ARRAY`, `UTF8`, `ENUM`, `BSON` | [String](/docs/ja/reference/data-types/string) |
| `JSON` | [JSON](/docs/ja/reference/data-types/newjson) |
| `FIXED_LEN_BYTE_ARRAY` | [FixedString](/docs/ja/reference/data-types/fixedstring) |
| `DECIMAL` | [Decimal](/docs/ja/reference/data-types/decimal) |
| `LIST` | [Array](/docs/ja/reference/data-types/array) |
| `MAP` | [Map](/docs/ja/reference/data-types/map) |
| struct | [Tuple](/docs/ja/reference/data-types/tuple) |
| `FLOAT16` | [Float32](/docs/ja/reference/data-types/float) |
| `UUID` | [FixedString(16)](/docs/ja/reference/data-types/fixedstring) |
| `INTERVAL` | [FixedString(12)](/docs/ja/reference/data-types/fixedstring) |
| `Point` (GeoParquet) | [Point](/docs/ja/reference/data-types/geo#point) |
| `LineString` (GeoParquet) | [LineString](/docs/ja/reference/data-types/geo#linestring) |
| `Polygon` (GeoParquet) | [Polygon](/docs/ja/reference/data-types/geo#polygon) |
| `MultiLineString` (GeoParquet) | [MultiLineString](/docs/ja/reference/data-types/geo#multilinestring) |
| `MultiPolygon` (GeoParquet) | [MultiPolygon](/docs/ja/reference/data-types/geo#multipolygon) |
| mixed/unknown geometry (GeoParquet) | [Geometry](/docs/ja/reference/data-types/geo#geometry) |
Parquet ファイルへの書き込み時には、対応する Parquet 型がないデータ型は、利用可能な最も近い型に変換されます。
| ClickHouse データ型 | Parquet 型 |
| ------------------------------------------------------------------ | --------------------------------------------------- |
| [IPv4](/docs/ja/reference/data-types/ipv4) | `UINT_32` |
| [IPv6](/docs/ja/reference/data-types/ipv6) | `FIXED_LEN_BYTE_ARRAY` (16 bytes) |
| [Date](/docs/ja/reference/data-types/date) (16 bits) | `DATE` (32 bits) |
| [DateTime](/docs/ja/reference/data-types/datetime) (32 bits, seconds) | `TIMESTAMP` (64 bits, milliseconds) |
| [Int128/UInt128/Int256/UInt256](/docs/ja/reference/data-types/int-uint) | `FIXED_LEN_BYTE_ARRAY` (16/32 bytes, little-endian) |
| [Point](/docs/ja/reference/data-types/geo#point) | `BYTE_ARRAY` (WKB) + GeoParquet メタデータ |
| [LineString](/docs/ja/reference/data-types/geo#linestring) | `BYTE_ARRAY` (WKB) + GeoParquet メタデータ |
| [Polygon](/docs/ja/reference/data-types/geo#polygon) | `BYTE_ARRAY` (WKB) + GeoParquet メタデータ |
| [MultiLineString](/docs/ja/reference/data-types/geo#multilinestring) | `BYTE_ARRAY` (WKB) + GeoParquet メタデータ |
| [MultiPolygon](/docs/ja/reference/data-types/geo#multipolygon) | `BYTE_ARRAY` (WKB) + GeoParquet メタデータ |
Array はネストでき、引数として `Nullable` 型の値を取ることもできます。`Tuple` 型と `Map` 型もネストできます。
ClickHouse table のカラムのデータ型は、挿入される Parquet data の対応するフィールドと異なる場合があります。データを挿入する際、ClickHouse は上の表に従ってデータ型を解釈し、その後、データを ClickHouse table のカラムに設定されたデータ型に[キャスト](/docs/ja/reference/functions/regular-functions/type-conversion-functions#CAST)します。たとえば、`UINT_32` の Parquet カラムは [IPv4](/docs/ja/reference/data-types/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 における年、月、日、時、分、秒、および秒未満の各フィールドを持つ時刻) で、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 file でエンコードされた時間間隔の生のバイナリ表現を持つ `FixedString(12)` として読み取られます。
## Geo types (GeoParquet)
ClickHouse は、[GeoParquet](https://geoparquet.org/) 仕様に準拠した ジオメトリカラム の読み書きをサポートしています。ジオメトリカラム は、[WKB](https://libgeos.org/specifications/wkb/) (読み取り時は WKT) でエンコードされた `BYTE_ARRAY` ペイロードとして保存され、ファイルレベルの Parquet メタデータには、各 ジオメトリカラム のエンコーディング、ジオメトリ型、CRS を記述する JSON の `geo` キーが含まれます。
### 読み取り時の挙動
読み取り時には、ジオメトリカラム は対応する ClickHouse の[Geo data types](/docs/ja/reference/data-types/geo)にマッピングされます。
* `Point`、`LineString`、`Polygon`、`MultiLineString`、または `MultiPolygon` として宣言されたカラムは、対応する ClickHouse の Geo 型として読み取られます。
* 複数の geometry types を持つカラム、または geometry type が不明なカラムは、サポートされているすべての Geo 型に対する `Variant` である [`Geometry`](/docs/ja/reference/data-types/geo#geometry) 型として読み取られます。
* 要求されたカラム型が `String` の場合、GeoParquet のメタデータは無視され、エンコード済みの生のジオメトリ payload がそのまま返されます。返されるのは、GeoParquet カラムで宣言されているエンコードに応じた WKB または WKT のバイト列です。これは、設定 [`input_format_parquet_allow_geoparquet_parser`](/docs/ja/reference/settings/formats#input_format_parquet_allow_geoparquet_parser) が `0` に設定されている場合も同様です。
### 書き込み動作
書き込み時には、型が `Point`、`LineString`、`Polygon`、`MultiLineString`、または `MultiPolygon` のトップレベルのカラムは `BYTE_ARRAY` (WKB) としてエンコードされ、適切な `geo` JSON メタデータが Parquet ファイルのフッターに追加されます。トップレベルの [`Geometry`](/docs/ja/reference/data-types/geo#geometry) `Variant` も WKB の `BYTE_ARRAY` payload としてエンコードされます (その下位の値は WKB に変換され、`Nullable(String)` カラムとして保存されます) が、これについては `geo` メタデータが出力されないため、読み取り時に結果は GeoParquet の geometry カラムとして認識されません。[`Ring`](/docs/ja/reference/data-types/geo#ring) などのその他の geo 関連型は、GeoParquet メタデータを付与せず、ネイティブな内部表現のまま書き込まれます。この動作は [`output_format_parquet_geometadata`](/docs/ja/reference/settings/formats#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 ファイルを使用します。
```text theme={null}
┌───────date─┬─season─┬─home_team─────────────┬─away_team───────────┬─home_team_goals─┬─away_team_goals─┐
1. │ 2022-04-30 │ 2021 │ Sutton United │ Bradford City │ 1 │ 4 │
2. │ 2022-04-30 │ 2021 │ Swindon Town │ Barrow │ 2 │ 1 │
3. │ 2022-04-30 │ 2021 │ Tranmere Rovers │ Oldham Athletic │ 2 │ 0 │
4. │ 2022-05-02 │ 2021 │ Port Vale │ Newport County │ 1 │ 2 │
5. │ 2022-05-02 │ 2021 │ Salford City │ Mansfield Town │ 2 │ 2 │
6. │ 2022-05-07 │ 2021 │ Barrow │ Northampton Town │ 1 │ 3 │
7. │ 2022-05-07 │ 2021 │ Bradford City │ Carlisle United │ 2 │ 0 │
8. │ 2022-05-07 │ 2021 │ Bristol Rovers │ Scunthorpe United │ 7 │ 0 │
9. │ 2022-05-07 │ 2021 │ Exeter City │ Port Vale │ 0 │ 1 │
10. │ 2022-05-07 │ 2021 │ Harrogate Town A.F.C. │ Sutton United │ 0 │ 2 │
11. │ 2022-05-07 │ 2021 │ Hartlepool United │ Colchester United │ 0 │ 2 │
12. │ 2022-05-07 │ 2021 │ Leyton Orient │ Tranmere Rovers │ 0 │ 1 │
13. │ 2022-05-07 │ 2021 │ Mansfield Town │ Forest Green Rovers │ 2 │ 2 │
14. │ 2022-05-07 │ 2021 │ Newport County │ Rochdale │ 0 │ 2 │
15. │ 2022-05-07 │ 2021 │ Oldham Athletic │ Crawley Town │ 3 │ 3 │
16. │ 2022-05-07 │ 2021 │ Stevenage Borough │ Salford City │ 4 │ 2 │
17. │ 2022-05-07 │ 2021 │ Walsall │ Swindon Town │ 0 │ 3 │
└────────────┴────────┴───────────────────────┴─────────────────────┴─────────────────┴─────────────────┘
```
データを挿入します:
```sql theme={null}
INSERT INTO football FROM INFILE 'football.parquet' FORMAT Parquet;
```
### データの読み取り
`Parquet`フォーマットを使用してデータを読み取ります。
```sql theme={null}
SELECT *
FROM football
INTO OUTFILE 'football.parquet'
FORMAT Parquet
```
Parquet はバイナリフォーマットのため、端末上で人が読める形式では表示されません。Parquet ファイルを出力するには、`INTO OUTFILE` を使用します。
Hadoop とデータをやり取りするには、[`HDFS テーブルエンジン`](/docs/ja/reference/engines/table-engines/integrations/hdfs) を使用できます。
## フォーマット設定
| 設定 | 説明 | デフォルト |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input_format_parquet_case_insensitive_column_matching` | Parquet のカラムと CH カラムの照合時に、大文字・小文字を区別しません。 | `0` |
| `input_format_parquet_preserve_order` | Parquet ファイルの読み取り時に、行の並び順を変更しないようにします。通常は大幅に遅くなります。 | `0` |
| `input_format_parquet_filter_push_down` | Parquet ファイルの読み取り時に、WHERE/PREWHERE 式と Parquet メタデータ内の最小値/最大値統計に基づいて、行グループ全体をスキップします。 | `1` |
| `input_format_parquet_bloom_filter_push_down` | Parquet ファイルの読み取り時に、WHERE 式と Parquet メタデータ内の bloom filter に基づいて、行グループ全体をスキップします。 | `0` |
| `input_format_parquet_allow_missing_columns` | Parquet 入力フォーマットの読み取り時に、欠落しているカラムを許可します。 | `1` |
| `input_format_parquet_local_file_min_bytes_for_seek` | Parquet 入力フォーマットで、読み飛ばしながら読み込む代わりに seek を行うために、ローカル読み取り (ファイル) で必要となる最小バイト数 | `8192` |
| `input_format_parquet_enable_row_group_prefetch` | Parquet のパース中に行グループの prefetch を有効にします。現在、prefetch できるのはシングルスレッドのパースのみです。 | `1` |
| `input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference` | Parquet フォーマットのスキーマ推論時に、サポートされていない型のカラムをスキップします。 | `0` |
| `input_format_parquet_max_block_size` | Parquet リーダーの最大ブロックサイズ。 | `65409` |
| `input_format_parquet_prefer_block_bytes` | Parquet リーダーが出力する平均ブロックバイト数 | `16744704` |
| `input_format_parquet_enable_json_parsing` | Parquet ファイルの読み取り時に、JSON カラムを ClickHouse JSON Column としてパースします。 | `1` |
| `input_format_parquet_allow_geoparquet_parser` | Parquet ファイルの読み取り時に、GeoParquet `geo` メタデータを認識し、ジオメトリカラムを (カラムで宣言されたエンコーディングに応じて WKB または WKT から) ClickHouse の geo データ型としてデコードします。`0` の場合、ジオメトリカラムは生の物理表現 (`String`) のまま公開されます。 | `1` |
| `output_format_parquet_row_group_size` | 目標の行グループサイズ (行数) 。 | `1000000` |
| `output_format_parquet_row_group_size_bytes` | 圧縮前の目標行グループサイズ (バイト単位) 。 | `536870912` |
| `output_format_parquet_string_as_string` | String カラムでは、Binary の代わりに Parquet String 型を使用します。 | `1` |
| `output_format_parquet_fixed_string_as_fixed_byte_array` | FixedString カラムでは、Binary の代わりに Parquet FIXED\_LEN\_BYTE\_ARRAY 型を使用します。 | `1` |
| `output_format_parquet_compression_method` | Parquet 出力フォーマットの圧縮方式。サポートされる codec: snappy, lz4, brotli, zstd, gzip, none (非圧縮) | `zstd` |
| `output_format_parquet_parallel_encoding` | 複数スレッドで Parquet エンコードを実行します。 | `1` |
| `output_format_parquet_data_page_size` | 圧縮前の目標ページサイズ (バイト単位) 。 | `1048576` |
| `output_format_parquet_batch_size` | この行数ごとにページサイズを確認します。平均値サイズが数 KB を超えるカラムがある場合は、値を小さくすることを検討してください。 | `1024` |
| `output_format_parquet_write_page_index` | Parquet ファイルにページ索引を書き込めるようにします。 | `1` |
| `output_format_parquet_geometadata` | GeoParquet の `geo` メタデータを Parquet ファイルのフッターに書き込み、最上位レベルの ClickHouse geo カラム ([`Point`](/docs/ja/reference/data-types/geo#point), [`LineString`](/docs/ja/reference/data-types/geo#linestring), [`Polygon`](/docs/ja/reference/data-types/geo#polygon), [`MultiLineString`](/docs/ja/reference/data-types/geo#multilinestring), [`MultiPolygon`](/docs/ja/reference/data-types/geo#multipolygon)) を WKB としてエンコードします。`0` の場合、これらのカラムはネイティブの内部表現 (例: `Point` は `Tuple(Float64, Float64)`) を使用して書き込まれ、GeoParquet メタデータは出力されません。 | `1` |
| `input_format_parquet_import_nested` | 廃止された設定です。何も行いません。 | `0` |
| `input_format_parquet_local_time_as_utc` | true | isAdjustedToUTC=false の Parquet timestamp に対して、スキーマ推論で使用する data type を決定します。true の場合: DateTime64(..., 'UTC')、false の場合: DateTime64(...)。ClickHouse にはローカルの wall-clock time 用の data type がないため、どちらの動作も完全に正しいわけではありません。直感に反しますが、おそらく 'true' のほうがまだ誤りの少ない選択肢です。これは、'UTC' timestamp を String としてフォーマットすると、正しいローカル時刻の表現が生成されるためです。 |