Dataflow BigQuery-ClickHouse Template - ClickHouse Documentation

BigQuery에서 ClickHouse로 전송하는 Template은 BigQuery 테이블의 데이터를 ClickHouse 테이블로 수집하는 배치 파이프라인입니다. 이 Template은 전체 테이블을 읽거나, 제공된 SQL 쿼리를 사용해 특정 레코드만 필터링할 수 있습니다.

파이프라인 요구 사항

소스 BigQuery 테이블이 존재해야 합니다.
대상 ClickHouse 테이블이 존재해야 합니다.
Dataflow 워커 머신이 ClickHouse 호스트에 접근할 수 있어야 합니다.

Template 매개변수

Parameter Name	Parameter Description	Required	Notes
`jdbcUrl`	`jdbc:clickhouse://<host>:<port>/<schema>` 형식의 ClickHouse JDBC URL입니다.	✅	사용자 이름과 비밀번호는 JDBC 옵션으로 추가하지 마십시오. 그 밖의 JDBC 옵션은 JDBC URL 끝에 추가할 수 있습니다. ClickHouse Cloud 사용자는 `jdbcUrl`에 `ssl=true&sslmode=NONE`을 추가하십시오.
`clickHouseUsername`	인증에 사용할 ClickHouse 사용자 이름입니다.	✅
`clickHousePassword`	인증에 사용할 ClickHouse 비밀번호입니다.	✅
`clickHouseTable`	데이터가 삽입될 대상 ClickHouse 테이블입니다.	✅
`maxInsertBlockSize`	삽입용 블록 생성 방식을 제어하는 경우, 삽입을 위한 최대 블록 크기입니다. (`ClickHouseIO` 옵션)		`ClickHouseIO` 옵션입니다.
`insertDistributedSync`	이 설정을 활성화하면 분산 테이블에 대한 INSERT 쿼리는 데이터가 클러스터의 모든 노드로 전송될 때까지 대기합니다. (`ClickHouseIO` 옵션)		`ClickHouseIO` 옵션입니다.
`insertQuorum`	복제된 테이블(Replicated Table)의 INSERT 쿼리에서 지정한 수의 레플리카에 대한 쓰기가 완료될 때까지 대기하고, 데이터 추가를 선형화합니다. 0 - 비활성화.		`ClickHouseIO` 옵션입니다. 이 설정은 기본 서버 설정에서 비활성화되어 있습니다.
`insertDeduplicate`	복제된 테이블(Replicated Table)의 INSERT 쿼리에서 삽입되는 블록에 대해 중복 제거를 수행할지 지정합니다.		`ClickHouseIO` 옵션입니다.
`maxRetries`	삽입당 최대 재시도 횟수입니다.		`ClickHouseIO` 옵션입니다.
`InputTableSpec`	읽어올 BigQuery 테이블입니다. `inputTableSpec` 또는 `query` 중 하나를 지정하십시오. 둘 다 설정하면 `query` 매개변수가 우선합니다. 예시: `<BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>`.		BigQuery Storage Read API를 사용해 BigQuery 스토리지에서 직접 데이터를 읽습니다. Storage Read API 제한 사항을 확인하십시오.
`outputDeadletterTable`	출력 테이블에 기록되지 못한 메시지를 저장하는 BigQuery 테이블입니다. 테이블이 없으면 파이프라인 실행 중에 생성됩니다. 지정하지 않으면 `<outputTableSpec>_error_records`가 사용됩니다. 예를 들어 `<PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>`입니다.
`query`	BigQuery에서 데이터를 읽는 데 사용할 SQL 쿼리입니다. BigQuery 데이터셋이 Dataflow 작업과 다른 프로젝트에 있는 경우 SQL 쿼리에서 전체 데이터셋 이름을 지정하십시오. 예: `<PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>`. `useLegacySql`이 true가 아니면 기본값은 GoogleSQL입니다.		`inputTableSpec` 또는 `query` 중 하나를 반드시 지정해야 합니다. 두 매개변수를 모두 설정하면 템플릿은 `query` 매개변수를 사용합니다. 예시: `SELECT * FROM sampledb.sample_table`.
`useLegacySql`	레거시 SQL을 사용하려면 `true`로 설정합니다. 이 매개변수는 `query` 매개변수를 사용할 때만 적용됩니다. 기본값은 `false`입니다.
`queryLocation`	기본 테이블에 대한 권한 없이 승인된 뷰에서 읽을 때 필요합니다. 예: `US`.
`queryTempDataset`	쿼리 결과를 저장할 임시 테이블을 생성할 기존 데이터셋을 설정합니다. 예: `temp_dataset`.
`KMSEncryptionKey`	쿼리 소스를 사용해 BigQuery에서 읽는 경우, 생성되는 임시 테이블을 암호화하는 데 이 Cloud KMS 키를 사용합니다. 예: `projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key`.

모든 ClickHouseIO 매개변수의 기본값은 ClickHouseIO Apache Beam 커넥터에서 확인할 수 있습니다.

소스 및 대상 테이블 스키마

BigQuery 데이터셋을 ClickHouse에 효과적으로 적재하기 위해 파이프라인은 다음 단계로 컬럼 추론 과정을 수행합니다:

Template는 대상 ClickHouse 테이블을 기준으로 스키마 객체를 생성합니다.
Template는 BigQuery 데이터셋을 순회하며 컬럼 이름을 기준으로 일치하는 컬럼을 찾습니다.

다만 BigQuery 데이터셋(테이블 또는 쿼리)의 컬럼 이름은 ClickHouse 대상 테이블의 컬럼 이름과 정확히 동일해야 합니다.

데이터 타입 매핑

BigQuery 타입은 ClickHouse 테이블 정의에 따라 변환됩니다. 따라서 위 표에는 대상 ClickHouse 테이블에 권장되는 매핑이 나와 있습니다(해당 BigQuery 테이블/쿼리 기준).

BigQuery Type	ClickHouse Type	Notes
배열 타입	배열 타입	내부 타입은 이 표에 나열된 지원되는 기본 데이터 타입 중 하나여야 합니다.
불리언 타입	Bool 타입
날짜 타입	Date 타입
Datetime 타입	Datetime 타입	`Enum8`, `Enum16`, `FixedString`에도 사용할 수 있습니다.
String 타입	String 타입	BigQuery에서는 모든 Int 타입(`INT`, `SMALLINT`, `INTEGER`, `BIGINT`, `TINYINT`, `BYTEINT`)이 `INT64`의 별칭입니다. Template은 정의된 컬럼 타입(`Int8`, `Int16`, `Int32`, `Int64`)에 따라 컬럼을 변환하므로, ClickHouse에서는 적절한 Integer 크기를 설정하는 것이 좋습니다.
Numeric - Integer 타입	Integer 타입	BigQuery에서는 모든 Int 타입(`INT`, `SMALLINT`, `INTEGER`, `BIGINT`, `TINYINT`, `BYTEINT`)이 `INT64`의 별칭입니다. Template은 정의된 컬럼 타입(`Int8`, `Int16`, `Int32`, `Int64`)에 따라 컬럼을 변환하므로, ClickHouse에서는 적절한 Integer 크기를 설정하는 것이 좋습니다. 또한 ClickHouse 테이블에서 `UInt8`, `UInt16`, `UInt32`, `UInt64`와 같은 부호 없는 Int 타입을 사용하는 경우에도 템플릿이 이를 변환합니다.
Numeric - Float 타입	Float 타입	지원되는 ClickHouse 타입: `Float32` 및 `Float64`

Template 실행

BigQuery to ClickHouse Template는 Google Cloud CLI를 통해 실행할 수 있습니다.

이 문서, 특히 위 섹션을 반드시 검토하여 Template의 구성 요구 사항과 사전 요구 사항을 충분히 이해하십시오.

Google Cloud Console
Google Cloud CLI

Google Cloud Console에 로그인한 다음 DataFlow를 검색합니다.

CREATE JOB FROM TEMPLATE 버튼을 클릭합니다.
Template 양식이 열리면 작업 이름을 입력하고 원하는 리전을 선택합니다.
DataFlow Template 입력란에 ClickHouse 또는 BigQuery를 입력한 다음 BigQuery to ClickHouse Template를 선택합니다.
Template를 선택하면 양식이 확장되어 다음과 같은 추가 정보를 입력할 수 있습니다.
- jdbc:clickhouse://host:port/schema 형식의 ClickHouse 서버 JDBC URL
- ClickHouse 사용자 이름
- ClickHouse 대상 테이블 이름

ClickHouse 비밀번호 옵션은 비밀번호가 구성되지 않은 경우를 위해 선택 사항으로 표시됩니다. 추가하려면 아래로 스크롤하여 Password for ClickHouse Endpoint 옵션으로 이동하십시오.

Template Parameters 섹션에 설명된 대로 BigQuery/ClickHouseIO 관련 구성을 필요에 맞게 사용자 지정하여 추가합니다.

`gcloud` CLI 설치 및 구성

아직 설치하지 않았다면 gcloud CLI를 설치합니다.
이 가이드의 Before you begin 섹션에 따라 DataFlow Template 실행에 필요한 구성, 설정, 권한을 준비합니다.

명령 실행

Flex Template를 사용하는 Dataflow 작업을 실행하려면 gcloud dataflow flex-template run 명령을 사용합니다.아래는 명령 예시입니다.

gcloud dataflow flex-template run "bigquery-clickhouse-dataflow-$(date +%Y%m%d-%H%M%S)" \
 --template-file-gcs-location "gs://clickhouse-dataflow-templates/bigquery-clickhouse-metadata.json" \
 --parameters inputTableSpec="<bigquery table id>",jdbcUrl="jdbc:clickhouse://<clickhouse host>:<clickhouse port>/<schema>?ssl=true&sslmode=NONE",clickHouseUsername="<username>",clickHousePassword="<password>",clickHouseTable="<clickhouse target table>"

명령 설명

Job Name: run 키워드 뒤의 텍스트는 고유한 작업 이름입니다.
Template File: --template-file-gcs-location으로 지정한 JSON 파일은 Template 구조와 허용되는 매개변수에 대한 세부 정보를 정의합니다. 언급된 파일 경로는 공개되어 있으며 바로 사용할 수 있습니다.
Parameters: 매개변수는 쉼표로 구분됩니다. 문자열 기반 매개변수의 경우 값은 큰따옴표로 묶으십시오.

예상 응답

명령을 실행한 후에는 다음과 유사한 응답이 표시됩니다.

job:
  createTime: '2025-01-26T14:34:04.608442Z'
  currentStateTime: '1970-01-01T00:00:00Z'
  id: 2025-01-26_06_34_03-13881126003586053150
  location: us-central1
  name: bigquery-clickhouse-dataflow-20250126-153400
  projectId: ch-integrations
  startTime: '2025-01-26T14:34:04.608442Z'

작업 모니터링

Google Cloud Console의 Dataflow Jobs 탭으로 이동하여 작업 상태를 모니터링합니다. 진행 상황과 오류를 포함한 작업 세부 정보를 확인할 수 있습니다:

문제 해결

메모리 제한(전체) 초과 오류(코드 241)

이 오류는 ClickHouse가 대량의 데이터 배치를 처리하는 중 메모리가 부족할 때 발생합니다. 이 문제를 해결하려면 다음을 수행하세요.

인스턴스 리소스를 늘리세요: 데이터 처리 부하를 감당할 수 있도록 메모리가 더 많은 상위 인스턴스로 ClickHouse 서버를 업그레이드하십시오.
배치 크기를 줄이세요: Dataflow 작업 구성에서 배치 크기를 조정해 더 작은 데이터 청크를 ClickHouse로 전송하면 배치당 메모리 사용량을 줄일 수 있습니다. 이러한 변경은 데이터 수집 중 리소스 사용량의 균형을 맞추는 데 도움이 됩니다.

Template 소스 코드

Template의 소스 코드는 다음 리포지토리에서 확인할 수 있습니다:

GoogleCloudPlatform/DataflowTemplates — 원본 Google Cloud Platform 리포지토리입니다.
ClickHouse/DataflowTemplates — ClickHouse의 포크 리포지토리입니다.

​파이프라인 요구 사항

​Template 매개변수

​소스 및 대상 테이블 스키마

​데이터 타입 매핑

​Template 실행

​gcloud CLI 설치 및 구성

​명령 실행

​명령 설명

​예상 응답

​작업 모니터링

​문제 해결

​메모리 제한(전체) 초과 오류(코드 241)

​Template 소스 코드

파이프라인 요구 사항

Template 매개변수

소스 및 대상 테이블 스키마

데이터 타입 매핑

Template 실행

`gcloud` CLI 설치 및 구성

명령 실행

명령 설명

예상 응답

작업 모니터링

문제 해결

메모리 제한(전체) 초과 오류(코드 241)

Template 소스 코드