참고
지원되는 데이터 소스
| 이름 | Logo | 유형 | 상태 | 설명 |
|---|---|---|---|---|
| Apache Kafka | 스트리밍 | 안정 | ClickPipes를 구성해 Apache Kafka에서 ClickHouse Cloud로 스트리밍 데이터를 수집합니다. | |
| Confluent Cloud | 스트리밍 | 안정 | 직접 통합을 통해 Confluent와 ClickHouse Cloud의 결합된 성능을 활용합니다. | |
| Redpanda |  | 스트리밍 | 안정 | ClickPipes를 구성해 Redpanda에서 ClickHouse Cloud로 스트리밍 데이터를 수집합니다. |
| AWS MSK | 스트리밍 | 안정 | ClickPipes를 구성해 AWS MSK에서 ClickHouse Cloud로 스트리밍 데이터를 수집합니다. | |
| Azure Event Hubs | 스트리밍 | 안정 | ClickPipes를 구성해 Azure Event Hubs에서 ClickHouse Cloud로 스트리밍 데이터를 수집합니다. | |
| WarpStream | 스트리밍 | 안정 | ClickPipes를 구성해 WarpStream에서 ClickHouse Cloud로 스트리밍 데이터를 수집합니다. |
지원되는 데이터 형식
지원되는 데이터 형식은 다음과 같습니다:
지원되는 데이터 유형
표준
다음과 같은 표준 ClickHouse 데이터 타입이 현재 ClickPipes에서 지원됩니다:
- 기본 숫자 타입 - [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
- Time
- Time64
- JSON
- 모든 ClickHouse LowCardinality 타입
- 위의 타입(널 허용 포함)을 키와 값으로 사용하는 Map 타입
- 위의 타입(널 허용 포함)을 요소로 사용하는 Tuple 및 Array (깊이 1단계만)
- SimpleAggregateFunction 타입 (AggregatingMergeTree 또는 SummingMergeTree를 대상으로 하는 경우)
Variant 타입 지원
ClickPipes는 다음과 같은 경우 Variant 타입을 지원합니다:
- Avro Union. Avro 스키마에 여러 개의 null이 아닌 타입으로 구성된 union이 포함되어 있는 경우, ClickPipes가 적절한 Variant 타입을 추론합니다. 이 경우를 제외하면 Avro 데이터에는 Variant 타입이 지원되지 않습니다.
- JSON 필드. 소스 데이터 스트림의 모든 JSON 필드에 대해 수동으로 Variant 타입(예:
Variant(String, Int64, DateTime))을 지정할 수 있습니다. 복잡한 하위 타입(배열/맵/튜플)은 지원되지 않습니다. 또한 ClickPipes가 올바른 Variant 하위 타입을 결정하는 방식 때문에, Variant 정의 내에서는 정수형 또는 datetime 타입을 각각 하나만 사용할 수 있습니다. 예를 들어Variant(Int64, UInt32)는 지원되지 않습니다.
JSON 타입 지원
ClickPipes에서는 다음과 같은 경우 JSON 타입을 지원합니다.
- Avro Record 및 Protobuf Message 필드는 항상 JSON 컬럼에 지정할 수 있습니다.
- Avro String 및 Bytes 필드는 Avro 필드가 실제로 JSON String 객체를 포함하는 경우 JSON 컬럼에 지정할 수 있습니다.
- Protobuf String 및 Bytes kind는 Protobuf 필드가 실제로 JSON String 객체를 포함하는 경우 JSON 컬럼에 지정할 수 있습니다.
- 항상 JSON 객체인 JSON 필드는 JSON 대상 컬럼에 지정할 수 있습니다.
대상 컬럼은 고정 또는 건너뛴 경로를 포함하여, 원하는 JSON 타입으로 수동으로 변경해야 합니다.
Avro
지원되는 Avro 데이터 타입
ClickPipes는 모든 Avro Primitive 및 Complex 타입과, local-timestamp-millis, local_timestamp-micros를 제외한 모든 Avro Logical 타입을 지원합니다. Avro record 타입은 Tuple로, array 타입은 Array로, map 타입은 Map으로 변환됩니다(키는 문자열만 지원). 일반적으로 여기에 나열된 변환을 사용할 수 있습니다. ClickPipes는 타입 변환 시 오버플로 또는 정밀도 손실을 검사하지 않으므로, Avro 숫자 타입에 대해서는 가능한 한 정확히 일치하는 타입을 매핑하여 사용할 것을 권장합니다.
또는, 모든 Avro 타입을 String 컬럼에 삽입할 수 있으며, 이 경우 유효한 JSON 문자열로 표현됩니다.
Nullable types and Avro unions
Avro에서 널 허용(Nullable) 타입은 기본 Avro 타입 T에 대해 (T, null) 또는 (null, T) 형태의 Union 스키마를 사용하여 정의합니다. 스키마 추론(schema inference) 시 이러한 Union은 ClickHouse의 「Nullable」 컬럼으로 매핑됩니다. 단, ClickHouse는
Nullable(Array), Nullable(Map), Nullable(Tuple) 타입을 지원하지 않습니다. 이러한 타입에 대한 Avro null Union은 널 비허용(non-nullable) 버전으로 매핑됩니다(Avro Record 타입은 ClickHouse의 이름이 지정된 Tuple로 매핑됨). 이들 타입에 대한 Avro "null" 값은 다음과 같이 삽입됩니다:
- null Avro array의 경우 빈 Array
- null Avro Map의 경우 빈 Map
- null Avro Record의 경우 모든 값이 기본값/0인 이름이 지정된 Tuple
Protobuf
지원되는 Protobuf 데이터 타입
ClickPipes는 오래전에 폐기된 proto 2 group 타입을 제외한 모든 Protobuf 2 및 3 타입을 지원합니다. 기본 타입 변환은
다음과 같이 대응됩니다:
모든 기본 타입에 대한 Array, Map, Nullable 변형도 지원됩니다.
| Protobuf 타입 | ClickHouse 타입 |
|---|---|
bool | UInt8 |
float | Float32 |
double | Float64 |
int32, sint32, sfixed32 | Int32 |
int64, sint64, sfixed64 | Int64 |
uint32, fixed32 | UInt32 |
uint64, fixed64 | UInt64 |
string, bytes | String |
enum | Enum |
repeated T | Array(T) |
message | Tuple |
숫자 타입은 오버플로 또는 정밀도 손실을 방지하기 위해 정확히 일치시키는 것이 좋습니다.
다음 well-known types도 지원됩니다:
| well-known 타입 | ClickHouse 타입 |
|---|---|
google.protobuf.Timestamp | DateTime, DateTime64 |
google.protobuf.Duration | Time, Time64 |
google.protobuf.StringValue, google.protobuf.BytesValue | Nullable(String) |
google.protobuf.Int32Value, google.protobuf.SInt32Value, google.protobuf.SFixed32Value | Nullable(Int32) |
google.protobuf.Int64Value, google.protobuf.SInt64Value, google.protobuf.SFixed64Value | Nullable(Int64) |
google.protobuf.UInt32Value, google.protobuf.Fixed32Value | Nullable(UInt32) |
google.protobuf.UInt64Value, google.protobuf.Fixed64Value | Nullable(UInt64) |
google.protobuf.FloatValue | Nullable(Float32) |
google.protobuf.DoubleValue | Nullable(Float64) |
google.protobuf.BoolValue | Nullable(UInt8) |
Protobuf oneof
스키마 추론 시 Protobuf oneof 필드는 기본적으로 이름이 지정된 Tuple에 매핑되며, 이때 기본값이 아닌 값을 갖는 필드는 최대 1개뿐입니다.
이 필드들은 활성 값이 설정된 구성 필드의 유형을 갖는 Variant 컬럼으로 자동 매핑될 수도 있습니다.
또는 각 구성 필드를 각각 별도의 ClickHouse 컬럼에 수동으로 매핑할 수도 있습니다. oneof 필드는 상호 배타적이므로 레코드마다 값이 채워지는 컬럼은 하나뿐입니다.
메시지 목록
ClickPipe에 대해 정의된 최상위 Protobuf schema에 protobuf Message인 단일 repeated 필드가 포함된 경우, 스키마 추론과 컬럼 대응은 "포함된" Message 필드를 기준으로 이루어집니다. Kafka 메시지는 이러한 메시지의 목록으로 처리되며, 단일 Kafka 메시지는 여러 개의 ClickHouse 행으로 펼쳐집니다.
Kafka 가상 컬럼
다음 가상 컬럼이 Kafka 호환 스트리밍 데이터 소스에서 지원됩니다. 새 대상을 생성할 때 Add Column 버튼을 사용하여 대상 테이블에 가상 컬럼을 추가할 수 있습니다.
| Name | Description | Recommended Data Type |
|---|---|---|
_key | Kafka 메시지 키 | String |
_timestamp | Kafka 타임스탬프 (밀리초 단위 정밀도) | DateTime64(3) |
_partition | Kafka 파티션 | Int32 |
_offset | Kafka 오프셋 | Int64 |
_topic | Kafka 토픽 | String |
_header_keys | 레코드 헤더(Headers)에 포함된 키의 병렬 배열 | Array(String) |
_header_values | 레코드 헤더(Headers)에 포함된 헤더 값의 병렬 배열 | Array(String) |
_raw_message | 전체 Kafka 메시지 | String |
_raw_message 컬럼은 JSON 데이터에만 사용하는 것을 권장합니다.
JSON 문자열만 필요한 사용 사례(예: ClickHouse JsonExtract* 함수를 사용하여
다운스트림 materialized view를 채우는 경우)에서는, 모든 "비-가상(non-virtual)" 컬럼을 삭제하는 것이 ClickPipes 성능 향상에 도움이 될 수 있습니다.
