메인 콘텐츠로 건너뛰기
여기에서 비공개 프리뷰 대기 목록에 등록할 수 있습니다.
Pub/Sub ClickPipes는 ClickPipes UI를 사용해 수동으로 배포하고 관리할 수 있으며, OpenAPI 및 Terraform을 사용해 프로그래밍 방식으로도 배포하고 관리할 수 있습니다.

​
사전 요구 사항

ClickPipes 소개를 숙지했으며, 수집할 토픽이 포함된 GCP 프로젝트에 액세스할 수 있고, 적절한 Pub/Sub 권한이 있는 서비스 계정을 생성한 상태여야 합니다. ClickPipes에 필요한 정확한 권한 집합은 Pub/Sub IAM 권한 가이드에서 확인하십시오.

​
첫 번째 ClickPipe 만들기

  1. ClickHouse Cloud 서비스의 SQL 콘솔에 액세스합니다.
  1. 왼쪽 메뉴에서 Data Sources 버튼을 선택한 다음 “Set up a ClickPipe”를 클릭합니다.
  1. 데이터 소스로 GCP Pub/Sub를 선택합니다.
  1. ClickPipe 이름, GCP Project ID, 그리고 Pub/Sub 액세스 권한이 부여된 서비스 계정의 service account JSON file을 입력하여 양식을 작성합니다. Project ID는 6~30자여야 하며, 소문자, 숫자, 하이픈을 포함할 수 있고, 문자로 시작해야 하며, 하이픈으로 끝날 수 없습니다.
  1. 수집할 Pub/Sub 토픽을 선택합니다. 자격 증명이 확인되면 드롭다운이 GCP 프로젝트의 토픽으로 자동으로 채워지며, 알파벳순으로 정렬되어 표시됩니다.
    • 데이터 포맷. 토픽을 선택하면 ClickPipes가 Pub/Sub 스키마 레지스트리를 조회합니다. 토픽에 네이티브 Avro 또는 Protobuf 스키마가 연결되어 있으면 데이터 포맷과 스키마가 자동으로 감지되며, 셀렉터는 해당 토픽의 최신 스키마로 고정됩니다. 네이티브 스키마가 없는 토픽은 기본적으로 JSONEachRow를 사용합니다.
    • 시작 오프셋. 수신을 시작할 위치를 선택합니다. 사용할 수 있는 옵션은 Latest(새 메시지만), Earliest(보존된 가장 오래된 메시지), Seek to Timestamp(UTC 날짜/시간 선택기 포함)입니다.
    • 필터 표현식(선택 사항). 메시지 속성에 적용되는 Pub/Sub subscription filter입니다. 예: attributes.type = "telemetry". 필터는 페이로드가 아니라 메시지 속성에만 적용되며, 파이프를 만든 후에는 변경할 수 없습니다(필터를 변경하려면 파이프를 다시 만들어야 합니다).
    • UI에는 선택한 토픽의 샘플 메시지가 표시되며, Flatten object 토글을 사용해 중첩된 JSON이 대상 측에서 어떻게 평탄화되는지 미리 볼 수 있습니다.
  1. 다음 단계에서는 데이터를 새 ClickHouse table에 수집할지, 기존 table을 재사용할지 선택할 수 있습니다. 화면의 안내에 따라 table 이름, 스키마, 설정을 수정하십시오. 상단의 샘플 table에서 변경 사항을 실시간으로 미리 볼 수 있습니다.
제공된 컨트롤을 사용해 고급 설정도 사용자 지정할 수 있습니다.
  1. 또는 데이터를 기존 ClickHouse table에 수집하도록 선택할 수도 있습니다. 이 경우 UI에서 source의 필드를 선택한 대상 table의 ClickHouse 필드에 매핑할 수 있습니다.
  1. 마지막으로 내부 ClickPipes 사용자에 대한 권한을 구성할 수 있습니다.
권한: ClickPipes는 대상 table에 데이터를 쓰기 위한 전용 사용자를 생성합니다. 사용자 지정 role 또는 사전 정의된 role 중 하나를 선택하여 이 내부 사용자의 role을 설정할 수 있습니다.
  • Full access: cluster에 대한 전체 액세스 권한을 부여합니다. 대상 table과 함께 materialized view 또는 딕셔너리를 사용하는 경우 유용할 수 있습니다.
    • Only destination table: 대상 table에 대한 INSERT 권한만 부여합니다.
  1. “Complete Setup”을 클릭하면 시스템이 ClickPipe를 등록하며, 요약 table에 나열된 항목을 확인할 수 있습니다.
요약 테이블에서는 소스 또는 ClickHouse의 대상 테이블에 있는 샘플 데이터를 표시하는 컨트롤을 제공합니다. 또한 ClickPipe를 삭제하고 수집 작업의 요약을 표시하는 컨트롤도 제공합니다.
  1. 축하합니다! 첫 번째 Pub/Sub ClickPipe를 성공적으로 설정했습니다. 이제 이 ClickPipe는 계속 실행되며, Pub/Sub topic의 데이터를 ClickHouse Cloud 서비스로 실시간으로 수집합니다.

​
관리형 subscription

Pub/Sub 메시지는 토픽에서 직접 소비되지 않고 subscription을 통해 소비됩니다. ClickPipes는 각 파이프마다 전용 subscription을 생성하고 관리하므로, 토픽만 선택하면 됩니다.
  • 관리형 subscription의 이름은 clickpipes-{pipeID}이며, 파이프가 시작되면 해당 토픽에 생성됩니다.
  • 60초 ack deadline, 7일 메시지 보존, 그리고 활성화된 메시지 순서 지정으로 구성됩니다.
  • subscription 생성은 멱등적입니다. 즉, 파이프를 다시 시작하거나 레플리카가 다시 스케줄링될 때 이미 구성된 토픽을 가리키는 기존 subscription이 있으면 이를 재사용합니다.
  • 토픽 디스커버리와 메시지 샘플링 중에는 ClickPipes가 수명이 짧은 ephemeral subscription(clickpipes-discovery-{uuid})도 생성하며, 샘플링이 완료되면 즉시 삭제됩니다.
  • 파이프가 삭제되면 ClickPipes는 정리 과정의 일부로 관리형 subscription도 삭제합니다.
따라서 제공한 서비스 계정에는 subscription을 소비하는 권한 외에도, 프로젝트에서 subscription을 생성하고 삭제할 수 있는 권한이 있어야 합니다. 전체 목록은 Pub/Sub IAM permissions guide를 참조하십시오.

​
지원되는 데이터 포맷

지원되는 포맷은 다음과 같습니다:
  • JSON
  • Avro — Pub/Sub 네이티브 스키마(BINARY 인코딩)를 통해 지원됩니다
  • Protobuf — Pub/Sub 네이티브 스키마(BINARY 인코딩)를 통해 지원됩니다
Avro와 Protobuf의 경우, 스키마는 토픽의 Pub/Sub 스키마 레지스트리에서 조회됩니다. 파이프는 항상 토픽 스키마의 최신 리비전을 사용하며, UI의 스키마 셀렉터는 설계상 읽기 전용입니다.

​
압축

Pub/Sub용 ClickPipes는 압축된 메시지를 자동으로 감지해 압축을 해제합니다. Pub/Sub 클라이언트는 원시 바이트를 전달하며, 별도 구성 없이 ClickPipes가 압축 해제를 처리합니다. 지원되는 압축 코덱은 다음과 같습니다:
  • gzip
  • zstd
  • lz4
  • snappy (프레임 형식)
압축은 각 메시지의 매직 바이트를 통해 자동으로 감지됩니다. 알려진 압축 시그니처가 없으면 해당 메시지는 비압축 상태로 처리됩니다. 감지된 압축 유형은 스키마 추론 과정에서도 표시되므로, UI의 샘플 데이터 미리 보기에는 압축 해제된 페이로드가 올바르게 표시됩니다.
자동 감지는 JSON과 같은 텍스트 기반 포맷에서 안전합니다. 출력 가능한 ASCII 문자는 압축 매직 바이트와 절대 충돌하지 않기 때문입니다. 압축 해제된 페이로드는 최대 64MB로 제한됩니다.

​
지원되는 데이터 타입

​
표준 타입 지원

현재 ClickPipes는 다음 ClickHouse 데이터 타입을 지원합니다:
  • 기본 숫자 타입 - [U]Int8/16/32/64, Float32/64 및 BFloat16
  • 대형 정수 타입 - [U]Int128/256
  • Decimal 타입
  • Boolean
  • String
  • FixedString
  • Date, Date32
  • DateTime, DateTime64 (UTC 시간대만)
  • Enum8/Enum16
  • UUID
  • IPv4
  • IPv6
  • 모든 ClickHouse LowCardinality 타입
  • 키와 값에 위 타입 중 아무 타입이나 사용할 수 있는 맵(널 허용 포함)
  • 요소에 위 타입 중 아무 타입이나 사용할 수 있는 Tuple 및 배열(널 허용 포함, 깊이 1단계만)
  • SimpleAggregateFunction 타입(AggregatingMergeTree 또는 SummingMergeTree 대상용)

​
Variant 유형 지원

소스 데이터 스트림의 모든 JSON 필드에 대해 Variant 유형(예: Variant(String, Int64, DateTime))을 수동으로 지정할 수 있습니다. ClickPipes가 사용할 올바른 variant subtype을 판별하는 방식상, Variant 정의에는 정수 유형 또는 datetime 유형을 각각 하나만 사용할 수 있습니다. 예를 들어 Variant(Int64, UInt32)는 지원되지 않습니다.

​
JSON 타입 지원

항상 JSON 객체인 JSON 필드는 JSON 대상 컬럼에 할당할 수 있습니다. 고정되거나 건너뛴 경로를 포함해, 대상 컬럼은 원하는 JSON 타입으로 수동으로 변경해야 합니다.

​
Pub/Sub 가상 컬럼

다음 가상 컬럼은 Pub/Sub 토픽에서 지원됩니다. 새 대상 테이블을 만들 때 Add Column 버튼을 사용해 가상 컬럼을 추가할 수 있습니다.
이름설명권장 데이터 타입
_message_id브로커가 할당한 Pub/Sub 메시지 IDString
_publish_timePub/Sub 게시 타임스탬프(밀리초 정밀도, UTC)DateTime64(3)
_ordering_keyPub/Sub 순서 지정 키(메시지에 키가 설정되지 않은 경우 빈 문자열)String
_attributes사용자 정의 Pub/Sub 메시지 속성Map(String, String)
_raw_message전체 Pub/Sub 메시지 페이로드(기본적으로 비활성화됨)String
_raw_message 필드는 전체 Pub/Sub 메시지 페이로드만 필요한 경우에 사용할 수 있습니다(예: ClickHouse JsonExtract* 함수를 사용해 후속 materialized view를 채우는 경우). 이러한 파이프의 경우 “non-virtual” 컬럼을 모두 삭제하면 ClickPipes 성능이 향상될 수 있습니다.

​
제한 사항

  • DEFAULT는 지원되지 않습니다.
  • 가장 작은 (XS) 레플리카 크기로 실행할 경우, 개별 메시지 크기는 기본적으로 8MB(비압축)로 제한되며 더 큰 레플리카에서는 16MB(비압축)로 제한됩니다. 이 한도를 초과하는 메시지는 오류와 함께 거부됩니다. 더 큰 메시지가 필요하면 지원팀에 문의하십시오.
  • Pub/Sub subscription 필터는 변경할 수 없습니다 — 필터 표현식을 변경하려면 파이프를 다시 생성해야 합니다.
  • 필터는 메시지 페이로드가 아니라 메시지 속성에만 적용됩니다.

​
성능

​
배칭

ClickPipes는 데이터를 배치로 묶어 ClickHouse에 삽입합니다. 이는 데이터베이스에 파트가 과도하게 생성되는 것을 방지하기 위한 것으로, 그렇지 않으면 클러스터 성능 문제가 발생할 수 있습니다. 다음 기준 중 하나를 충족하면 배치가 삽입됩니다:
  • 배치 크기가 최대 크기에 도달한 경우(100,000행 또는 레플리카 메모리 1GB당 32MB)
  • 배치가 최대 시간(5초) 동안 열려 있었던 경우

​
지연 시간

지연 시간(즉, Pub/Sub 메시지가 게시된 시점부터 해당 메시지를 ClickHouse에서 사용할 수 있게 될 때까지 걸리는 시간)은 여러 요인(게시자 지연 시간, 네트워크 지연 시간, 메시지 크기/포맷)에 따라 달라집니다. 위 섹션에서 설명한 배칭 역시 지연 시간에 영향을 줍니다. 예상되는 지연 시간을 정확히 파악하려면 실제 사용 사례에 맞춰 테스트해 볼 것을 항상 권장합니다. 낮은 지연 시간에 대한 구체적인 요구 사항이 있다면 문의해 주십시오.

​
순서 지정 키

Pub/Sub는 동일한 순서 지정 키를 공유하는 메시지가 하나의 구독자에게 게시된 순서대로 전달되도록 보장합니다. ClickPipes는 관리형 구독에서 기본적으로 순서 지정을 활성화합니다. 따라서 메시지에 순서 지정 키가 있으면 구독자는 해당 메시지를 순서대로 수신하며, 순서 지정 키가 없으면 동작은 달라지지 않습니다. 프로듀서가 모든 메시지를 소수의 순서 지정 키(또는 단일 키)로 게시하면, Pub/Sub는 해당 메시지를 소수의 구독자에게 집중시켜 전달하므로 수평 처리량이 제한될 수 있습니다. 순서가 필요하지 않다면 순서 지정 키를 생략하거나, 카디널리티가 높은 순서 지정 키를 사용할 것을 권장합니다.

​
스케일링

Pub/Sub용 ClickPipes는 수평 및 수직으로 모두 스케일링할 수 있도록 설계되었습니다. 각 파이프는 단일 관리형 Pub/Sub subscription을 사용하며, 이는 구성할 수 없습니다. 기본적으로 하나의 컨슈머가 해당 subscription에서 데이터를 가져오며, ClickPipe 생성 시 또는 설정 -> 고급 설정 -> 스케일링에서 언제든지 컨슈머 수를 늘릴 수 있습니다. ClickPipes는 subscription의 메시지를 실행 중인 컨슈머에 자동으로 분산하므로 별도의 조정은 필요하지 않습니다. ClickPipes는 가용 영역에 분산된 아키텍처를 통해 고가용성을 제공하며, 이를 위해서는 최소 2개의 컨슈머로 스케일링해야 합니다. 실행 중인 컨슈머 수와 관계없이 장애 허용은 설계상 기본적으로 제공됩니다. 컨슈머 또는 기반 인프라에 장애가 발생하면 ClickPipes가 해당 컨슈머를 자동으로 다시 시작하고 메시지 처리를 계속합니다.

​
전달 보장 방식

Pub/Sub용 ClickPipes는 at-least-once 전달을 제공합니다. Pub/Sub 메시지는 해당 행이 ClickHouse에 삽입된 후에만(또는 형식이 잘못된 레코드의 경우 오류 테이블에 기록된 후에만) ack됩니다. 무한 재전달을 방지하기 위해, 오류 테이블로 라우팅된 잘못된 레코드를 포함해 모든 메시지는 처리되면 ack됩니다. 레플리카가 삽입 후 Pub/Sub에 ack가 도달하기 전에 장애로 중단되면, 메시지는 ack deadline이 지난 뒤 다시 전달되고 다시 삽입되므로 다운스트림 consumer는 중복을 허용할 수 있어야 합니다. 정확히 한 번 처리 의미 체계가 필요하다면 _message_id 가상 컬럼을 사용해 다운스트림에서 중복을 제거하십시오(Pub/Sub의 각 메시지 ID는 토픽 내에서 고유합니다).

​
인증

Pub/Sub용 ClickPipes는 서비스 계정 JSON 키를 사용해 GCP에 인증합니다. 파이프를 생성할 때 키 파일을 업로드하면, ClickPipes는 해당 파일을 저장 시 암호화하고 메시지를 소비하며 managed subscription의 수명 주기를 관리하는 데 런타임에 사용합니다. 필요한 IAM 권한의 정확한 목록과 권장되는 사용자 지정 역할(Role) 정의는 Pub/Sub IAM 권한 가이드를 참조하십시오.
마지막 수정일 2026년 6월 10일