Parquet

Parquet 포맷 문서

입력	출력	별칭
✔	✔

​

설명

Apache Parquet은 Hadoop 생태계에서 널리 사용되는 열 지향 저장 포맷입니다. ClickHouse는 이 포맷의 읽기 및 쓰기를 지원합니다.

​

데이터 타입 매핑

아래 표는 Parquet 데이터 타입이 ClickHouse 데이터 타입과 어떻게 매핑되는지 보여줍니다.

Parquet 타입(논리, 변환 또는 물리)	ClickHouse 데이터 타입
BOOLEAN	Bool
UINT_8	UInt8
INT_8	Int8
UINT_16	UInt16
INT_16	Int16/Enum16
UINT_32	UInt32
INT_32	Int32
UINT_64	UInt64
INT_64	Int64
DATE	Date32
TIMESTAMP, TIME	DateTime64
FLOAT	Float32
DOUBLE	Float64
INT96	DateTime64(9, ‘UTC’)
BYTE_ARRAY, UTF8, ENUM, BSON	String
JSON	JSON
FIXED_LEN_BYTE_ARRAY	FixedString
DECIMAL	Decimal
LIST	Array
MAP	Map
struct	Tuple
FLOAT16	Float32
UUID	FixedString(16)
INTERVAL	FixedString(12)
Point (GeoParquet)	Point
LineString (GeoParquet)	LineString
Polygon (GeoParquet)	Polygon
MultiLineString (GeoParquet)	MultiLineString
MultiPolygon (GeoParquet)	MultiPolygon
혼합/알 수 없는 geometry (GeoParquet)	Geometry

Parquet 파일을 쓸 때 대응되는 Parquet 타입이 없는 데이터 타입은 가장 가까운 사용 가능한 타입으로 변환됩니다.

ClickHouse 데이터 타입	Parquet 타입
IPv4	UINT_32
IPv6	FIXED_LEN_BYTE_ARRAY (16 bytes)
Date (16 bits)	DATE (32 bits)
DateTime (32 bits, seconds)	TIMESTAMP (64 bits, milliseconds)
Int128/UInt128/Int256/UInt256	FIXED_LEN_BYTE_ARRAY (16/32 bytes, little-endian)
Point	BYTE_ARRAY (WKB) + GeoParquet metadata
LineString	BYTE_ARRAY (WKB) + GeoParquet metadata
Polygon	BYTE_ARRAY (WKB) + GeoParquet metadata
MultiLineString	BYTE_ARRAY (WKB) + GeoParquet metadata
MultiPolygon	BYTE_ARRAY (WKB) + GeoParquet metadata

배열은 중첩될 수 있으며, 인수로 Nullable 타입 값을 가질 수 있습니다. Tuple 및 Map 타입도 중첩될 수 있습니다.

ClickHouse 테이블 컬럼의 데이터 타입은 삽입된 Parquet 데이터의 해당 필드와 다를 수 있습니다. 데이터를 삽입할 때 ClickHouse는 먼저 위 표에 따라 데이터 타입을 해석한 다음, 데이터를 ClickHouse 테이블 컬럼에 설정된 데이터 타입으로 캐스팅합니다. 예를 들어 UINT_32 Parquet 컬럼은 IPv4 ClickHouse 컬럼으로 읽을 수 있습니다.

일부 Parquet 타입에는 밀접하게 대응되는 ClickHouse 타입이 없습니다. 이러한 타입은 다음과 같이 읽습니다.

• TIME(하루 중 시간)은 타임스탬프로 읽습니다. 예: 10:23:13.000은 1970-01-01 10:23:13.000이 됩니다.
• isAdjustedToUTC=false인 TIMESTAMP/TIME은 로컬 wall-clock time입니다(어떤 시간대를 로컬로 간주하는지와 관계없이, 로컬 시간대 기준의 연, 월, 일, 시, 분, 초 및 소수 초 필드). 이는 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은 현재 Parquet 파일에 인코딩된 시간 인터벌의 원시 바이너리 표현이 담긴 FixedString(12)로 읽습니다.

​

Geo 타입 (GeoParquet)

ClickHouse는 GeoParquet 사양에 따라 지오메트리 컬럼의 읽기 및 쓰기를 지원합니다. 지오메트리 컬럼은 WKB로 인코딩된 BYTE_ARRAY 페이로드로 저장되며(읽을 때는 WKT), 파일 수준 Parquet 메타데이터의 JSON geo 키에는 각 지오메트리 컬럼의 인코딩, 지오메트리 타입, CRS가 설명되어 있습니다.

​

읽기 동작

읽을 때 지오메트리 컬럼은 해당하는 ClickHouse geo 데이터 타입으로 매핑됩니다.

• Point, LineString, Polygon, MultiLineString 또는 MultiPolygon으로 선언된 컬럼은 이에 대응하는 ClickHouse geo 타입으로 읽어들입니다.
• 여러 지오메트리 타입을 포함하거나 타입을 알 수 없는 컬럼은 지원되는 모든 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 파일 footer에 추가됩니다. 최상위 Geometry Variant도 WKB BYTE_ARRAY payload로 인코딩되지만(하위 값은 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 파일을 사용합니다:

    ┌───────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 │
    └────────────┴────────┴───────────────────────┴─────────────────────┴─────────────────┴─────────────────┘

데이터를 삽입하세요:

INSERT INTO football FROM INFILE 'football.parquet' FORMAT Parquet;

​

데이터 읽기

다음과 같이 Parquet 포맷을 사용해 데이터를 읽습니다:

SELECT *
FROM football
INTO OUTFILE 'football.parquet'
FORMAT Parquet

Parquet은 터미널에 사람이 읽을 수 있는 형태로 표시되지 않는 바이너리 형식입니다. Parquet 파일로 출력하려면 INTO OUTFILE을 사용하십시오.

Hadoop과 데이터를 주고받으려면 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 파일을 읽을 때 Parquet 메타데이터의 WHERE/PREWHERE 표현식과 최소/최대 통계를 기반으로 전체 row group을 건너뜁니다.	1
input_format_parquet_bloom_filter_push_down	Parquet 파일을 읽을 때 Parquet 메타데이터의 WHERE 표현식과 블룸 필터를 기반으로 전체 row group을 건너뜁니다.	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 파싱 중 row group 프리페치를 활성화합니다. 현재는 단일 스레드 파싱에서만 프리페치를 사용할 수 있습니다.	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	목표 row group 크기(행 수 기준)입니다.	1000000
output_format_parquet_row_group_size_bytes	압축 전 기준 목표 row group 크기(바이트)입니다.	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 출력 형식의 압축 방식입니다. 지원되는 코덱: 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 파일 footer에 기록하고 최상위 수준의 ClickHouse geo 컬럼(Point, LineString, Polygon, MultiLineString, 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 타임스탬프에 대해 스키마 추론 시 사용할 데이터 타입을 결정합니다. true이면 DateTime64(…, ‘UTC’), false이면 DateTime64(…)를 사용합니다. ClickHouse에는 로컬 wall-clock time을 위한 데이터 타입이 없으므로 어느 쪽도 완전히 올바르지는 않습니다. 직관에 어긋날 수 있지만, 아마 ‘true’ 쪽이 덜 부정확합니다. ‘UTC’ 타임스탬프를 String으로 포맷하면 올바른 로컬 시간 표현이 생성되기 때문입니다.