> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/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 [数据类型](/zh/reference/data-types/index) 之间的对应关系。
| Parquet 类型 (逻辑类型、转换类型或物理类型) | ClickHouse 数据类型 |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| `BOOLEAN` | [Bool](/zh/reference/data-types/boolean) |
| `UINT_8` | [UInt8](/zh/reference/data-types/int-uint) |
| `INT_8` | [Int8](/zh/reference/data-types/int-uint) |
| `UINT_16` | [UInt16](/zh/reference/data-types/int-uint) |
| `INT_16` | [Int16](/zh/reference/data-types/int-uint)/[Enum16](/zh/reference/data-types/enum) |
| `UINT_32` | [UInt32](/zh/reference/data-types/int-uint) |
| `INT_32` | [Int32](/zh/reference/data-types/int-uint) |
| `UINT_64` | [UInt64](/zh/reference/data-types/int-uint) |
| `INT_64` | [Int64](/zh/reference/data-types/int-uint) |
| `DATE` | [Date32](/zh/reference/data-types/date) |
| `TIMESTAMP`, `TIME` | [DateTime64](/zh/reference/data-types/datetime64) |
| `FLOAT` | [Float32](/zh/reference/data-types/float) |
| `DOUBLE` | [Float64](/zh/reference/data-types/float) |
| `INT96` | [DateTime64(9, 'UTC')](/zh/reference/data-types/datetime64) |
| `BYTE_ARRAY`, `UTF8`, `ENUM`, `BSON` | [String](/zh/reference/data-types/string) |
| `JSON` | [JSON](/zh/reference/data-types/newjson) |
| `FIXED_LEN_BYTE_ARRAY` | [FixedString](/zh/reference/data-types/fixedstring) |
| `DECIMAL` | [Decimal](/zh/reference/data-types/decimal) |
| `LIST` | [Array](/zh/reference/data-types/array) |
| `MAP` | [Map](/zh/reference/data-types/map) |
| struct | [Tuple](/zh/reference/data-types/tuple) |
| `FLOAT16` | [Float32](/zh/reference/data-types/float) |
| `UUID` | [FixedString(16)](/zh/reference/data-types/fixedstring) |
| `INTERVAL` | [FixedString(12)](/zh/reference/data-types/fixedstring) |
| `Point` (GeoParquet) | [Point](/zh/reference/data-types/geo#point) |
| `LineString` (GeoParquet) | [LineString](/zh/reference/data-types/geo#linestring) |
| `Polygon` (GeoParquet) | [Polygon](/zh/reference/data-types/geo#polygon) |
| `MultiLineString` (GeoParquet) | [MultiLineString](/zh/reference/data-types/geo#multilinestring) |
| `MultiPolygon` (GeoParquet) | [MultiPolygon](/zh/reference/data-types/geo#multipolygon) |
| 混合/未知几何体 (GeoParquet) | [Geometry](/zh/reference/data-types/geo#geometry) |
写入 Parquet 文件时，没有对应 Parquet 类型的数据类型会被转换为最接近的可用类型：
| ClickHouse 数据类型 | Parquet 类型 |
| ------------------------------------------------------------------ | ------------------------------------- |
| [IPv4](/zh/reference/data-types/ipv4) | `UINT_32` |
| [IPv6](/zh/reference/data-types/ipv6) | `FIXED_LEN_BYTE_ARRAY` (16 字节) |
| [Date](/zh/reference/data-types/date) (16 位) | `DATE` (32 位) |
| [DateTime](/zh/reference/data-types/datetime) (32 位，秒) | `TIMESTAMP` (64 位，毫秒) |
| [Int128/UInt128/Int256/UInt256](/zh/reference/data-types/int-uint) | `FIXED_LEN_BYTE_ARRAY` (16/32 字节，小端序) |
| [Point](/zh/reference/data-types/geo#point) | `BYTE_ARRAY` (WKB) + GeoParquet 元数据 |
| [LineString](/zh/reference/data-types/geo#linestring) | `BYTE_ARRAY` (WKB) + GeoParquet 元数据 |
| [Polygon](/zh/reference/data-types/geo#polygon) | `BYTE_ARRAY` (WKB) + GeoParquet 元数据 |
| [MultiLineString](/zh/reference/data-types/geo#multilinestring) | `BYTE_ARRAY` (WKB) + GeoParquet 元数据 |
| [MultiPolygon](/zh/reference/data-types/geo#multipolygon) | `BYTE_ARRAY` (WKB) + GeoParquet 元数据 |
Array 可以嵌套，其参数值也可以是 `Nullable` 类型。`Tuple` 和 `Map` 类型同样可以嵌套。
ClickHouse 表列的数据类型可以与插入的 Parquet 数据中对应字段的类型不同。插入数据时，ClickHouse 会先根据上表解释数据类型，然后将数据 [转换](/zh/reference/functions/regular-functions/type-conversion-functions#CAST) 为 ClickHouse 表列所设置的数据类型。例如，`UINT_32` Parquet 列可以读入 [IPv4](/zh/reference/data-types/ipv4) ClickHouse 列中。
对于某些 Parquet 类型，并没有与之非常接近的 ClickHouse 类型。我们按如下方式读取它们：
* `TIME` (一天中的时间) 会被读取为时间戳。例如，`10:23:13.000` 会变成 `1970-01-01 10:23:13.000`。
* 设置了 `isAdjustedToUTC=false` 的 `TIMESTAMP`/`TIME` 表示本地挂钟时间 (即本地时区中的年、月、日、时、分、秒和亚秒字段，不论具体将哪个 timezone 视为本地) ，与 SQL `TIMESTAMP WITHOUT TIME ZONE` 相同。但 ClickHouse 读取时会改为将其视作 UTC 时间戳。例如，`2025-09-29 18:42:13.000` (表示本地挂钟上的读数) 会变成 `2025-09-29 18:42:13.000` (`DateTime64(3, 'UTC')`，表示一个时间点) 。如果将其转换为 String，会显示正确的年、月、日、时、分、秒和亚秒，此时可以将其理解为某个本地时区中的时间，而不是 UTC。违反直觉的是，把类型从 `DateTime64(3, 'UTC')` 改为 `DateTime64(3)` 也没有帮助，因为这两种类型表示的都是时间点，而不是时钟读数；但 `DateTime64(3)` 还会错误地使用本地时区进行格式化。
* `INTERVAL` 当前会被读取为 `FixedString(12)`，内容是时间间隔的原始二进制表示，编码方式与 Parquet 文件中一致。
## Geo 类型 (GeoParquet)
ClickHouse 支持按照 [GeoParquet](https://geoparquet.org/) 规范读写几何列。几何列以 [WKB](https://libgeos.org/specifications/wkb/) 编码的 `BYTE_ARRAY` 载荷形式存储 (读取时也支持 WKT) ，并在文件级 Parquet 元数据中通过一个 JSON `geo` 键描述每个几何列的编码、几何类型和 CRS。
### 读取行为
读取时，几何列会映射为对应的 ClickHouse [geo data types](/zh/reference/data-types/geo)：
* 声明为 `Point`、`LineString`、`Polygon`、`MultiLineString` 或 `MultiPolygon` 的列，会读取为对应的 ClickHouse geo type。
* 包含多种或未知几何类型的列，会读取为 [`Geometry`](/zh/reference/data-types/geo#geometry) 类型，它是一个涵盖所有受支持 geo types 的 `Variant`。
* 如果请求的列类型为 `String`，则会忽略 GeoParquet 元数据，并按原样返回原始编码的几何载荷——WKB 或 WKT 字节，具体取决于 GeoParquet 列声明的编码类型。如果设置 [`input_format_parquet_allow_geoparquet_parser`](/zh/reference/settings/formats#input_format_parquet_allow_geoparquet_parser) 为 `0`，也是如此。
### 写入行为
写入时，类型为 `Point`、`LineString`、`Polygon`、`MultiLineString` 或 `MultiPolygon` 的顶层列会编码为 `BYTE_ARRAY` (WKB) ，并将相应的 `geo` JSON 元数据 追加到 Parquet 文件页脚。顶层的 [`Geometry`](/zh/reference/data-types/geo#geometry) `Variant` 也会被编码为 WKB `BYTE_ARRAY` 载荷 (其子值会转换为 WKB，并存储为 `Nullable(String)` 列) ，但不会为其输出 `geo` 元数据，因此读取时，结果不会被识别为 GeoParquet 几何列。其他与 geo 相关的类型 (例如 [`Ring`](/zh/reference/data-types/geo#ring)) 则会使用其原生底层表示写入，不附带任何 GeoParquet 元数据。将 [`output_format_parquet_geometadata`](/zh/reference/settings/formats#output_format_parquet_geometadata) 设置为 `0` 可完全禁用此行为；在这种情况下，即使是受支持的 geo 类型，也会使用其原生底层表示写入 (`Point` 写为 `Tuple(Float64, Float64)`，`LineString` 写为 `Array(Point)`，`Polygon` 写为 `Array(Array(Point))`，等等) ，并且不会输出任何 GeoParquet 元数据。
几何列必须位于 schema 根级，或嵌套在 `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 是一种二进制格式，无法在终端中以人类可读的形式显示。请使用 `INTO OUTFILE` 输出 Parquet 文件。
如需与 Hadoop 交换数据，可以使用 [`HDFS 表引擎`](/zh/reference/engines/table-engines/integrations/hdfs)。
## 格式设置
| 设置 | 说明 | 默认值 |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input_format_parquet_case_insensitive_column_matching` | 匹配 Parquet 列与 CH columns 时忽略大小写。 | `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 输入格式中，本地读取 (文件) 执行寻道而不是通过跳过读取时所需的最小字节数。 | `8192` |
| `input_format_parquet_enable_row_group_prefetch` | 在解析 Parquet 期间启用行组预取。目前只有单线程解析支持预取。 | `1` |
| `input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference` | 对 Parquet 格式进行 schema inference 时，跳过类型不受支持的列。 | `0` |
| `input_format_parquet_max_block_size` | parquet reader 的最大块大小。 | `65409` |
| `input_format_parquet_prefer_block_bytes` | parquet reader 输出的平均块字节数。 | `16744704` |
| `input_format_parquet_enable_json_parsing` | 读取 Parquet 文件时，将 JSON columns 解析为 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 列使用 Parquet String 类型，而不是 Binary。 | `1` |
| `output_format_parquet_fixed_string_as_fixed_byte_array` | 对 FixedString 列使用 Parquet FIXED\_LEN\_BYTE\_ARRAY 类型，而不是 Binary。 | `1` |
| `output_format_parquet_compression_method` | Parquet output format 的压缩方法。支持的 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`](/zh/reference/data-types/geo#point)、[`LineString`](/zh/reference/data-types/geo#linestring)、[`Polygon`](/zh/reference/data-types/geo#polygon)、[`MultiLineString`](/zh/reference/data-types/geo#multilinestring)、[`MultiPolygon`](/zh/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 时间戳进行 schema inference 时使用的数据类型。如果为 true：`DateTime64(..., 'UTC')`；如果为 false：`DateTime64(...)`。这两种行为都不完全正确，因为 ClickHouse 没有表示本地挂钟时间的数据类型。反直觉的是，`true` 可能反而是相对没那么不正确的选项，因为将 `'UTC'` 时间戳格式化为 String 时，会得到正确的本地时间表示。 |