여기에서 비공개 프리뷰 대기 목록에 등록할 수 있습니다.
첫 번째 ClickPipe 만들기
- ClickHouse Cloud 서비스의 SQL 콘솔에 액세스합니다.

- 왼쪽 메뉴에서
Data Sources버튼을 선택한 다음 “Set up a ClickPipe”를 클릭합니다.

- 데이터 소스로 GCP Pub/Sub를 선택합니다.

- ClickPipe 이름, GCP Project ID, 그리고 Pub/Sub 액세스 권한이 부여된 서비스 계정의 service account JSON file을 입력하여 양식을 작성합니다. Project ID는 6~30자여야 하며, 소문자, 숫자, 하이픈을 포함할 수 있고, 문자로 시작해야 하며, 하이픈으로 끝날 수 없습니다.

-
수집할 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이 대상 측에서 어떻게 평탄화되는지 미리 볼 수 있습니다.

- 다음 단계에서는 데이터를 새 ClickHouse 테이블에 수집할지, 기존 테이블을 재사용할지 선택할 수 있습니다. 화면의 안내에 따라 테이블 이름, 스키마, 설정을 수정하십시오. 상단의 샘플 테이블에서 변경 사항을 실시간으로 미리 볼 수 있습니다.


- 또는 데이터를 기존 ClickHouse 테이블에 수집하도록 선택할 수도 있습니다. 이 경우 UI에서 소스의 필드를 선택한 대상 테이블의 ClickHouse 필드에 매핑할 수 있습니다.

- 마지막으로 내부 ClickPipes 사용자에 대한 권한을 구성할 수 있습니다.
Full access: 클러스터에 대한 전체 액세스 권한을 부여합니다. 대상 테이블과 함께 materialized view 또는 딕셔너리를 사용하는 경우 유용할 수 있습니다.Only destination table: 대상 테이블에 대한INSERT권한만 부여합니다.

- “Complete Setup”을 클릭하면 시스템이 ClickPipe를 등록하며, 요약 테이블에 나열된 항목을 확인할 수 있습니다.




- 축하합니다! 첫 번째 Pub/Sub ClickPipe를 성공적으로 설정했습니다. 이제 이 ClickPipe는 계속 실행되며, Pub/Sub 토픽의 데이터를 ClickHouse Cloud 서비스로 실시간으로 수집합니다.
- 관리형 subscription의 이름은
clickpipes-{pipeID}이며, 파이프가 시작되면 해당 토픽에 생성됩니다. - 60초 ack deadline, 7일 메시지 보존, 그리고 활성화된 메시지 순서 지정으로 구성됩니다.
- subscription 생성은 멱등적입니다. 즉, 파이프를 다시 시작하거나 레플리카가 다시 스케줄링될 때 이미 구성된 토픽을 가리키는 기존 subscription이 있으면 이를 재사용합니다.
- 토픽 디스커버리와 메시지 샘플링 중에는 ClickPipes가 수명이 짧은 ephemeral subscription(
clickpipes-discovery-{uuid})도 생성하며, 샘플링이 완료되면 즉시 삭제됩니다. - 파이프가 삭제되면 ClickPipes는 정리 과정의 일부로 관리형 subscription도 삭제합니다.
- JSON
- Avro — Pub/Sub 네이티브 스키마(BINARY 인코딩)를 통해 지원됩니다
- Protobuf — Pub/Sub 네이티브 스키마(BINARY 인코딩)를 통해 지원됩니다
- gzip
- zstd
- lz4
- snappy (프레임 형식)
자동 감지는 JSON과 같은 텍스트 기반 포맷에서 안전합니다. 출력 가능한 ASCII 문자는 압축 매직 바이트와 절대 충돌하지 않기 때문입니다. 압축 해제된 페이로드는 최대 64MB로 제한됩니다.
- 기본 숫자 타입 - [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(String, Int64, DateTime))을 수동으로 지정할 수 있습니다.
ClickPipes가 사용할 올바른 variant subtype을 판별하는 방식상, Variant 정의에는 정수 유형 또는 datetime 유형을 각각 하나만 사용할 수 있습니다.
예를 들어 Variant(Int64, UInt32)는 지원되지 않습니다.
항상 JSON 객체인 JSON 필드는 JSON 대상 컬럼에 할당할 수 있습니다. 고정되거나 건너뛴 경로를 포함해, 대상
컬럼은 원하는 JSON 타입으로 수동으로 변경해야 합니다.
다음 가상 컬럼은 Pub/Sub 토픽에서 지원됩니다. 새 대상 테이블을 만들 때 Add Column 버튼을 사용해 가상 컬럼을 추가할 수 있습니다.
_raw_message 필드는 전체 Pub/Sub 메시지 페이로드만 필요한 경우에 사용할 수 있습니다(예: ClickHouse JsonExtract* 함수를 사용해 후속 materialized view를 채우는 경우). 이러한 파이프의 경우 “non-virtual” 컬럼을 모두 삭제하면 ClickPipes 성능이 향상될 수 있습니다.
- DEFAULT는 지원되지 않습니다.
- 가장 작은 (XS) 레플리카 크기로 실행할 경우, 개별 메시지 크기는 기본적으로 16MB(비압축)로 제한되며 더 큰 레플리카에서는 32MB(비압축)로 제한됩니다. 이 한도를 초과하는 메시지는 오류와 함께 거부됩니다. 더 큰 메시지가 필요하면 지원팀에 문의하십시오.
- Pub/Sub subscription filter는 변경할 수 없습니다 — 필터 표현식을 변경하려면 파이프를 다시 생성해야 합니다.
- 필터는 메시지 페이로드가 아니라 메시지 속성에만 적용됩니다.
- 배치 크기가 최대 크기에 도달한 경우(100,000행 또는 레플리카 메모리 1GB당 32MB)
- 배치가 최대 시간(5초) 동안 열려 있었던 경우
_message_id 가상 컬럼을 사용해 다운스트림에서 중복을 제거하십시오(Pub/Sub의 각 메시지 ID는 토픽 내에서 고유합니다).