استكشاف الأخطاء وإصلاحها وأفضل الممارسات

رسالة الخطأ:

Test grants failed, cause: user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT

السبب: لا يملك مستخدم Fivetran الامتيازات المطلوبة. يتطلب الـ connector منح ALTER وCREATE DATABASE وCREATE TABLE وINSERT وSELECT على *.* (جميع قواعد البيانات والجداول).

الحل:

امنح الامتيازات المطلوبة مباشرةً لمستخدم Fivetran:

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

رسالة الخطأ:

error while waiting for all mutations to be completed: ... initial cause: ...

السبب: تم إرسال عملية ALTER TABLE ... UPDATE أو ALTER TABLE ... DELETE من نوع mutation، لكن الموصّل انتهت مهلته أثناء انتظار اكتمالها على جميع النسخ المتماثلة. وغالبًا ما يحتوي جزء "initial cause" من الخطأ على خطأ ClickHouse الأصلي (وعادةً ما يكون بالرمز 341، "Unfinished").

يمكن أن يحدث هذا عندما:

• يكون عنقود ClickHouse Cloud تحت حملٍ مرتفع.
• تتوقف عقدة واحدة أو أكثر أثناء تنفيذ عملية mutation.

الحلول:

1. تحقق من تقدّم عملية mutation: شغّل الاستعلام التالي للتحقق من عمليات mutation المعلّقة:

   SELECT database, table, mutation_id, command, create_time, is_done
   FROM system.mutations
   WHERE NOT is_done
   ORDER BY create_time DESC;

2. تحقق من حالة العنقود: تأكد من أن جميع العقد سليمة.
3. انتظر ثم أعد المحاولة: تكتمل عمليات mutation في النهاية بمجرد أن تستعيد حالة العنقود عافيتها. سيعيد Fivetran محاولة المزامنة تلقائيًا.

رسالة الخطأ:

قد تظهر أخطاء مختلفة إذا كان عدم تطابق الأعمدة ناتجًا عن تغيّر في مخطط المصدر. على سبيل المثال:

columns count in ClickHouse table (8) does not match the input file (6). Expected columns: id, name, ..., got: id, name, ...

أو:

column user_email was not found in the table definition. Table columns: ...; input file columns: ...

السبب: الأعمدة في جدول الوجهة في ClickHouse لا تتطابق مع الأعمدة في البيانات التي تتم مزامنتها. يمكن أن يحدث هذا عندما:

• أُضيفت أعمدة إلى جدول ClickHouse أو أُزيلت منه يدويًا.
• لم يُطبَّق تغيير في المخطط في المصدر على النحو الصحيح.

الحلول:

1. تذكّر عدم تعديل الجداول المُدارة بواسطة Fivetran يدويًا. راجع أفضل الممارسات.
2. أعِد العمود إلى حالته السابقة: إذا كنت تعرف النوع الذي ينبغي أن يكون عليه العمود، فأعِد العمود إلى النوع المتوقع باستخدام تعيين تحويل الأنواع كمرجع.
3. أعِد مزامنة الجدول: في لوحة معلومات Fivetran، شغِّل إعادة مزامنة تاريخية للجدول المتأثر.
4. احذف وأعِد الإنشاء: كحل أخير، احذف جدول الوجهة ودَع Fivetran يعيد إنشاءه أثناء المزامنة التالية.

رسالة الخطأ:

code: 168, message: AST is too big. Maximum: 50000

أو

code: 62, message: Max query size exceeded

السبب: تؤدي دفعات UPDATE أو DELETE الكبيرة إلى إنشاء عبارات SQL ذات أشجار بنية مجردة بالغة التعقيد. ويشيع ذلك مع الجداول العريضة أو عند تفعيل وضع السجل التاريخي.

الحل:

خفّض mutation_batch_size وhard_delete_batch_size في ملف التهيئة المتقدمة. تكون القيمة الافتراضية لكليهما 1500، ويقبلان قيماً بين 200 و1500.

رسالة الخطأ:

code: 241, message: (total) memory limit exceeded: would use 14.01 GiB

السبب: تتطلب عملية INSERT ذاكرة أكبر من الذاكرة المتاحة. يحدث هذا عادةً أثناء المزامنات الأولية الكبيرة، أو مع الجداول ذات الأعمدة الكثيرة، أو عمليات Batch المتزامنة.

الحلول:

1. تقليل write_batch_size: جرّب خفضها إلى 50,000 للجداول الكبيرة.
2. تقليل حمل قاعدة البيانات: تحقّق من الحمل على خدمة ClickHouse Cloud لمعرفة ما إذا كان هناك حمل زائد.
3. ترقية خدمة ClickHouse Cloud لتوفير مزيد من الذاكرة.

رسالة الخطأ:

ClickHouse connection error: unexpected EOF

أو FAILURE_WITH_TASK من دون تتبّع مكدس في سجلات Fivetran.

السبب:

• لم تُضبط قائمة الوصول لعناوين IP للسماح بمرور حركة Fivetran.
• مشكلات شبكة عابرة بين Fivetran وClickHouse Cloud.
• بيانات مصدر تالفة أو غير صالحة تؤدي إلى تعطل موصل الوجهة.

الحلول:

1. تحقّق من قائمة الوصول لعناوين IP: في ClickHouse Cloud، انتقل إلى الإعدادات > الأمان وأضف عناوين IP الخاصة بـ Fivetran أو اسمح بالوصول من أي مكان.
2. إعادة المحاولة: تعيد إصدارات الموصل الأحدث المحاولة تلقائيًا عند حدوث أخطاء EOF. وغالبًا ما تكون الأخطاء المتقطعة (1–2 يوميًا) عابرة.
3. إذا استمرت المشكلة: افتح تذكرة دعم مع ClickHouse وقدّم نافذة الوقت الخاصة بالخطأ. واطلب أيضًا من دعم Fivetran التحقيق في جودة بيانات المصدر.

رسالة الخطأ:

cause: can't map type UInt64 to Fivetran types

السبب: يربط الموصّل LONG بـ Int64 فقط، وليس بـ UInt64 مطلقًا. يظهر هذا الخطأ عند تعديل نوع أحد الأعمدة يدويًا في جدول تديره Fivetran.

الحلول:

1. لا تعدّل أنواع الأعمدة يدويًا في الجداول التي تديرها Fivetran.
2. لاستعادة الوضع: أعد العمود إلى النوع المتوقّع (مثل Int64) أو احذف الجدول ثم أعد مزامنته.
3. للأنواع المخصّصة: أنشئ عرضًا ماديًا فوق الجدول الذي تديره Fivetran.

رسالة الخطأ:

Failed to alter table ... cause: no primary keys for table

السبب: يتطلب كل جدول ClickHouse وجود ORDER BY. عندما لا يحتوي المصدر على مفتاح أساسي، تضيف Fivetran الحقل _fivetran_id تلقائيًا. يحدث هذا الخطأ في حالات نادرة يكون فيها للمصدر مفتاح أساسي (PK)، لكن البيانات لا تتضمنه.

الحلول:

1. تواصل مع دعم Fivetran للتحقيق في مسار معالجة بيانات المصدر.
2. تحقق من مخطط المصدر: تأكد من وجود أعمدة المفتاح الأساسي في البيانات.

رسالة الخطأ:

user is missing the required grants on *.*: ALTER, CREATE DATABASE, CREATE TABLE, INSERT, SELECT

السبب: يفحص الـconnector الامتيازات باستخدام:

SELECT access_type, database, table, column FROM system.grants WHERE user_name = 'my_user'

لا يُرجع هذا سوى الامتيازات الممنوحة مباشرةً. أما الامتيازات المُسندة عبر دور في ClickHouse فتكون قيمتها user_name = NULL وrole_name = 'my_role'، لذا لا تظهر في هذا الفحص.

الحل:

امنح الامتيازات مباشرةً لمستخدم Fivetran:

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

عند ارتفاع حمل الإدخال، فكّر في استخدام compute-compute separation في ClickHouse Cloud لإنشاء خدمة مخصّصة لأحمال الكتابة الخاصة بـ Fivetran. يعزل هذا الإدخال عن الاستعلامات التحليلية ويمنع التنافس على الموارد.

على سبيل المثال، يمكن استخدام المعمارية التالية:

• الخدمة A (للكتابة): وجهة Fivetran + أدوات إدخال أخرى (ClickPipes، وموصلات Kafka)
• الخدمة B (للقراءة): أدوات BI، ولوحات المعلومات، والاستعلامات الفورية

يستخدم ClickHouse SharedReplacingMergeTree لجداول الوجهة في Fivetran، وهو إصدار من محرك الجداول ReplacingMergeTree في ClickHouse Cloud. وجود صفوف مكررة بالمفتاح الأساسي نفسه أمر طبيعي — إذ تحدث إزالة التكرارات بشكل غير متزامن أثناء عمليات الدمج في الخلفية. وعند القراءة، يجب توخي الحذر لتجنب إرجاع صفوف مكررة، لأن بعض الصفوف قد لا تكون أُزيلت تكراراتها بعد.

يُعد استخدام الكلمة المفتاحية FINAL أبسط طريقة لتجنب الصفوف المكررة، لأنه يفرض دمج أي صفوف لم تُزل تكراراتها بعد وقت القراءة:

SELECT * FROM schema.table FINAL WHERE ...

هناك طرق لتحسين عملية FINAL هذه — على سبيل المثال، من خلال التصفية على أعمدة المفتاح باستخدام شرط WHERE. لمزيد من التفاصيل، راجع قسم أداء FINAL في دليل ReplacingMergeTree.

إذا لم تكن هذه التحسينات كافية، فلديك خيارات إضافية تتيح تجنّب استخدام FINAL مع الاستمرار في التعامل مع القيم المكررة بشكل صحيح:

• إذا كنت تريد تنفيذ استعلام على عمود رقمي تزداد قيمه باستمرار، يمكنك استخدام max(the_column).
• إذا كنت بحاجة إلى استرجاع أحدث قيمة لبعض الأعمدة لمفتاح معيّن، فيمكنك استخدام argMax(the_column, _fivetran_id).

يقوم Fivetran بمطابقة المفتاح الأساسي للجدول المصدر مع عبارة ORDER BY في ClickHouse. وعندما لا يحتوي المصدر على PK، يصبح _fivetran_id (وهو UUID) مفتاح الفرز، مما قد يؤدي إلى ضعف أداء الاستعلامات لأن ClickHouse يبني الفهرس الأساسي المتناثر من أعمدة ORDER BY.

التوصيات في هذه الحالة إذا لم يكن أي تحسين آخر كافيًا:

1. تعامل مع جداول Fivetran على أنها جداول مرحلية خام. لا تستعلم منها مباشرةً لأعمال التحليلات.
2. إذا لم يكن أداء الاستعلامات كافيًا بعد، فاستخدم عرضًا ماديًا قابلاً للتحديث لإنشاء نسخة من الجدول يكون فيها ORDER BY محسّنًا ليتناسب مع أنماط الاستعلام لديك. وعلى عكس العروض المادية التزايدية، تعيد العروض المادية القابلة للتحديث تشغيل الاستعلام كاملًا وفق جدول زمني، مما يعالج عمليتي UPDATE وDELETE اللتين يُجريهما Fivetran أثناء المزامنة بشكل صحيح:

   CREATE MATERIALIZED VIEW schema.table_optimized
   REFRESH EVERY 1 HOUR
   ENGINE = ReplacingMergeTree()
   ORDER BY (user_id, event_date)
   AS SELECT * FROM schema.table_raw FINAL;

تجنّب إجراء تغييرات DDL يدويًا (مثل ALTER TABLE ... MODIFY COLUMN) على الجداول التي يديرها Fivetran. يتوقّع الموصّل مخطط البيانات الذي أنشأه. قد تتسبب التغييرات اليدوية في أخطاء تعيين الأنواع وإخفاقات عدم تطابق مخطط البيانات.

استخدم العروض المادية لإجراء التحويلات المخصّصة.

عند تشخيص حالات الفشل:

• تحقّق من system.query_log في ClickHouse بحثًا عن المشكلات من جهة الخادم.
• اطلب المساعدة من Fivetran بشأن المشكلات من جهة العميل.

بالنسبة إلى أخطاء الموصل، أنشئ issue على GitHub أو تواصل مع ClickHouse Support.

استخدم الاستعلامات التالية لتشخيص حالات فشل المزامنة في ClickHouse.

SELECT event_time, query, exception_code, exception
FROM system.query_log
WHERE client_name LIKE 'fivetran-destination%'
  AND exception_code > 0
ORDER BY event_time DESC
LIMIT 50;

SELECT event_time, query_kind, query, exception_code, exception
FROM system.query_log
WHERE user = '{fivetran_user}'
ORDER BY event_time DESC
LIMIT 100;