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: اختر HTTPS. ستظهر تفاصيل الاتصال في مثال لأمر curl. إذا كنت تستخدم ClickHouse مُدارًا ذاتيًا، فسيُحدِّد مسؤول ClickHouse لديك تفاصيل الاتصال.

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

نفترض أنك قمت بتنزيل حزمة Confluent وتثبيتها محليًا. اتبع تعليمات التثبيت الخاصة بالموصل كما هو موثّق هنا. إذا كنت تستخدم أسلوب التثبيت confluent-hub، فسيتم تحديث ملفات التكوين المحلية لديك. لإرسال البيانات من Kafka إلى ClickHouse، نستخدم مكوّن 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. وسيحاول استنتاج مخطط لك تلقائيًا. لن تُدرج التهيئة النموذجية المقدمة سوى 10 آلاف رسالة فقط - عدّل هنا إذا لزم الأمر. كما تزيل هذه التهيئة أي حقول Array غير متوافقة من مجموعة البيانات أثناء إدخالها إلى Kafka. وهذا مطلوب لكي يتمكن موصل JDBC من تحويل الرسائل إلى تعليمات INSERT. إذا كنت تستخدم بياناتك الخاصة، فتأكد إما من إدراج مخطط مع كل رسالة (بضبط _value.converter.schemas.enable _على true) أو من أن العميل لديك ينشر رسائل تشير إلى مخطط في السجل. يجب أن يبدأ Kafka Connect في استهلاك الرسائل وإدراج صفوف في ClickHouse. لاحظ أن التحذيرات المتعلقة بـ “[JDBC Compliant Mode] Transaction isn’t supported.” متوقعة ويمكن تجاهلها. ينبغي أن تؤكد قراءة بسيطة للجدول الهدف “Github” إدراج البيانات.
آخر تعديل في ٢٩ يونيو ٢٠٢٦