메인 콘텐츠로 건너뛰기
Pub/Sub to ClickHouse Template은 Pub/Sub subscription에서 JSON으로 인코딩된 메시지를 읽어 ClickHouse 테이블에 기록하는 스트리밍 파이프라인입니다. 파싱에 실패하거나 대상 스키마에 맞게 매핑되지 않은 메시지는 데드 레터 대상, 즉 ClickHouse 테이블, Pub/Sub 토픽 또는 둘 다로 라우팅됩니다.

​
파이프라인 요구 사항

  • 소스 Pub/Sub subscription이 존재해야 합니다.
  • subscription에 게시되는 메시지는 유효한 JSON이어야 합니다.
  • 대상 ClickHouse 테이블(table)이 존재해야 하며, 해당 컬럼 이름은 JSON 페이로드(payload)의 필드 이름과 일치해야 합니다.
  • Dataflow worker 머신에서 ClickHouse 호스트에 접근할 수 있어야 합니다.
  • 데드 레터 대상(clickHouseDeadLetterTable 또는 deadLetterTopic)을 최소 하나 이상 지정해야 합니다. 둘 다 지정하면 실패한 메시지가 두 대상으로 동시에 라우팅됩니다.
  • clickHouseDeadLetterTable이 설정된 경우, 데드 레터 테이블은 데드 레터 처리에 나와 있는 스키마(schema)로 ClickHouse에 미리 존재해야 합니다.
  • deadLetterTopic이 설정된 경우, Pub/Sub 토픽이 미리 존재해야 합니다.

​
Template 매개변수



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

​
메시지 포맷 및 스키마 매핑

Pub/Sub 메시지는 최상위 필드 이름이 대상 ClickHouse 테이블의 컬럼 이름과 정확히 일치하는 JSON 객체여야 합니다. 수신 메시지를 대상 테이블에 매핑하기 위해 파이프라인은 시작 시 다음 작업을 수행합니다:
  1. 대상 ClickHouse 테이블의 스키마를 가져옵니다.
  2. 해당 ClickHouse 스키마를 바탕으로 Beam Row 스키마를 생성합니다.
  3. 수신되는 각 Pub/Sub 메시지에 대해 JSON payload를 파싱하고, ClickHouse 스키마에 정의된 이름의 필드를 읽어 행을 구성합니다.

JSON 필드 이름은 ClickHouse 컬럼 이름과 정확히 일치해야 합니다(대소문자를 구분함). 메시지에 포함된 필드 중 ClickHouse 컬럼에 해당하지 않는 필드는 무시됩니다. ClickHouse 컬럼에 대응하는 필드가 JSON payload에 없으면, 파이프라인은 해당 컬럼에 NULL을 기록하려고 시도합니다. 이는 해당 컬럼이 널 허용으로 선언된 경우에만 성공합니다. 파싱에 실패한 메시지, 값이 컬럼 타입으로 변환될 수 없는 메시지, 또는 널 허용이 아닌 컬럼에 NULL을 기록하려는 메시지는 데드 레터 대상으로 라우팅됩니다.

​
타입 변환

JSON 값은 해당 ClickHouse 컬럼 타입에 맞게 강제 변환됩니다:

​
배칭 및 윈도우 처리

파이프라인은 스트리밍 방식으로 동작하므로, 들어오는 행은 ClickHouse로 플러시되기 전에 윈도우 단위로 누적됩니다. 윈도우 처리 전략은 지정한 매개변수에 따라 선택됩니다. 이 값을 조정하면 지연 시간과 삽입 효율성 사이에서 균형을 맞출 수 있습니다. 더 작은 윈도우는 종단 간 지연 시간을 줄이고, 더 큰 윈도우는 수는 적지만 크기는 더 큰 INSERT 배치를 생성합니다.

​
데드 레터 처리

JSON 파싱, 스키마 매핑 또는 타입 강제 변환에 실패한 메시지는 구성된 데드 레터 대상(들)로 라우팅됩니다. clickHouseDeadLetterTable 또는 deadLetterTopic 중 최소 하나를 반드시 지정해야 합니다. 둘 다 설정하면 실패한 메시지가 두 곳 모두로 전송됩니다.

​
ClickHouse 데드 레터 테이블

clickHouseDeadLetterTable이 설정된 경우, 데드 레터 테이블은 다음과 같은 고정 스키마로 미리 생성되어 있어야 합니다: 단일 노드 배포를 위한 최소 정의:
배포 환경에 맞게 엔진과 ORDER BY 절을 조정하세요 — 복제된 테이블에는 ReplicatedMergeTree를 사용하고, 분산 환경에서는 ON CLUSTER를 추가하며, 필요에 따라 파티셔닝이나 TTL을 조정하십시오.

​
Pub/Sub 데드 레터 토픽

deadLetterTopic이 설정되면, 실패한 각 메시지가 다음 정보를 포함해 해당 토픽으로 다시 게시됩니다.
  • Payload: 원본 메시지 바이트입니다.
  • 속성 errorMessage: 실패 시점에 포착된 예외 메시지입니다.
  • 속성 failedAt: 해당 행이 실패한 처리 시점의 타임스탬프입니다.
이렇게 하면 기본 스키마 또는 프로듀서 문제를 해결한 후 실패한 메시지를 손쉽게 다시 처리할 수 있습니다.

​
Template 실행

Pub/Sub to ClickHouse Template은 Google Cloud Console에서 사용할 수 있습니다.
이 문서, 특히 위 섹션을 반드시 검토하여 Template의 구성 요구 사항과 사전 요구 사항을 충분히 이해하십시오.
Google Cloud Console에 로그인한 다음 Dataflow를 검색합니다.
  1. CREATE JOB FROM TEMPLATE 버튼을 누르십시오.
  2. Template 양식이 열리면 작업 이름을 입력하고 원하는 리전을 선택합니다.
  3. Dataflow Template 입력란에 ClickHouse 또는 Pub/Sub를 입력한 다음 Pub/Sub to ClickHouse Template을 선택합니다.
  4. 선택하면 양식이 확장됩니다. 다음을 입력합니다.
    • projects/<PROJECT_ID>/subscriptions/<SUBSCRIPTION_NAME> 형식의 Pub/Sub 입력 subscription
    • ClickHouse endpoint URL — ClickHouse Cloud의 경우 https://<HOST>:8443 사용
    • ClickHouse 데이터베이스, 대상 테이블, 사용자 이름 및 비밀번호
    • 최소 하나의 데드 레터 대상: ClickHouse 테이블 또는 Pub/Sub 토픽(또는 둘 다)
  5. 필요에 따라 Template parameters 섹션에 설명된 대로 배칭(windowSeconds, batchRowCount) 및 ClickHouseIO 튜닝 매개변수를 사용자 지정합니다.

​
작업 모니터링

작업 상태를 모니터링하려면 Google Cloud Console의 Dataflow Jobs 탭으로 이동하십시오. 여기에서 진행 상황과 오류를 포함한 작업 세부 정보를 확인할 수 있습니다: 템플릿은 또한 PubSubToClickHouse 네임스페이스 아래에 다음과 같은 사용자 지정 메트릭을 내보내며, Dataflow 작업 페이지에서 확인할 수 있습니다:

​
문제 해결

​
메모리 제한(총량) 초과 오류(코드 241)

이 오류는 ClickHouse가 대량의 데이터 배치를 처리하는 중 메모리가 부족할 때 발생합니다. 이 문제를 해결하려면 다음을 수행하십시오.
  • 인스턴스 리소스를 늘리세요: 데이터 처리 부하를 감당할 수 있도록 메모리가 더 많은 더 큰 인스턴스로 ClickHouse 서버를 업그레이드하십시오.
  • 배치 크기를 줄이세요: Dataflow 작업 구성에서 batchRowCount(및/또는 maxInsertBlockSize)를 줄여 더 작은 데이터 청크를 ClickHouse로 전송하면 배치당 메모리 사용량을 줄일 수 있습니다.

​
모든 메시지가 데드 레터 대상으로 전송됩니다

가장 흔한 원인은 다음과 같습니다.
  • JSON 필드 이름이 ClickHouse 컬럼 이름과 정확히 일치하지 않습니다(일치는 대소문자를 구분합니다).
  • JSON 값을 컬럼 유형으로 변환할 수 없습니다(예: DateTime 컬럼에 ISO-8601 형식이 아닌 문자열이 있는 경우).
  • 파이프라인이 시작된 이후 대상 테이블 스키마가 변경되었습니다 — 스키마는 시작 시 한 번만 가져옵니다. 스키마 변경 사항을 적용한 후 작업을 다시 시작하십시오.
근본 원인을 파악하려면 ClickHouse 데드 레터 테이블의 error_message 및 stack_trace 컬럼(또는 Pub/Sub 데드 레터 메시지의 errorMessage 속성)을 확인하십시오.

​
파이프라인이 시작되지만 ClickHouse에 행이 도착하지 않습니다

  • subscription이 메시지를 수신하고 있는지 확인하십시오 — Dataflow 작업 페이지에서 messages-received 메트릭을 확인하십시오.
  • 시간 기반 모드(windowSeconds만 해당)에서는 윈도우 경계에서만 행이 플러시됩니다. 플러시가 발생하는지 확인하려면 windowSeconds 값을 낮추십시오.
  • Dataflow 작업자와 ClickHouse 엔드포인트 간 네트워크 연결이 가능한지 확인하십시오(방화벽, VPC peering 또는 Private Service Connect).

​
Template 소스 코드

Template의 소스 코드는 다음 리포지토리에서 확인할 수 있습니다.
마지막 수정일 2026년 6월 19일