Kinesis ClickPipes는 ClickPipes UI를 통해 수동으로 배포하고 관리할 수 있으며, OpenAPI 및 Terraform을 통해 프로그래밍 방식으로도 배포하고 관리할 수 있습니다.
ClickPipes 소개를 숙지하고 IAM 자격 증명 또는 IAM Role을 설정해 두어야 합니다. ClickHouse Cloud에서 사용할 역할을 설정하는 방법은 Kinesis 역할 기반 접근 가이드를 참조하십시오.
- ClickHouse Cloud 서비스의 SQL 콘솔에 접속합니다.
- 왼쪽 메뉴에서
Data Sources 버튼을 선택한 다음 “Set up a ClickPipe”를 클릭합니다.
- 데이터 소스를 선택합니다.
- ClickPipe 이름, 설명(선택 사항), IAM 역할 또는 자격 증명, 기타 연결 정보를 입력하여 양식을 작성합니다.
- Kinesis 스트림과 시작 오프셋을 선택합니다. UI에는 선택한 소스(Kafka topic 등)의 샘플 문서가 표시됩니다. Kinesis 스트림의 경우 Enhanced Fan-out을 활성화해 ClickPipe의 성능과 안정성을 높일 수도 있습니다(Enhanced Fan-out에 대한 자세한 내용은 여기에서 확인할 수 있습니다).
- 다음 단계에서는 데이터를 새 ClickHouse 테이블로 수집할지, 기존 테이블을 재사용할지 선택할 수 있습니다. 화면의 안내에 따라 테이블 이름, 스키마, 설정을 수정하십시오. 상단의 샘플 테이블에서 변경 사항을 실시간 미리보기로 확인할 수 있습니다.
제공된 컨트롤을 사용해 고급 설정을 사용자 지정할 수도 있습니다.
- 또는 데이터를 기존 ClickHouse 테이블로 수집하도록 선택할 수도 있습니다. 이 경우 UI에서 소스 필드를 선택한 대상 테이블의 ClickHouse 필드에 매핑할 수 있습니다.
- 마지막으로 내부 ClickPipes 사용자에 대한 권한을 구성할 수 있습니다.
권한: ClickPipes는 대상 테이블에 데이터를 쓰기 위한 전용 사용자를 생성합니다. 이 내부 사용자에게 사용자 지정 역할 또는 미리 정의된 역할 중 하나를 선택할 수 있습니다.
Full access: cluster 전체에 대한 권한입니다. 대상 테이블과 함께 구체화된 뷰(Materialized View) 또는 딕셔너리(Dictionary)를 사용하는 경우 유용할 수 있습니다.
Only destination table: 대상 테이블에 대해서만 INSERT 권한을 부여합니다.
- “Complete Setup”을 클릭하면 시스템이 ClickPipe를 등록하고, 요약 테이블에 표시되는 것을 확인할 수 있습니다.
요약 테이블에서는 소스 또는 ClickHouse의 대상 테이블에서 샘플 데이터를 표시하는 컨트롤을 제공합니다.
또한 ClickPipe를 제거하고 수집 작업의 요약을 표시하는 컨트롤도 제공합니다.
- 축하합니다! 첫 번째 ClickPipe 설정을 성공적으로 완료했습니다. 스트리밍 ClickPipe인 경우 원격 데이터 소스의 데이터를 실시간으로 계속 수집합니다. 그렇지 않은 경우 배치를 수집한 후 완료됩니다.
지원되는 포맷은 다음과 같습니다:
Kinesis용 ClickPipes는 압축된 레코드를 자동으로 감지하고 압축을 해제합니다. Kafka와 달리 Kafka에서는 클라이언트 라이브러리가 압축 해제를 투명하게 처리하지만, Kinesis는 raw 바이트를 그대로 전달하므로 ClickPipes가 별도 구성 없이 이를 처리합니다.
지원되는 압축 코덱은 다음과 같습니다:
- gzip
- zstd
- lz4
- snappy (framed format)
압축은 각 레코드의 매직 바이트를 기반으로 자동 감지됩니다. 알려진 압축 시그니처가 발견되지 않으면 해당 레코드는 비압축 상태로 처리됩니다. 감지된 압축 유형은 스키마 추론 과정에서도 표시되므로 UI의 샘플 데이터 미리보기에는 압축 해제된 데이터가 올바르게 표시됩니다.
JSON 및 CSV 같은 텍스트 기반 포맷에서는 자동 감지가 안전합니다. 인쇄 가능한 ASCII 문자는 압축 매직 바이트와 절대 충돌하지 않기 때문입니다.
- 기본 숫자 타입 - [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 타입
- 키와 값에 위 타입 중 하나를 사용할 수 있는 Map (Nullable 포함)
- 요소에 위 타입 중 하나를 사용할 수 있는 Tuple 및 Array (Nullable 포함, 1단계 깊이만)
- SimpleAggregateFunction 타입 (대상이 AggregatingMergeTree 또는 SummingMergeTree인 경우)
소스 데이터 스트림의 모든 JSON 필드에 대해 Variant 유형(예: Variant(String, Int64, DateTime))을 수동으로 지정할 수
있습니다. ClickPipes가 사용할 올바른 Variant 하위 유형을 판별하는 방식상, Variant 정의에는 정수형 또는 날짜/시간
유형을 하나만 사용할 수 있습니다. 예를 들어 Variant(Int64, UInt32)는 지원되지 않습니다.
항상 JSON 객체 형태인 JSON 필드는 JSON 대상 컬럼에 할당할 수 있습니다. 원하는 JSON 타입으로 대상
컬럼을 수동으로 변경해야 하며, 여기에는 고정 경로와 건너뛸 경로도 포함됩니다.
다음 가상 컬럼은 Kinesis 스트림에서 지원됩니다. 새 대상 테이블을 만들 때 Add Column 버튼을 사용해 가상 컬럼을 추가할 수 있습니다.
| 이름 | 설명 | 권장 데이터 타입 |
|---|
| _key | Kinesis 파티션 키 | String |
| _timestamp | Kinesis 대략적 수신 타임스탬프(밀리초 정밀도) | DateTime64(3) |
| _stream | Kinesis 스트림 이름 | String |
| _sequence_number | Kinesis 시퀀스 번호 | String |
| _raw_message | 전체 Kinesis 메시지 | String |
_raw_message 필드는 전체 Kinesis JSON 레코드만 필요한 경우(예: ClickHouse JsonExtract* 함수를 사용해 다운스트림 구체화된 뷰(Materialized View)를 채우는 경우)에 사용할 수 있습니다. 이러한 파이프에서는 “가상”이 아닌 모든 컬럼을 삭제하면 ClickPipes 성능이 향상될 수 있습니다.
- DEFAULT는 지원되지 않습니다.
- 가장 작은 (XS) 레플리카 크기에서는 개별 메시지의 기본 한도가 8MB(비압축)이며, 더 큰 레플리카에서는 16MB(비압축)입니다. 이 한도를 초과하는 메시지는 오류가 발생하며 거부됩니다. 더 큰 메시지가 필요하면 지원팀에 문의하십시오.
ClickPipes는 데이터를 배치 단위로 묶어 ClickHouse에 삽입합니다. 이는 데이터베이스에 파트가 과도하게 생성되어 클러스터 성능 문제가 발생하는 것을 방지하기 위한 것입니다.
다음 기준 중 하나를 충족하면 배치가 삽입됩니다:
- 배치 크기가 최대 크기(100,000행 또는 레플리카 메모리 1GB당 32MB)에 도달함
- 배치가 최대 시간(5초) 동안 열려 있음
지연 시간(즉, Kinesis 메시지가 stream으로 전송된 시점부터 해당 메시지를 ClickHouse에서 사용할 수 있게 될 때까지의 시간)은 여러 요인(예: Kinesis 지연 시간, 네트워크 지연 시간, 메시지 크기/포맷)에 따라 달라집니다. 또한 위 섹션에서 설명한 배칭도 지연 시간에 영향을 줍니다. 예상되는 지연 시간을 파악하려면 실제 사용 사례에 맞춰 테스트해 보실 것을 항상 권장합니다.
낮은 지연 시간에 대한 구체적인 요구 사항이 있으면 문의해 주세요.
동시에 활성 상태인 세그먼트 수는 처리량 요구 사항에 맞게 제한할 것을 강력히 권장합니다. “On Demand” Kinesis 스트림의 경우 AWS가 처리량에 따라 이에 맞는 수의 세그먼트를 자동으로 할당합니다.
반면 “Provisioned” 스트림에서는 세그먼트를 너무 많이 프로비저닝하면 아래 설명처럼 지연 시간이 발생할 수 있으며, 이러한 스트림에 대한 Kinesis 요금은 “세그먼트당” 부과되므로 비용도 증가합니다.
프로듀서 애플리케이션이 많은 수의 활성 세그먼트에 지속적으로 쓰기 작업을 수행하면, 해당 세그먼트를 효율적으로 처리할 수 있을 만큼 파이프가 충분히 확장되지 않은 경우 지연 시간이 발생할 수 있습니다. Kinesis 처리량 제한에 따라,
ClickPipes는 세그먼트 데이터를 읽기 위해 레플리카당 정해진 수의 “worker”를 할당합니다. 예를 들어 가장 작은 크기에서는 ClickPipes 레플리카 하나에 이러한 worker 스레드가 4개 있습니다. 프로듀서가
동시에 4개를 초과하는 세그먼트에 쓰기 작업을 수행하면, worker 스레드를 사용할 수 있을 때까지 “추가” 세그먼트의 데이터는 처리되지 않습니다. 특히 파이프가 “enhanced fanout”을 사용하는 경우, 각 worker 스레드는
단일 세그먼트를 5분 동안 구독하며 그 시간 동안 다른 세그먼트를 읽을 수 없습니다. 이로 인해 5분 단위의 지연 시간 “스파이크”가 발생할 수 있습니다.
Kinesis용 ClickPipes는 수평 및 수직 방향 모두로 스케일링할 수 있도록 설계되었습니다. 기본적으로 컨슈머 1개를 포함하는 컨슈머 그룹을 생성합니다. 이 설정은 ClickPipe 생성 시 구성할 수 있으며, 이후에도 설정 -> 고급 설정 -> 스케일링에서 언제든지 변경할 수 있습니다.
ClickPipes는 가용 영역에 분산된 아키텍처를 통해 고가용성을 제공합니다.
이를 위해서는 최소 2개의 컨슈머로 스케일링해야 합니다.
실행 중인 컨슈머 수와 관계없이 장애 허용은 설계상 기본적으로 제공됩니다.
컨슈머 또는 해당 기반 infrastructure에 장애가 발생하면,
ClickPipe가 자동으로 컨슈머를 다시 시작하고 메시지 처리를 계속합니다.
Amazon Kinesis 스트림에 액세스하려면 IAM 자격 증명 또는 IAM Role을 사용할 수 있습니다. IAM Role 설정 방법에 대한 자세한 내용은 ClickHouse Cloud에서 사용할 수 있는 역할을 설정하는 방법을 설명한 이 가이드를 참조하십시오. 
