설명
데이터 타입 매핑
Parquet 파일을 쓸 때 대응되는 Parquet 타입이 없는 데이터 타입은 가장 가까운 사용 가능한 타입으로 변환됩니다.
배열은 중첩될 수 있으며, 인수로
Nullable 타입 값을 가질 수 있습니다. Tuple 및 Map 타입도 중첩될 수 있습니다.
와이드 정수
Int128, UInt128, Int256, UInt256을 리틀 엔디언 순서의 주석 없는 FIXED_LEN_BYTE_ARRAY(16/32) 값으로 기록합니다. 이전 ClickHouse 버전에서 파일을 읽을 수 있도록 이 레거시 표현은 기본값으로 유지됩니다.
대신 표준 Parquet DECIMAL 표현을 사용하려면 output_format_parquet_wide_integer_as_decimal = 1을 설정합니다.
Decimal 표현은 표준 Parquet 컬럼 청크 통계와 페이지 인덱스에 숫자 정렬을 제공하므로, ClickHouse에서 행 그룹 및 페이지 최소/최대 가지치기를 사용할 수 있습니다. ClickHouse는 두 인코딩을 모두 읽습니다. Decimal 정밀도 39의 경우 스키마 추론은
Decimal256을 기반으로 하는 Decimal(39, 0)을 반환합니다. 와이드 정수 타입을 복원하려면 명시적인 Int128 또는 UInt128 구조를 지정하십시오. Decimal 정밀도 77 또는 78은 ClickHouse Decimal256의 범위를 초과하므로, 해당 파일을 읽으려면 명시적으로 호환되는 Int256 또는 UInt256 구조가 필요합니다. 명시적인 와이드 정수 구조를 사용하면 ClickHouse는 유효한 모든 너비의 BYTE_ARRAY 또는 FIXED_LEN_BYTE_ARRAY로 저장된 표준 Decimal 값을 허용하고, 부호 확장을 제거한 후 모든 값을 범위 검사합니다.
일부 Parquet 클라이언트는 Decimal 정밀도를 최대 38까지만 지원하며, Arrow의 고수준 Decimal 타입은 정밀도를 최대 76까지만 지원합니다. 이러한 클라이언트는 스키마와 33바이트 물리 너비가 Parquet를 준수하더라도 정밀도 77/78 표현을 거부할 수 있습니다. 이전 ClickHouse 버전 또는 Decimal 제한이 더 작은 클라이언트에서 파일을 읽어야 한다면 이 설정을 비활성화된 상태로 유지하십시오.
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입니다(어떤 시간대를 로컬로 간주하는지와 관계없이, 로컬 시간대 기준의 연, 월, 일, 시, 분, 초 및 소수 초 필드). 이는 SQLTIMESTAMP 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)
BYTE_ARRAY 페이로드로 저장되며(읽을 때는 WKT), 파일 수준 Parquet 메타데이터의 JSON geo 키에는 각 지오메트리 컬럼의 인코딩, 지오메트리 타입, CRS가 설명되어 있습니다.
읽기 동작
Point,MultiPoint,LineString,Polygon,MultiLineString또는MultiPolygon으로 선언된 컬럼은 이에 대응하는 ClickHouse geo 타입으로 읽어들입니다.- 여러 지오메트리 타입을 포함하거나 타입을 알 수 없는 컬럼은 지원되는 모든 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 파일 footer에 추가됩니다. 최상위 Geometry Variant도 WKB BYTE_ARRAY 페이로드로 인코딩되지만(하위 값은 WKB로 변환되어 Nullable(String) 컬럼에 저장됨), 이에 대해서는 geo 메타데이터가 출력되지 않으므로 읽을 때 GeoParquet 지오메트리 컬럼으로 인식되지 않습니다. Ring과 같은 다른 geo 관련 타입은 GeoParquet 메타데이터 없이 해당 네이티브 내부 표현으로 기록됩니다. 이 동작은 output_format_parquet_geometadata를 0으로 설정해 완전히 비활성화할 수 있으며, 이 경우 지원되는 geo 타입도 네이티브 내부 표현(Point는 Tuple(Float64, Float64), LineString은 배열(Point), Polygon은 배열(배열(Point)) 등)으로 기록되고 GeoParquet 메타데이터도 출력되지 않습니다.
지오메트리 컬럼은 스키마 루트에 있거나 Tuple(struct) 내부에 중첩되어 있어야 하며, 배열 또는 Map 내부에 중첩하는 것은 지원되지 않습니다. geo 컬럼에는 Nullable도 지원되지 않습니다.
사용 예시
데이터 삽입
football.parquet라는 Parquet 파일을 사용합니다:
데이터 읽기
Parquet 포맷을 사용해 데이터를 읽습니다:
HDFS 테이블 엔진을 사용할 수 있습니다.