مرجع

يتناول بالتفصيل التنسيقات والمصادر ودلالات التسليم والمصادقة والميزات التجريبية التي يدعمها 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

​

أنواع البيانات المدعومة

​

الأنواع القياسية

أنواع بيانات ClickHouse القياسية التالية مدعومة حاليًا في ClickPipes:

• الأنواع الرقمية الأساسية - [U]Int8/16/32/64 و Float32/64 و BFloat16
• أنواع الأعداد الصحيحة الكبيرة - [U]Int128/256
• Decimal Types
• Boolean
• String
• FixedString
• Date و Date32
• DateTime و DateTime64 (مناطق زمنية UTC فقط)
• Enum8/Enum16
• معرّف UUID
• IPv4
• IPv6
• Time و Time64
• JSON
• جميع أنواع LowCardinality في ClickHouse
• Map بمفاتيح وقيم تستخدم أيًا من الأنواع المذكورة أعلاه (بما في ذلك Nullable)
• Tuple و Array بعناصر تستخدم أيًا من الأنواع المذكورة أعلاه (بما في ذلك Nullable، وبعمق مستوى واحد فقط)
• أنواع SimpleAggregateFunction (لوجهات AggregatingMergeTree أو SummingMergeTree)

​

دعم نوع Variant

يدعم ClickPipes نوع Variant في الحالات التالية:

• اتحادات Avro. إذا كان مخطط Avro لديك يحتوي على union يضم عدة أنواع غير NULL، فسيستنتج ClickPipes نوع Variant المناسب. بخلاف ذلك، لا تكون أنواع Variant مدعومة في بيانات Avro.
• حقول JSON. يمكنك تحديد نوع Variant يدويًا (مثل Variant(String, Int64, DateTime)) لأي حقل JSON في مصدر تدفق البيانات. لا تُدعَم الأنواع الفرعية المعقدة (arrays/maps/tuples). بالإضافة إلى ذلك، ونظرًا للطريقة التي يحدد بها ClickPipes النوع الفرعي الصحيح من Variant الذي يجب استخدامه، لا يمكن استخدام أكثر من نوع عدد صحيح واحد أو نوع DateTime واحد في تعريف Variant — على سبيل المثال، 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 هذه بعمود “Nullable” في ClickHouse. لاحظ أن ClickHouse لا يدعم الأنواع Nullable(Array) وNullable(Map) وNullable(Tuple). ستُحوَّل اتحادات null في Avro لهذه الأنواع إلى إصدارات غير Nullable (وتُحوَّل أنواع Avro Record إلى named Tuple في ClickHouse). وستُدرَج قيم Avro “nulls” لهذه الأنواع على النحو التالي:

• Array فارغة لصفيف Avro null
• Map فارغة لـ Avro Map null
• named Tuple تحتوي على جميع القيم الافتراضية/الصفرية لـ Avro Record null

​

Protobuf

​

أنواع بيانات Protobuf المدعومة

يدعم ClickPipes جميع أنواع Protobuf 2 و3، باستثناء النوع group في proto 2، وهو نوع أُعلن عن إهماله منذ وقت طويل. وتستخدم تحويلات الأنواع الأساسية عمليات التحويل التالية:

تتوفّر أيضًا متغيرات 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

بالنسبة إلى الأنواع الرقمية، يُوصى باستخدام تطابق تام لتجنّب overflow أو فقدان precision.

الأنواع الشائعة المعروفة التالية مدعومة أيضًا:

النوع الشائع المعروف	نوع 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، فسيعتمد استنتاج المخطط وتعيين الأعمدة على حقل الرسالة “المضمَّنة”. وستُعالَج رسالة Kafka على أنها قائمة من هذه الرسائل، كما ستُفكَّك رسالة Kafka واحدة إلى عدة صفوف في ClickHouse.

​

الأعمدة الافتراضية في Kafka

الأعمدة الافتراضية التالية مدعومة لمصادر البيانات المتدفقة المتوافقة مع Kafka. عند إنشاء وجهة جديدة، يمكن إضافة الأعمدة الافتراضية إلى الجدول الهدف باستخدام الزر Add Column.

الاسم	الوصف	نوع البيانات الموصى به
_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* من أجل ملء عرض مادي لاحق)، قد يؤدي حذف جميع الأعمدة “غير الافتراضية” إلى تحسين أداء ClickPipes.