Справочник

Содержит сведения о поддерживаемых форматах, источниках, семантике доставки, аутентификации и экспериментальных возможностях Kafka ClickPipes.

​

Поддерживаемые источники данных

Название	Логотип	Тип	Статус	Описание
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.

​

Поддерживаемые форматы данных

Поддерживаются следующие форматы:

• JSON
• AvroConfluent
• Protobuf

​

Поддерживаемые типы данных

​

Стандартные типы

В настоящее время 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
• Map, где ключи и значения используют любой из перечисленных выше типов (включая Nullable)
• Tuple и Array, где элементы используют любой из перечисленных выше типов (включая Nullable; только один уровень вложенности)
• типы SimpleAggregateFunction (для пунктов назначения AggregatingMergeTree или SummingMergeTree)

​

Поддержка типа Variant

ClickPipes поддерживает тип Variant в следующих случаях:

• Union в Avro. Если ваша схема Avro содержит union с несколькими типами, отличными от null, ClickPipes определит подходящий тип Variant. В остальных случаях типы Variant для данных Avro не поддерживаются.
• Поля JSON. Вы можете вручную указать тип Variant (например, Variant(String, Int64, DateTime)) для любого поля JSON в исходном потоке данных. Сложные подтипы (arrays/maps/tuples) не поддерживаются. Кроме того, из-за особенностей того, как ClickPipes определяет нужный подтип варианта, в определении Variant можно использовать только один целочисленный тип или тип datetime — например, Variant(Int64, UInt32) не поддерживается.

​

Поддержка JSON-типа

ClickPipes поддерживает JSON-тип в следующих случаях:

• Поля Avro Record и Protobuf Message всегда можно назначить JSON-столбцу.
• Поля Avro String и Bytes можно назначить JSON-столбцу, если поле Avro фактически содержит объекты JSON, представленные в виде строк.
• Типы Protobuf String и Bytes можно назначить JSON-столбцу, если поле Protobuf фактически содержит объекты JSON, представленные в виде строк.
• Поля JSON, которые всегда содержат объект JSON, можно назначить целевому JSON-столбцу.

Обратите внимание, что вам потребуется вручную изменить целевой столбец на нужный JSON-тип, включая все фиксированные или пропущенные пути.

​

Avro

​

Поддерживаемые типы данных Avro

ClickPipes поддерживает все примитивные и составные типы Avro, а также все логические типы Avro, кроме local-timestamp-millis и local_timestamp-micros. Типы Avro record преобразуются в Tuple, типы array — в Array, а map — в Map (только со строковыми ключами). В общем случае доступны преобразования, перечисленные здесь. Мы рекомендуем использовать точное соответствие типов для числовых типов Avro, поскольку ClickPipes не проверяет переполнение или потерю точности при преобразовании типов. Также все типы Avro можно вставить в столбец String; в этом случае они будут представлены как корректная JSON-строка.

​

Типы Nullable и union в Avro

Типы Nullable в Avro определяются с помощью схемы Union вида (T, null) или (null, T), где T — базовый тип Avro. Во время определения схемы такие union будут сопоставляться со столбцом ClickHouse “Nullable”. Обратите внимание, что ClickHouse не поддерживает типы Nullable(Array), Nullable(Map) и Nullable(Tuple). Union с null в Avro для этих типов будут сопоставлены с версиями без Nullable (типы Avro Record сопоставляются с именованным Tuple в ClickHouse). Значения Avro “null” для этих типов будут вставлены как:

• пустой Array для null-массива Avro
• пустой Map для null-значения Avro Map
• именованный Tuple со всеми значениями по умолчанию/нулевыми значениями для null-Record Avro

​

Protobuf

​

Поддерживаемые типы данных Protobuf

ClickPipes поддерживает все типы Protobuf 2 и 3, за исключением давно устаревшего типа group из proto2. Для базовых преобразований типов используются следующие сопоставления:

Также поддерживаются варианты 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

Для числовых типов рекомендуется точное соответствие, чтобы избежать переполнения или потери точности.

Также поддерживаются следующие стандартные типы:

Стандартный тип	Тип 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, в котором не более одного поля содержит значение, отличное от значения по умолчанию. Эти поля также могут автоматически сопоставляться со столбцом Variant, где активное значение принимает тип того входящего поля, которое задано. Кроме того, каждое входящее поле можно вручную сопоставить с отдельным столбцом ClickHouse; поскольку поля oneof взаимоисключают друг друга, в каждой записи будет заполнен только один столбец.

​

Списки сообщений

Если схема Protobuf верхнего уровня, заданная для ClickPipe, содержит одно повторяющееся поле, которое само является сообщением Protobuf, то определение схемы и сопоставление столбцов будут выполняться на основе «вложенного» поля 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	Параллельный массив ключей в заголовках записи	Array(String)
_header_values	Параллельный массив заголовков в записи	Array(String)
_raw_message	Полное сообщение Kafka	String

Обратите внимание, что столбец _raw_message рекомендуется использовать только для данных JSON. В сценариях, где требуется только строка JSON (например, при использовании функций ClickHouse JsonExtract* для заполнения последующей materialized view), удаление всех «не виртуальных» столбцов может повысить производительность ClickPipes.