Skip to main content

​
지원되는 데이터 소스

​
격리 수준

Kafka consumer의 격리 수준은 ClickPipe가 Kafka 트랜잭션에서 커밋된 메시지만 읽고 삽입할지 여부를 결정합니다. kafka_read_committed 설정을 활성화하면 read_committed를 사용하여 중단된 Kafka 트랜잭션의 메시지를 건너뜁니다. 비활성화하면 read_uncommitted를 사용하여 모든 메시지를 읽습니다. 이 설정은 고급 설정에서 구성할 수 있습니다.

​
지원되는 데이터 포맷

지원되는 포맷은 다음과 같습니다:

​
지원되는 데이터 타입

​
표준

현재 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
  • Time, Time64
  • JSON
  • 모든 ClickHouse LowCardinality 타입
  • 위 타입 중 임의의 타입을 키와 값으로 사용하는 맵(널 허용 포함)
  • 위 타입 중 임의의 타입을 요소로 사용하는 Tuple 및 배열(널 허용 포함, 1단계 깊이만 지원)
  • SimpleAggregateFunction 타입(AggregatingMergeTree 또는 SummingMergeTree 대상에 사용)

​
Variant 타입 지원

ClickPipes는 다음과 같은 경우에 Variant 타입을 지원합니다:
  • Avro Unions. Avro 스키마에 여러 non-null 타입을 포함하는 유니온이 있으면 ClickPipes가 적절한 Variant 타입을 추론합니다. Avro 데이터에서는 이 경우 외에는 Variant 타입이 지원되지 않습니다.
  • JSON 필드. 소스 데이터 스트림의 JSON 필드에 대해 Variant 타입(예: Variant(String, Int64, DateTime))을 수동으로 지정할 수 있습니다. 복잡한 하위 타입(배열/맵/튜플)은 지원되지 않습니다. 또한 ClickPipes가 사용할 올바른 Variant 하위 타입을 결정하는 방식 때문에 Variant 정의에서는 integer 또는 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는 local-timestamp-millis 및 local_timestamp-micros를 제외한 모든 Avro Primitive 및 Complex 타입과 모든 Avro Logical 타입을 지원합니다. Avro record 타입은 Tuple로, array 타입은 배열로, map 타입은 맵으로(문자열 키만 지원) 변환됩니다. 일반적으로 여기에 나열된 변환을 사용할 수 있습니다. ClickPipes는 타입 변환 시 오버플로우나 정밀도 손실을 검사하지 않으므로, Avro 숫자 타입에는 정확히 일치하는 타입을 사용하는 것이 좋습니다. 또는 모든 Avro 타입을 String 컬럼에 삽입할 수 있으며, 이 경우 유효한 JSON 문자열로 표현됩니다.

​
널 허용 타입과 Avro 유니온

Avro에서 널 허용 타입은 T가 기본 Avro 타입일 때 (T, null) 또는 (null, T) 형태의 Union 스키마를 사용해 정의됩니다. 스키마 추론 중 이러한 유니온은 ClickHouse의 “Nullable” 컬럼으로 매핑됩니다. ClickHouse는 Nullable(Array), Nullable(Map), Nullable(Tuple) 타입을 지원하지 않는다는 점에 유의하십시오. 이러한 타입에 대한 Avro null 유니온은 null을 허용하지 않는 버전으로 매핑됩니다(Avro Record 타입은 ClickHouse의 named tuple로 매핑됩니다). 이러한 타입의 Avro “null” 값은 다음과 같이 삽입됩니다:
  • null Avro 배열의 경우 빈 배열
  • null Avro 맵의 경우 빈 맵
  • null Avro Record의 경우 모든 값이 기본값/0으로 채워진 named tuple

​
Protobuf

​
지원되는 Protobuf 데이터 타입

ClickPipes는 오래전에 사용 중단된 proto 2 group 타입을 제외한 모든 Protobuf 2 및 3 타입을 지원합니다. 기본 타입 변환에는 다음 매핑을 사용합니다:
모든 기본 타입에 대한 Array, Map, Nullable 변형도 지원합니다.
숫자 타입은 오버플로우나 정밀도 손실을 방지하기 위해 정확히 일치시키는 것이 좋습니다.
다음 well-known types도 지원합니다:

​
Protobuf oneof

스키마 추론 시 Protobuf oneof 필드는 기본적으로 이름이 있는 Tuple에 매핑되며, 이 경우 기본값이 아닌 값을 갖는 필드는 최대 하나뿐입니다. 이러한 필드는 설정된 구성 필드에 따라 활성 값의 유형이 결정되는 Variant 컬럼으로 자동 매핑될 수도 있습니다. 또는 각 구성 필드를 각각 별도의 ClickHouse 컬럼에 수동으로 매핑할 수도 있습니다. oneof 필드는 서로 배타적이므로 레코드마다 실제로 값이 채워지는 컬럼은 하나뿐입니다.

​
메시지 목록

ClickPipe에 대해 정의된 최상위 Protobuf 스키마에 protobuf Message인 단일 반복 필드가 하나만 포함된 경우, 스키마 추론과 컬럼 매핑은 “포함된” Message 필드를 기준으로 수행됩니다. Kafka 메시지는 이러한 메시지의 목록으로 처리되며, 단일 Kafka 메시지는 여러 개의 ClickHouse 행으로 풀어집니다.

​
Kafka 가상 컬럼

다음 가상 컬럼은 Kafka 호환 스트리밍 데이터 소스에서 지원됩니다. 새 대상을 만들 때 Add Column 버튼을 사용하여 가상 컬럼을 대상 테이블에 추가할 수 있습니다. _raw_message 컬럼은 JSON 데이터에만 사용하는 것을 권장합니다. JSON 문자열만 필요한 사용 사례(예: ClickHouse JsonExtract* 함수를 사용하여 다운스트림 materialized view를 채우는 경우)에서는 모든 “비가상” 컬럼을 삭제하면 ClickPipes 성능이 향상될 수 있습니다.

​
구조화된 메시지 키

_key를 String 컬럼에 매핑하면 원본 Kafka 메시지 키가 저장됩니다. 이 매핑에서는 키 디코딩 및 스키마 조회를 수행하지 않습니다. 구조화된 키에서 필드를 추출하려면 _key.로 시작하는 소스 필드를 매핑하십시오. 예를 들어 JSON 키 {"customer":{"id":42}}에서는 _key.customer.id를 customer_id와 같은 대상 컬럼에 매핑합니다. _key.* 매핑이나 String 이외의 타입으로 직접 _key를 매핑하는 경우, ClickPipes는 먼저 구성된 스키마 레지스트리를 사용해 키가 인코딩되었는지 확인합니다. 그렇지 않으면 키가 JSON 객체인지 확인합니다. 레지스트리로 인코딩된 키는 레코드 값과 동일한 포맷 및 레지스트리 계열을 사용해야 하지만, 스키마 ID는 달라도 됩니다. 키 스키마 변경은 자동으로 감지됩니다. 디코딩이 활성화된 경우 원시 키, JSON 스칼라 또는 배열, 잘못된 형식의 JSON은 중첩 키 필드를 채우지 않으며, 해당 대상 컬럼에는 타입 기본값이 적용됩니다. ClickPipes가 레지스트리로 인코딩된 키를 인식했지만 스키마를 가져오거나 적용할 수 없는 경우 Kafka 레코드를 ClickPipes error table에 기록합니다. Avro 키는 primitive, 배열, 맵 또는 fixed 타입과 같은 비레코드 루트 스키마를 사용할 수도 있습니다. 이를 디코딩하려면 _key를 String 이외의 호환되는 대상 타입에 직접 매핑하십시오. 비레코드 스키마는 중첩 키 필드를 채울 수 없습니다.
마지막 수정일 2026년 8월 18일