spark_catalog이며, 테이블은 {catalog name}.{database}.{table} 형식으로 식별됩니다. 새로운
카탈로그 기능을 사용하면 이제 단일 Spark 애플리케이션에서 여러 카탈로그를 추가해 사용할 수 있습니다.
ClickHouse Spark connector는 Catalog API와 TableProvider API(포맷 기반 접근 방식)라는 두 가지 액세스 패턴을 지원합니다. 두 방식의 차이를 이해하면 사용 사례에 맞는 접근 방식을 선택하는 데 도움이 됩니다.
- Java 8 또는 17 (Spark 4.0에는 Java 17 이상이 필요합니다)
- Scala 2.12 또는 2.13 (Spark 4.0은 Scala 2.13만 지원합니다)
- Apache Spark 3.3, 3.4, 3.5 또는 4.0
ClickHouse를 Spark와 통합하는 방법은 프로젝트 구성에 따라 여러 가지가 있습니다.
프로젝트의 빌드 파일(Maven의
pom.xml 또는 SBT의 build.sbt 등)에 ClickHouse Spark 커넥터를 의존성으로 직접 추가할 수 있습니다.
또는 필요한 JAR 파일을 $SPARK_HOME/jars/ 폴더에 넣거나, spark-submit 명령에서 --jars 플래그를 사용해 Spark 옵션으로 직접 전달할 수 있습니다.
두 방법 모두 Spark 환경에서 ClickHouse 커넥터를 사용할 수 있게 해줍니다.
- Maven
- Gradle
- SBT
- Spark SQL/Shell CLI
이 설정은 다음 방법 중 하나로 지정할 수 있습니다.
spark-defaults.conf를 편집하거나 생성합니다.- 구성을
spark-submit명령에 전달합니다(또는spark-shell/spark-sqlCLI 명령에 전달). - Context를 초기화할 때 구성을 추가합니다.
- Python
- Scala
- Java
- Python
- Scala
- Java
- Engine: 지정하지 않으면 기본값으로
MergeTree()를 사용합니다.engine옵션을 사용해 다른 엔진을 지정할 수 있습니다(예:ReplacingMergeTree(),SummingMergeTree()등). - ORDER BY: 필수 - 새 테이블을 생성할 때는 반드시
order_by옵션을 명시적으로 지정해야 합니다. 커넥터는 지정된 모든 컬럼이 스키마에 존재하는지 검증합니다. - 널 허용 키 지원: ORDER BY에 널 허용 컬럼이 포함되어 있으면
settings.allow_nullable_key=1을 자동으로 추가합니다
- Python
- Scala
- Java
이 옵션은 테이블이 아직 없어서 새로 생성해야 할 때 사용됩니다:
- 새 테이블을 생성할 때는
order_by옵션이 필요합니다. 지정한 모든 컬럼은 스키마에 존재해야 합니다. ** ORDER BY에 널 허용 컬럼이 포함되어 있고 이 값이 명시적으로 지정되지 않으면 자동으로1로 설정됩니다.
append: 기존 테이블에 데이터를 추가합니다overwrite: 테이블의 모든 데이터를 대체합니다(테이블을 TRUNCATE함)
- Python
- Scala
- Java
allow_nullable_key, index_granularity와 같은 ClickHouse 전용 설정과 그 밖의 테이블 수준 또는 쿼리 수준 설정을 구성할 수 있습니다. 이는 커넥터가 ClickHouse에 연결하는 방식을 제어하는 커넥터 옵션(host, database, table 등)과는 다릅니다.
TableProvider API에서는 settings.<key> 옵션 포맷을 사용합니다:
- Python
- Scala
- Java
spark.sql.catalog.<catalog_name>.option.<key> 포맷을 사용하십시오:
- Java
- Scala
- Python
- Spark SQL
- Java
- Scala
- Python
- Spark SQL
Spark SQL을 사용할 때는 한 번에 하나의 SQL statement만 실행할 수 있습니다.
VariantType 지원은 Spark 4.0+에서 제공되며, 실험적 JSON/Variant 타입을 활성화한 ClickHouse 25.3+가 필요합니다.
VariantType을 지원합니다. VariantType은 ClickHouse의 JSON 및 Variant 타입에 매핑되므로, 유연한 스키마의 데이터를 효율적으로 저장하고 쿼리할 수 있습니다.
이 섹션에서는 VariantType의 매핑과 사용법에 중점을 둡니다. 지원되는 모든 데이터 타입에 대한 전체 개요는 지원되는 데이터 타입 섹션을 참조하십시오.
ClickHouse에서 데이터를 읽으면
JSON 및 Variant 컬럼이 자동으로 Spark의 VariantType에 매핑됩니다.
- Scala
- Python
- Java
- Scala
- Python
- Java
variant_types 속성을 지정하지 않으면 해당 컬럼은 기본적으로 ClickHouse의 JSON 타입을 사용하며, 이 타입은 JSON 객체만 허용합니다:
variant_types 속성에 타입을 지정합니다:
Variant()에서 사용할 수 있습니다.
- 기본 타입:
String,Int8,Int16,Int32,Int64,UInt8,UInt16,UInt32,UInt64,Float32,Float64,Bool - 배열:
Array(T)— 여기서 T는 중첩 배열을 포함한 지원되는 모든 타입입니다 - JSON: JSON 객체 저장용
JSON
VariantType으로 읽힙니다. 이 동작은 재정의할 수 있으며, 문자열로 읽도록 설정할 수 있습니다.
- Scala
- Python
- Java
쓰기 포맷을 설정합니다:
- JSON 전용 데이터에는 JSON 타입 사용: JSON 객체만 저장한다면 기본 JSON 타입을 사용합니다(
variant_types속성 없음) - 타입을 명시적으로 지정:
Variant()를 사용할 때는 저장할 예정인 모든 타입을 명시적으로 나열합니다 - 실험적 기능 활성화: ClickHouse에서
allow_experimental_json_type = 1이 활성화되어 있는지 확인합니다 - 쓰기에는 JSON 포맷 사용: 더 나은 호환성을 위해 VariantType 데이터 쓰기에는 JSON 포맷을 권장합니다
- 쿼리 패턴 고려: JSON/Variant 타입은 효율적인 필터링을 위해 ClickHouse의 JSON 경로 쿼리를 지원합니다
- 성능을 위한 컬럼 힌트: ClickHouse에서 JSON 필드를 사용할 때 컬럼 힌트를 추가하면 쿼리 성능이 향상됩니다. 현재는 Spark를 통해 컬럼 힌트를 추가하는 기능을 지원하지 않습니다. 이 기능의 진행 상황은 GitHub issue #497에서 확인하십시오.
- Scala
- Python
- Java
구성 사용: 다음은 Catalog API와 TableProvider API 모두에 적용되는 Spark 수준의 구성 옵션입니다. 설정하는 방법은 2가지입니다.
-
전역 Spark 구성 (모든 작업에 적용됨):
-
작업별 재정의 (TableProvider API 전용 - 전역 설정을 재정의할 수 있음):
spark-defaults.conf에서 설정하거나 Spark 세션을 생성할 때 설정할 수 있습니다.
이 섹션에서는 Spark와 ClickHouse 간의 데이터 타입 매핑을 설명합니다. 아래 표는
ClickHouse에서 Spark로 데이터를 읽어올 때와 Spark에서 ClickHouse로 데이터를 삽입할 때의 데이터 타입 변환을 빠르게 참고할 수 있도록 정리한 것입니다.
프로젝트에 기여하거나 문제를 보고하려는 경우, 의견을 보내주시면 감사하겠습니다!
이슈를 등록하고, 개선 사항을 제안하고,
pull request를 제출하려면 GitHub 리포지토리를 방문하십시오.
기여는 언제나 환영합니다! 시작하기 전에 리포지토리의 기여 가이드라인을 확인해 주십시오.
ClickHouse Spark 커넥터 개선에 도움을 주셔서 감사합니다!