Skip to main content
يجب استخدام هذا connector فقط إذا كانت بياناتك بسيطة وتتكون من data types بدائية، مثل int. أما الأنواع الخاصة بـ ClickHouse، مثل maps، فهي غير مدعومة.
في أمثلتنا، نستخدم توزيعة Confluent الخاصة بـ Kafka Connect. فيما يلي نشرح عملية تثبيت بسيطة، تتضمن سحب الرسائل من موضوع Kafka واحد وإدراج rows في ClickHouse table. نوصي باستخدام Confluent Cloud، إذ توفّر فئة مجانية سخية لمن لا يملكون بيئة Kafka. لاحظ أن وجود مخطط مطلوب لاستخدام موصل JDBC (فلا يمكنك استخدام JSON أو CSV عاديَّين مع JDBC connector). ورغم أنه يمكن ترميز مخطط داخل كل رسالة، فإنه يُنصح بشدة باستخدام Confluent schema registry لتجنّب الـ overhead المرتبط بذلك. يقوم برنامج الإدراج النصي المرفق تلقائيًا باستنتاج مخطط من الرسائل وإدراجها في registry، لذا يمكن إعادة استخدام هذا البرنامج النصي مع datasets أخرى. ويُفترض أن keys في Kafka هي من النوع Strings. ويمكن العثور على مزيد من التفاصيل حول schemas في Kafka هنا.

الترخيص

يُوزَّع موصل JDBC بموجب Confluent Community License

الخطوات

اجمع بيانات الاتصال الخاصة بك

للاتصال بـ ClickHouse باستخدام HTTP(S)، تحتاج إلى المعلومات التالية: تتوفر تفاصيل خدمة ClickHouse Cloud الخاصة بك في ClickHouse Cloud console. حدِّد خدمة ثم انقر على Connect:
زر Connect لخدمة ClickHouse Cloud
اختر HTTPS. ستظهر تفاصيل الاتصال في مثال لأمر curl.
تفاصيل اتصال HTTPS لخدمة ClickHouse Cloud
إذا كنت تستخدم ClickHouse مُدارًا ذاتيًا، فسيُحدِّد مسؤول ClickHouse لديك تفاصيل الاتصال.
1

تثبيت Kafka Connect والموصل

نفترض أنك قمت بتنزيل حزمة Confluent وتثبيتها محليًا. اتبع تعليمات التثبيت الخاصة بتثبيت الموصل كما هو موثّق هنا.إذا كنت تستخدم طريقة التثبيت confluent-hub، فسيتم تحديث ملفات التهيئة المحلية لديك.لإرسال البيانات إلى ClickHouse من Kafka، نستخدم مكوّن Sink الخاص بالموصل.
2

تنزيل برنامج تشغيل JDBC وتثبيته

نزّل وثبّت برنامج تشغيل ClickHouse JDBC ‏clickhouse-jdbc-<version>-shaded.jar من هنا. ثبّته في Kafka Connect باتباع التفاصيل الواردة هنا. قد تعمل برامج تشغيل أخرى، لكنها لم تُختبر.
مشكلة شائعة: تقترح الوثائق نسخ ملف jar إلى share/java/kafka-connect-jdbc/. إذا واجهت مشكلات في عثور Connect على برنامج التشغيل، فانسخ برنامج التشغيل إلى share/confluent-hub-components/confluentinc-kafka-connect-jdbc/lib/. أو عدّل plugin.path ليشمل برنامج التشغيل — انظر أدناه.
3

إعداد التهيئة

اتبع هذه التعليمات لإعداد Connect بما يناسب نوع التثبيت لديك، مع الانتباه إلى الفروق بين عنقود مستقل وعنقود موزّع. وإذا كنت تستخدم Confluent Cloud، فالإعداد الموزّع هو المناسب.المعلمات التالية مهمة عند استخدام موصل JDBC مع ClickHouse. ويمكن العثور على قائمة كاملة بالمعلمات هنا:
  • _connection.url_ - يجب أن يكون بالصيغة jdbc:clickhouse://&lt;clickhouse host>:&lt;clickhouse http port>/&lt;target database>
  • connection.user - مستخدم لديه صلاحية الكتابة إلى قاعدة البيانات الهدف
  • table.name.format- جدول ClickHouse الذي ستُدرج البيانات فيه. يجب أن يكون موجودًا.
  • batch.size - عدد الصفوف التي تُرسل في batch واحد. احرص على ضبطه على قيمة كبيرة بما يكفي. ووفقًا لتوصيات ClickHouse، ينبغي اعتبار القيمة 1000 حدًا أدنى.
  • tasks.max - يدعم موصل JDBC Sink تشغيل task واحد أو أكثر. ويمكن استخدام ذلك لتحسين الأداء. وإلى جانب حجم batch، يُعد هذا وسيلتك الأساسية لتحسين الأداء.
  • value.converter.schemas.enable - اضبطه على false إذا كنت تستخدم مخطط registry، وعلى true إذا كنت تضمن مخططات داخل الرسائل.
  • value.converter - اضبطه وفقًا لنوع بياناتك، فمثلًا بالنسبة إلى JSON استخدم io.confluent.connect.json.JsonSchemaConverter.
  • key.converter - اضبطه على org.apache.kafka.connect.storage.StringConverter. نحن نستخدم مفاتيح String.
  • pk.mode - غير ذي صلة بـ ClickHouse. اضبطه على none.
  • auto.create - غير مدعوم ويجب أن تكون قيمته false.
  • auto.evolve - نوصي باستخدام false لهذا الإعداد، رغم أنه قد يصبح مدعومًا مستقبلًا.
  • insert.mode - اضبطه على “insert”. الأوضاع الأخرى غير مدعومة حاليًا.
  • key.converter - اضبطه وفقًا لأنواع مفاتيحك.
  • value.converter - اضبطه بناءً على نوع البيانات في topic لديك. ويجب أن تكون هذه البيانات ذات مخطط مدعوم — بتنسيقات JSON أو Avro أو Protobuf.
إذا كنت تستخدم dataset التجريبي الخاص بنا للاختبار، فتأكد من ضبط ما يلي:
  • value.converter.schemas.enable - اضبطه على false لأننا نستخدم مخطط registry. واضبطه على true إذا كنت تضمن مخطط داخل كل رسالة.
  • key.converter - اضبطه على “org.apache.kafka.connect.storage.StringConverter”. نحن نستخدم مفاتيح String.
  • value.converter - اضبطه على “io.confluent.connect.json.JsonSchemaConverter”.
  • value.converter.schema.registry.url - اضبط URL لخادم مخطط، إلى جانب بيانات الاعتماد الخاصة به، عبر المعلمة value.converter.schema.registry.basic.auth.user.info.
يمكن العثور على ملفات تهيئة نموذجية لبيانات Github التجريبية هنا، على افتراض أن Connect يعمل في وضع مستقل وأن Kafka مستضاف في Confluent Cloud.
4

إنشاء جدول ClickHouse

تأكد من إنشاء الجدول، مع حذفه إذا كان موجودًا بالفعل نتيجة أمثلة سابقة. يرد أدناه مثال متوافق مع مجموعة بيانات Github المختصرة. لاحظ عدم وجود أي من النوعين Array أو Map لأنهما غير مدعومين حاليًا:
5

ابدأ تشغيل Kafka Connect

ابدأ Kafka Connect في وضع مستقل أو موزّع.
6

أضف بيانات إلى Kafka

أرسل الرسائل إلى Kafka باستخدام البرنامج النصي وملف التهيئة المتوفرين. ستحتاج إلى تعديل github.config ليتضمن بيانات اعتماد Kafka الخاصة بك. والبرنامج النصي مُهيّأ حاليًا للاستخدام مع Confluent Cloud.
يمكن استخدام هذا البرنامج النصي لإدراج أي ملف ndjson في Kafka topic. وسيحاول هذا استنتاج مخطط لك تلقائيًا. لن تُدرج التهيئة النموذجية المتوفرة سوى 10k رسالة فقط - عدّل هنا إذا لزم الأمر. كما تزيل هذه التهيئة أي حقول Array غير متوافقة من dataset أثناء إدراجها في Kafka.وهذا مطلوب لكي يتمكن موصل JDBC من تحويل الرسائل إلى عبارات INSERT. وإذا كنت تستخدم بياناتك الخاصة، فتأكد إما من إدراج مخطط مع كل رسالة (بضبط _value.converter.schemas.enable _على true) أو من أن عميلك ينشر رسائل تشير إلى مخطط في registry.يجب أن يبدأ Kafka Connect في استهلاك الرسائل وإدراج الصفوف في ClickHouse. لاحظ أن التحذيرات المتعلقة بـ “[JDBC Compliant Mode] Transaction isn’t supported.” متوقعة ويمكن تجاهلها.يجب أن تؤكد قراءة بسيطة من الجدول الهدف “Github” إدراج البيانات.
آخر تعديل في ٢٣ يوليو ٢٠٢٦