Skip to main content
يتيح هذا المحرك دمج ClickHouse مع NATS. يتيح لك NATS ما يلي:
  • نشر subject الرسائل أو الاشتراك فيها.
  • معالجة الرسائل الجديدة عند توفرها.

إنشاء جدول

المعلمات المطلوبة:
  • nats_urlhost:port (على سبيل المثال، localhost:4222)..
  • nats_subjects – قائمة بالـ subject التي يشترك فيها جدول NATS أو ينشر إليها. يدعم subject أحرف البدل مثل foo.*.bar أو baz.>
  • nats_format – تنسيق الرسالة. يستخدم الصياغة نفسها المستخدمة في دالة SQL FORMAT، مثل JSONEachRow. لمزيد من المعلومات، راجع قسم التنسيقات.
المعلمات الاختيارية:
  • nats_schema – معلمة يجب استخدامها إذا كان التنسيق يتطلب تعريف schema. على سبيل المثال، يتطلب Cap’n Proto مسار ملف schema واسم الكائن الجذر schema.capnp:Message.
  • nats_stream – اسم stream موجود في NATS JetStream.
  • nats_consumer_name – اسم durable pull مستهلك موجود في NATS JetStream.
  • nats_num_consumers – عدد الـ مستهلكين لكل جدول. القيمة الافتراضية: 1. حدِّد عددًا أكبر من الـ مستهلكين إذا كان معدل النقل لمستهلك واحد غير كافٍ في NATS core فقط.
  • nats_queue_group – اسم مجموعة queue لمشتركي NATS. القيمة الافتراضية هي اسم الجدول.
  • nats_max_reconnect – مهمل وليس له أي تأثير، إذ تتم إعادة الاتصال بشكل دائم مع مهلة nats_reconnect_wait.
  • nats_reconnect_wait – مقدار الوقت بالمللي ثانية للانتظار بين كل محاولة إعادة اتصال. القيمة الافتراضية: 2000.
  • nats_server_list - قائمة الخوادم الخاصة بالاتصال. يمكن تحديدها للاتصال بعنقود NATS.
  • nats_skip_broken_messages - مدى تحمّل محلل رسائل NATS للرسائل غير المتوافقة مع schema لكل block. القيمة الافتراضية: 0. إذا كان nats_skip_broken_messages = N فسيتخطى المحرك عدد N من رسائل NATS التي يتعذر تحليلها (الرسالة الواحدة تعادل صفًا واحدًا من البيانات).
  • nats_max_block_size - عدد الـ row التي تجمعها عملية أو عمليات poll لتفريغ البيانات من NATS. القيمة الافتراضية: max_insert_block_size.
  • nats_flush_interval_ms - مهلة تفريغ البيانات المقروءة من NATS. القيمة الافتراضية: stream_flush_interval_ms.
  • nats_wait_for_flush_interval - إذا كانت القيمة true، فستبقى دورة البث في الخلفية مفتوحة طوال فترة التفريغ (nats_flush_interval_ms، أو stream_flush_interval_ms بخلاف ذلك) بدلًا من الانتهاء بمجرد تفريغ queue المستهلك، مما يتيح تراكم المزيد من الرسائل في block واحد مقابل زمن استيعاب إضافي يصل إلى فترة تفريغ واحدة. القيمة الافتراضية: false (سلوك تفريغ فوري منخفض الكمون).
  • nats_username - اسم مستخدم NATS. عند تخزينه في مجموعة مسماة معرّفة في ملف إعدادات الخادم، لا يمكن لـ query تجاوز nats_url أو nats_server_list الخاصين بالمجموعة.
  • nats_password - كلمة مرور NATS. عند تخزينها في مجموعة مسماة معرّفة في ملف إعدادات الخادم، لا يمكن لـ query تجاوز nats_url أو nats_server_list الخاصين بالمجموعة.
  • nats_token - رمز مصادقة NATS. عند تخزينه في مجموعة مسماة معرّفة في ملف إعدادات الخادم، لا يمكن لـ query تجاوز nats_url أو nats_server_list الخاصين بالمجموعة.
  • nats_credential_file - مسار ملف بيانات اعتماد NATS. لا يُقبل إلا من مجموعة مسماة معرّفة في ملف إعدادات الخادم لا يتم تجاوز nats_url وnats_server_list الخاصين بها بواسطة query، لأن الخادم يفتح المسار بصلاحياته الخاصة. في query، مرّر محتويات الملف في nats_credentials بدلًا من ذلك.
  • nats_credentials - محتوى بيانات اعتماد NATS (نفس الحمولة الموجودة في ملف .creds الذي يتضمن JWT المستخدم والبذرة). نظرًا إلى أنه الصيغة الوحيدة التي يمكن لـ query استخدامها، فإنه يستبدل nats_credential_file الموروث من مجموعة مسماة بدلًا من التعارض معه، ما لم يقفل المشغّل ذلك المسار باستخدام <nats_credential_file overridable="false">. لا يمكن تعيين سلسلة فارغة له لإزالة بيانات الاعتماد التي تحملها مجموعة مسماة.
  • nats_startup_connect_tries - عدد محاولات الاتصال عند بدء التشغيل. القيمة الافتراضية: 5.
  • nats_max_rows_per_message — الحد الأقصى لعدد rows المكتوبة في رسالة NATS واحدة للتنسيقات المعتمدة على الصفوف. (القيمة الافتراضية: 1).
  • nats_commit_on_select - ثبّت الرسائل عند تنفيذ query. ينطبق على JetStream فقط؛ إذ لا يحتوي NATS core على إقرارات. القيمة الافتراضية: 0.
  • nats_handle_error_mode — كيفية التعامل مع الأخطاء في محرك NATS. القيم الممكنة: default (سيتم طرح الاستثناء إذا فشل تحليل رسالة)، stream (ستُحفَظ رسالة الاستثناء والرسالة الخام في أعمدة افتراضية _error و _raw_message).
اتصال SSL: لإجراء اتصال آمن استخدم nats_secure = 1. يتم التحكم في التحقق من الشهادة عبر متغير البيئة CLICKHOUSE_NATS_TLS_SECURE. إذا كانت الشهادة منتهية الصلاحية، أو موقعة ذاتيًا، أو مفقودة، أو غير صالحة لأي سبب آخر، فقم بتعطيل التحقق بتعيين CLICKHOUSE_NATS_TLS_SECURE=0. الكتابة في جدول NATS: إذا كان الجدول يقرأ فقط من subject واحد، فسيُنشَر أي إدراج إلى نفس subject. ومع ذلك، إذا كان الجدول يقرأ من عدة subject، فسنحتاج إلى تحديد الـ subject الذي نرغب في النشر إليه. لذلك، عند الإدراج في جدول يقرأ من عدة subject، يلزم ضبط stream_like_engine_insert_queue. يمكنك اختيار أحد الـ subject التي يقرأ منها الجدول ونشر بياناتك هناك. على سبيل المثال:
يمكن أيضًا إضافة إعدادات التنسيق إلى جانب الإعدادات المتعلقة بـ NATS. مثال:
يمكن إضافة إعدادات خادم NATS باستخدام ملف إعدادات ClickHouse. وبشكل أكثر تحديدًا، يمكنك إضافة كلمة مرور NATS لمحرك NATS:

الوصف

لا تكون SELECT مفيدة كثيرًا لقراءة الرسائل (إلا لأغراض استكشاف الأخطاء وإصلاحها)، لأن كل رسالة لا يمكن قراءتها إلا مرة واحدة. والأكثر عملية هو إنشاء مسارات في الوقت الفعلي باستخدام العروض المادية. للقيام بذلك:
  1. استخدم المحرك لإنشاء مستهلك NATS واعتبره stream بيانات.
  2. أنشئ جدولًا بالبنية المطلوبة.
  3. أنشئ عرضًا ماديًا يحوّل البيانات من المحرك ويضعها في جدول أُنشئ مسبقًا.
عندما يرتبط MATERIALIZED VIEW بالمحرك، يبدأ في جمع البيانات في الخلفية. يتيح لك ذلك الاستمرار في تلقي الرسائل من NATS وتحويلها إلى التنسيق المطلوب باستخدام SELECT. يمكن أن يحتوي جدول NATS واحد على أي عدد تريده من العروض المادية؛ فهي لا تقرأ البيانات من الجدول مباشرةً، بل تستقبل السجلات الجديدة (على شكل كتل)، وبهذه الطريقة يمكنك الكتابة إلى عدة جداول بمستويات مختلفة من التفصيل (مع التجميع وبدونه). مثال:
لإيقاف استلام بيانات الـ stream أو لتغيير منطق التحويل، افصل العرض المادي:
إذا كنت تريد تغيير الجدول الهدف باستخدام ALTER، فنوصي بتعطيل العرض المادي لتجنّب حدوث اختلافات بين الجدول الهدف والبيانات الواردة من العرض.

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

  • _subject - الـsubject لرسالة NATS. نوع البيانات: String.
أعمدة افتراضية إضافية عندما تكون قيمة nats_handle_error_mode='stream':
  • _raw_message - الرسالة الخام التي تعذّر تحليلها بنجاح. نوع البيانات: Nullable(String).
  • _error - رسالة الاستثناء التي حدثت أثناء فشل التحليل. نوع البيانات: Nullable(String).
ملاحظة: لا تُملأ الأعمدة الافتراضية _raw_message و _error إلا عند حدوث استثناء أثناء التحليل، وتكون دائمًا NULL عندما يُحلَّلَت الرسالة بنجاح.

دعم تنسيقات البيانات

يدعم محرك NATS جميع التنسيقات التي يدعمها ClickHouse. ويعتمد عدد الصفوف في رسالة NATS الواحدة على ما إذا كان التنسيق يعتمد على الصفوف أم على الكتل:
  • بالنسبة إلى التنسيقات المعتمدة على الصفوف، يمكن التحكم في عدد الصفوف في رسالة NATS الواحدة عبر ضبط nats_max_rows_per_message.
  • أما بالنسبة إلى التنسيقات المعتمدة على الكتل، فلا يمكن تقسيم الكتلة إلى أجزاء أصغر، لكن يمكن التحكم في عدد الصفوف في الكتلة الواحدة من خلال الإعداد العام max_block_size.

استخدام JetStream

قبل استخدام محرك NATS مع NATS JetStream، يجب إنشاء stream في NATS وdurable pull مستهلك. ويمكنك لهذا الغرض استخدام أداة nats، على سبيل المثال، من حزمة NATS CLI:
بعد إنشاء stream وdurable pull مستهلك، يمكننا إنشاء جدول باستخدام محرك NATS. وللقيام بذلك، يجب تهيئة: nats_stream وnats_consumer_name وnats_subjects:
توفر جداول JetStream تسليمًا مرة واحدة على الأقل: لا يتم الإقرار بالرسالة إلا بعد إدراجها في العروض المادية التابعة، لذا تظل الرسالة التي يفشل إدراجها أو ينقطع إدراجها من دون إقرار، وتُعاد تسليمها. لا يوفر Core NATS (من دون JetStream) إقرارًا أو إعادة تشغيل، لذا فهو يضمن التسليم مرة واحدة على الأكثر، وتُفقد الرسالة التي ينقطع تسليمها.
آخر تعديل في ٢٦ أغسطس ٢٠٢٦