본문으로 바로가기
본문으로 바로가기

Dataflow BigQuery to ClickHouse 템플릿

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

파이프라인 요구 사항​

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

템플릿 매개변수​



매개변수 이름매개변수 설명필수비고
jdbcUrljdbc: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복제된 테이블에 대한 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>.
queryBigQuery에서 데이터를 읽기 위해 사용할 SQL 쿼리입니다. BigQuery 데이터셋이 Dataflow 작업과 다른 프로젝트에 있는 경우, 예를 들어 <PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>처럼 SQL 쿼리에서 전체 데이터셋 이름을 지정해야 합니다. useLegacySql이 true가 아닌 한 기본적으로 GoogleSQL이 사용됩니다.inputTableSpec 또는 query 중 하나를 반드시 지정해야 합니다. 두 매개변수를 모두 설정하면 템플릿은 query 매개변수를 사용합니다. 예: SELECT * FROM sampledb.sample_table.
useLegacySql레거시 SQL을 사용하려면 true로 설정합니다. 이 매개변수는 query 매개변수를 사용할 때만 적용됩니다. 기본값은 false입니다.
queryLocation기본 테이블에 대한 권한 없이 승인된 뷰(authorized view)에서 읽을 때 필요합니다. 예: US.
queryTempDataset쿼리 결과를 저장할 임시 테이블을 생성하기 위해 사용할 기존 데이터셋을 설정합니다. 예: temp_dataset.
KMSEncryptionKey쿼리 소스를 사용하여 BigQuery에서 읽는 경우, 생성되는 임시 테이블을 암호화하기 위해 사용할 Cloud KMS 키입니다. 예: projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key.
참고

모든 ClickHouseIO 매개변수의 기본값은 ClickHouseIO Apache Beam Connector에 나와 있습니다.

소스 및 타깃 테이블 스키마​

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

  1. 템플릿은 대상 ClickHouse 테이블을 기반으로 스키마 객체를 생성합니다.
  2. 템플릿은 BigQuery 데이터셋을 순회하면서 컬럼 이름을 기준으로 컬럼을 매핑합니다.

참조

따라서 BigQuery 데이터셋(테이블이든 쿼리 결과이든)은 ClickHouse 대상 테이블과 컬럼 이름이 정확히 동일해야 합니다.

데이터 타입 매핑​

BigQuery 데이터 타입은 ClickHouse 테이블 정의를 기준으로 변환됩니다. 따라서 위의 테이블에는 특정 BigQuery 테이블/쿼리에 대해 대상 ClickHouse 테이블에서 사용해야 하는 권장 매핑이 나와 있습니다.

BigQuery TypeClickHouse TypeNotes
Array TypeArray Type내부 타입은 이 표에 나열된 지원되는 기본(primitive) 데이터 타입 중 하나여야 합니다.
Boolean TypeBool Type
Date TypeDate Type
Datetime TypeDatetime TypeEnum8, Enum16, FixedString와 함께도 사용할 수 있습니다.
String TypeString TypeBigQuery에서는 모든 Int 타입(INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT)이 INT64의 별칭입니다. 템플릿이 정의된 컬럼 타입(Int8, Int16, Int32, Int64)에 따라 컬럼을 변환하므로, ClickHouse에서 적절한 Integer 크기를 설정하는 것이 좋습니다.
Numeric - Integer TypesInteger TypesBigQuery에서는 모든 Int 타입(INT, SMALLINT, INTEGER, BIGINT, TINYINT, BYTEINT)이 INT64의 별칭입니다. 템플릿이 정의된 컬럼 타입(Int8, Int16, Int32, Int64)에 따라 컬럼을 변환하므로, ClickHouse에서 적절한 Integer 크기를 설정하는 것이 좋습니다. 또한 템플릿은 ClickHouse 테이블에서 사용되는 부호 없는 Int 타입(UInt8, UInt16, UInt32, UInt64)도 변환합니다.
Numeric - Float TypesFloat Types지원되는 ClickHouse 타입은 Float32와 Float64입니다.

Running the Template​

BigQuery to ClickHouse 템플릿은 Google Cloud CLI를 통해 실행할 수 있습니다.

참고

이 문서, 특히 위의 섹션들을 검토하여 템플릿의 구성 요구 사항과 사전 조건을 충분히 이해해야 합니다.

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

  1. CREATE JOB FROM TEMPLATE 버튼을 누릅니다.
    DataFlow 콘솔
  2. 템플릿 양식이 열리면 작업 이름을 입력하고 원하는 리전을 선택합니다.
    DataFlow 템플릿 초기 양식
  3. DataFlow Template 입력란에 ClickHouse 또는 BigQuery를 입력한 뒤, BigQuery to ClickHouse 템플릿을 선택합니다.
    BigQuery to ClickHouse 템플릿 선택
  4. 템플릿을 선택하면 추가 세부 정보를 입력할 수 있도록 양식이 확장됩니다.
    • 다음 형식의 ClickHouse 서버 JDBC URL: jdbc:clickhouse://host:port/schema
    • ClickHouse 사용자 이름
    • ClickHouse 대상 테이블 이름

참고

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

확장된 BigQuery to ClickHouse 템플릿 양식
  1. Template Parameters 섹션에 설명된 대로, 필요에 따라 BigQuery/ClickHouseIO 관련 설정을 구성하고 추가합니다.

작업 모니터링​

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

실행 중인 BigQuery to ClickHouse 작업이 표시된 Dataflow 콘솔

문제 해결​

Memory limit (total) exceeded error (code 241)​

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

  • 인스턴스 리소스 증가: 데이터 처리 부하를 감당할 수 있도록 더 많은 메모리를 가진 더 큰 인스턴스로 ClickHouse 서버를 업그레이드하십시오.
  • 배치 크기 감소: Dataflow 작업 설정에서 배치 크기를 조정하여 더 작은 데이터 청크를 ClickHouse로 전송하면 배치당 메모리 사용량을 줄일 수 있습니다. 이러한 변경은 데이터 수집 과정에서 리소스 사용을 균형 있게 조정하는 데 도움이 됩니다.

Template 소스 코드​

Template의 소스 코드는 ClickHouse에서 포크한 DataflowTemplates 저장소에서 확인할 수 있습니다.