메인 콘텐츠로 건너뛰기

설명

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

데이터 타입 매핑

아래 표는 Parquet 데이터 타입이 ClickHouse 데이터 타입과 어떻게 매핑되는지 보여줍니다. Parquet 파일을 쓸 때 대응되는 Parquet 타입이 없는 데이터 타입은 가장 가까운 사용 가능한 타입으로 변환됩니다. 배열은 중첩될 수 있으며, 인수로 Nullable 타입 값을 가질 수 있습니다. Tuple 및 Map 타입도 중첩될 수 있습니다.

와이드 정수

기본적으로 ClickHouse는 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 타입이 없습니다. 이러한 타입은 다음과 같이 읽습니다.
  • isAdjustedToUTC=false인 TIMESTAMP는 로컬 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)로 읽습니다。

Variant 타입

ClickHouse는 Spark 4.0 등에서 기록한 Parquet VARIANT 인코딩 컬럼을 Dynamic 타입으로 읽습니다. VARIANT 논리 타입(명세 버전 1)으로 주석이 지정된 그룹 컬럼은 variant로 인식됩니다. Spark 4.0은 이 주석 없이 variant 컬럼을 기록하므로, BYTE_ARRAY 타입의 metadata 필드와 value 필드만으로 구성된 그룹도 variant로 읽습니다. 이 동작은 input_format_parquet_detect_variant_by_structure 설정으로 비활성화할 수 있으며, 이 경우 해당 그룹은 이전과 같이 두 원시 필드로 구성된 Tuple로 읽습니다. 단, 컬럼에 Dynamic 또는 JSON 타입을 명시적으로 요청하면 설정과 관계없이 variant로 읽습니다. 각 값은 고유한 타입을 유지합니다. Variant 기본 타입은 대응하는 ClickHouse 타입으로 읽습니다(예: int32는 Int32, decimal8은 Decimal(18, S), timestamp는 DateTime64(6, 'UTC'), timestamp_ntz는 DateTime64(6), binary와 string은 String, uuid는 UUID). variant null은 NULL로 읽으며, variant 객체는 중첩 객체를 점으로 구분된 경로로 평탄화하여 JSON으로 읽습니다(null 필드는 존재하지 않는 것으로 간주합니다). 모든 원소가 객체인 variant 배열은 Array(JSON)으로, 그 밖의 variant 배열은 Array(Dynamic)으로 읽습니다. variant 값이 항상 객체라는 보장이 없으므로 최상위 타입은 JSON이 아닌 Dynamic입니다. 테이블 구조(table structure)나 file 테이블 함수의 구조 인수 등에서 JSON 타입을 명시적으로 지정하여 variant 컬럼을 JSON으로 읽을 수도 있습니다. 이 경우 모든 값이 객체여야 하며, 그렇지 않으면 예외가 발생합니다. variant null과 컬럼 전체가 null인 값은 빈 객체로 읽습니다. 요청한 JSON 타입에서 타입이 지정된 경로는 해당 타입으로 변환되며, SKIP 및 SKIP REGEXP에 나열된 경로는 건너뜁니다. Shredded variant(typed_value 필드가 있는 그룹)는 아직 지원되지 않습니다. 이러한 컬럼을 읽으면 예외가 발생하지만 파일의 나머지 컬럼은 정상적으로 읽을 수 있으며, input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference가 활성화되어 있으면 스키마 추론 시 해당 컬럼을 건너뜁니다. Dynamic 또는 JSON 컬럼을 Parquet에 VARIANT로 기록하는 것도 지원되지 않습니다.

파일 참조

Parquet FILE 논리 타입으로 지정된 그룹은 인라인으로 저장되거나 외부 파일에 저장된 바이트 범위에 대한 참조를 나타냅니다. 이 그룹은 파일에 있는 필드로 구성된 이름 있는 Tuple로 읽히며, 각 필드는 Nullable입니다. uri, content_type, checksum은 Nullable(String)으로, offset과 size는 Nullable(Int64)로, inline은 원시 바이트를 담은 Nullable(String)으로 읽힙니다. null 파일 참조는 모든 원소가 NULL인 튜플로 읽힙니다. 다른 Tuple과 마찬가지로, 원소 수가 더 적은 Tuple을 요청하여 필드의 부분 집합만 읽거나, file.uri처럼 개별 필드를 서브컬럼으로 읽을 수 있습니다. 그룹의 스키마(schema)는 검사 대상입니다. 스키마에는 이 필드들만 포함되어야 하고, 모든 필드는 OPTIONAL이어야 하며, 명세에 정의된 타입을 따라야 합니다. 그렇지 않으면 예외가 발생합니다. 반면 값은 검사하지 않으므로, 유효한 참조를 구성하지 않는 값(예: uri 없이 offset만 있는 경우)도 저장된 그대로 반환됩니다. ClickHouse는 참조를 해석하지 않습니다. 즉, 외부 파일을 읽지 않습니다. 쓰기 시 output_format_parquet_write_file_logical_type 설정이 활성화되어 있으면, 이러한 Tuple(원소 이름이 FILE 필드의 비어 있지 않은 부분 집합이고, offset과 size는 정수이며, 나머지 원소는 String 또는 FixedString인 경우)은 FILE로 지정된 그룹으로 기록됩니다. 설정이 비활성화되어 있으면 일반 그룹으로 기록됩니다.

기하 데이터 타입(geo types) (GeoParquet)

ClickHouse는 GeoParquet 사양 및 Parquet GEOMETRY와 GEOGRAPHY 논리 타입에 따라 지오메트리 컬럼의 읽기 및 쓰기를 지원합니다. 지오메트리 컬럼은 WKB로 인코딩된 BYTE_ARRAY 페이로드로 저장됩니다(GeoParquet의 경우 읽을 때는 WKT도 가능). GeoParquet은 파일 수준 Parquet 메타데이터의 JSON geo 키에 각 지오메트리 컬럼의 인코딩, 기하 도형 유형, CRS를 기술합니다. 반면 논리 타입은 컬럼 자체에 주석을 다는 방식이며, 이때 컬럼 청크 메타데이터에는 min/max 통계 대신 GeospatialStatistics(경계 상자와 기하 도형 유형 목록)가 포함됩니다. 하나의 파일에 두 방식이 함께 사용될 수도 있습니다.

읽기 동작

읽을 때 지오메트리 컬럼은 해당하는 ClickHouse 기하 데이터 타입(geo types)으로 매핑됩니다.
  • Point, MultiPoint, LineString, Polygon, MultiLineString 또는 MultiPolygon으로 선언된 컬럼은 이에 대응하는 ClickHouse 기하 데이터 타입(geo types)으로 읽어들입니다.
  • 여러 기하 도형 유형을 포함하거나 타입을 알 수 없는 컬럼은 지원되는 모든 기하 데이터 타입(geo types)을 포괄하는 Variant인 Geometry 타입으로 읽어들입니다.
  • GEOMETRY 또는 GEOGRAPHY 논리 타입을 가진 컬럼은 파일에 GeoParquet 메타데이터가 있으면 해당 메타데이터에서 기하 도형 유형을 가져옵니다. 메타데이터가 없으면 모든 컬럼 청크의 GeospatialStatistics에 동일한 단일 2D 기하 도형 유형이 지정된 경우 해당 기하 데이터 타입(geo types)으로 읽어들이고, 그렇지 않으면 Geometry로 읽어들입니다. 기하 데이터 타입(geo types)을 명시적으로 요청하면 값을 해당 타입으로 직접 디코딩합니다.
  • ClickHouse에는 geography 전용 타입이 없으므로 GEOGRAPHY 컬럼은 GEOMETRY와 동일한 기하 데이터 타입(geo types)으로 읽어들이며(좌표는 경도와 위도), 에지 보간 알고리즘(algorithm 매개변수)은 반영되지 않습니다. CRS(crs 매개변수, 기본값 OGC:CRS84) 역시 반영되지 않습니다. Z 또는 M 좌표를 가진 기하 도형은 지원되지 않습니다.
  • GEOMETRY 및 GEOGRAPHY 논리 타입의 정렬 순서(sort order)는 정의되어 있지 않으므로 이러한 컬럼의 min/max 통계와 컬럼 인덱스는 무시됩니다. input_format_parquet_spatial_filter_push_down을 활성화하면 GeospatialStatistics의 경계 상자를 사용해 행 그룹(row groups)을 건너뜁니다.
  • 요청한 컬럼 타입이 String이면 GeoParquet 메타데이터와 논리 타입은 무시되며, 원시 인코딩된 지오메트리 페이로드를 그대로 반환합니다. 즉, GeoParquet 컬럼에 선언된 인코딩에 따라 WKB 또는 WKT 바이트를 반환합니다. 이는 설정 input_format_parquet_allow_geoparquet_parser가 0으로 설정되어 있고 기하 데이터 타입(geo types)을 명시적으로 요청하지 않은 경우에도 마찬가지입니다.

쓰기 동작

쓰기 시 Point, MultiPoint, LineString, Polygon, MultiLineString 또는 MultiPolygon 타입의 최상위 컬럼은 BYTE_ARRAY(WKB)로 인코딩되며, 적절한 geo JSON 메타데이터가 Parquet 파일 footer에 추가됩니다. 최상위 Geometry Variant도 WKB BYTE_ARRAY 페이로드로 인코딩되지만(하위 값은 WKB로 변환되어 Nullable(String) 컬럼에 저장됨), 기본적으로 이에 대해서는 geo 메타데이터가 출력되지 않으므로 다시 읽으면 String으로 읽힙니다. 이러한 컬럼은 기본적으로 min/max 통계와 함께 BYTE_ARRAY로 기록됩니다. output_format_parquet_geometry_logical_type 설정을 활성화하면 이 모든 컬럼에 기본 CRS(OGC:CRS84)와 함께 GEOMETRY 논리 타입이 지정되며, 사양의 요구에 따라 컬럼 청크 메타데이터에는 GeospatialStatistics(경계 상자 및 기하 도형 유형)가 포함되지만 min/max 통계와 컬럼 인덱스는 포함되지 않습니다. 또한 Geometry 컬럼은 geo 메타데이터에 빈 기하 도형 유형 목록으로 기술되므로 다시 읽으면 Geometry로 읽힙니다. 이 논리 타입을 인식하지 못하는 판독기(예: 버전 20 이전의 Arrow C++ 및 pyarrow)는 파일 전체를 열 수 없기 때문에 이 설정은 기본적으로 비활성화되어 있습니다. Ring과 같은 다른 geo 관련 타입은 GeoParquet 메타데이터 없이 해당 네이티브 내부 표현으로 기록됩니다. 이 동작은 output_format_parquet_geometadata를 0으로 설정해 완전히 비활성화할 수 있으며, 이 경우 지원되는 기하 데이터 타입(geo types)도 네이티브 내부 표현(Point는 Tuple(Float64, Float64), LineString은 배열(Point), Polygon은 배열(배열(Point)) 등)으로 기록되고 GeoParquet 메타데이터도 출력되지 않습니다. 지오메트리 컬럼은 스키마 루트에 있거나 Tuple(struct) 내부에 중첩되어 있어야 하며, 배열 또는 Map 내부에 중첩하는 것은 지원되지 않습니다. geo 컬럼에는 Nullable도 지원되지 않습니다.

사용 예시

데이터 삽입

다음 데이터가 들어 있는 football.parquet라는 Parquet 파일을 사용합니다:
데이터를 삽입하세요:

데이터 읽기

다음과 같이 Parquet 포맷을 사용해 데이터를 읽습니다:
Parquet은 터미널에 사람이 읽을 수 있는 형태로 표시되지 않는 바이너리 형식입니다. Parquet 파일로 출력하려면 INTO OUTFILE을 사용하십시오.
Hadoop과 데이터를 주고받으려면 HDFS 테이블 엔진을 사용할 수 있습니다.

포맷 설정