Skip to main content
يرشدك دليل البدء خلال الاستعلام عن Apache Iceberg وDelta Lake وApache Hudi وApache Paimon لأول مرة. بعد الانتهاء من الإعداد، استخدم هذه الصفحة لاختيار نمط الوصول المناسب، وضبط أداء الاستعلامات، واستكشاف أخطاء استعلامات بحيرة البيانات وإصلاحها في بيئة الإنتاج.

اختر طريقة الوصول

دوال الجداول

مرّر مسار التخزين وبيانات الاعتماد مباشرةً بشكلٍ مضمن عندما تعرف الموقع ولا تحتاج إلى تعريف جدول دائم.
استخدم بديل S3 مع AWS S3 وGCS. ولدى Azure ونظام الملفات المحلي بدائل مخصّصة (icebergAzure وicebergLocal، وما يقابلهما للتنسيقات الأخرى). راجع الاستعلام مباشرةً للاطلاع على القائمة الكاملة. يوفّر Paimon دوال جداول فقط.

محركات الجداول

أنشئ جدولًا باستخدام محرك الجدول عندما تحتاج إلى إجراء query على المسار نفسه بشكل متكرر. يخزّن ClickHouse المسار وبيانات الاعتماد في البيانات الوصفية للجدول، بحيث يمكنك إجراء query باستخدام اسم جدول عادي بدلًا من إعادة إنشاء استدعاء الدالة في كل مرة.
تدعم محركات الجداول ميزات القراءة نفسها التي تدعمها دوال الجداول، بما في ذلك التخزين المؤقت للبيانات والتخزين المؤقت للبيانات الوصفية. لا تُكرَّر البيانات مطلقًا في ClickHouse. ويكون محرك الجدول مفيدًا عندما تشارك فريقًا في الوصول أو تُشغِّل مهامًا مجدولة على الجدول نفسه.

محرك قاعدة البيانات DataLakeCatalog

اربط ClickHouse مرة واحدة عند تسجيل الجداول في كتالوج بيانات خارجي. وسيظهر كل جدول في الكتالوج تلقائيًا كجدول في ClickHouse، بما في ذلك الجداول التي تُضاف لاحقًا في المصدر بعد إنشاء الاتصال.
يوفّر هذا قابلية توسّع أفضل من إنشاء تعريفات table منفصلة عندما تدير عددًا كبيرًا من الجداول أو عدة كتالوجات. راجع الاتصال بالكتالوجات وأدلة الكتالوجات.
backticks لأسماء الجداول متعددة الأجزاءتستخدم الكتالوجات غالبًا تسمية database.table. أَحِط الاسم المؤهَّل بقاعدة البيانات بعلامات backticks، كما في المثال أعلاه.

الإعدادات المطلوبة

تتطلب العديد من عمليات التكامل علامة تفعيل لميزة معيّنة قبل استخدامها لأول مرة. تحقّق من إصدار خدمتك إذا فشل CREATE DATABASE بسبب خطأ في الأذونات. بالنسبة إلى اتصالات الكتالوج، لكل نوع من أنواع الكتالوج علامة خاصة به. راجع الاتصال بالكتالوجات للحصول على نظرة عامة، ومرجع DataLakeCatalog للاطّلاع على تفاصيل الإعدادات. أما إعداد كل كتالوج على حدة، فتجده في أدلة الكتالوج. بالنسبة إلى عمليات الكتابة، يتطلب Iceberg allow_insert_into_iceberg ‏(25.7+، وBeta بدءًا من 26.2). راجع الكتابة إلى بحيرات البيانات. ويتطلب Delta Lake allow_delta_lake_writes ‏(25.9+). وتوضّح مصفوفة الدعم العلامات التي تنطبق على كل تنسيق وكل عملية.

حسّن أداء الاستعلامات

تتطابق أرقام الإصدارات في هذه الصفحة مع إصدارات ClickHouse (Cloud والمُدارة ذاتيًا). تحقّق من إصدار خدمتك قبل تمكين أي إعداد أو ميزة. يعتمد أداء استعلامات Lake على مقدار البيانات الوصفية وعدد ملفات Parquet التي يقرؤها ClickHouse من التخزين الكائني. وكما هو الحال مع أي جدول في ClickHouse، يتحسّن أداء الاستعلامات عند التصفية حسب أعمدة التقسيم واختيار عدد أقل من الأعمدة.

عادات الاستعلام

قم بالتصفية حسب أعمدة التقسيم في WHERE. تخزّن Iceberg وDelta Lake البيانات الوصفية للتقسيم، مما يتيح لـ ClickHouse تخطي الملفات غير ذات الصلة أثناء تخطيط الاستعلام. وإذا كان عامل التصفية يستهدف عمودًا خارج مواصفات التقسيم، فسيفحص ClickHouse كل ملف مطابق. بالنسبة إلى جداول Iceberg التي تستخدم التقسيم المخفي، قم بالتصفية حسب العمود المصدر في مخطط الجدول، وليس حسب عمود تقسيم منفصل أو اسم حقل مُحوَّل. إذا كان الجدول مُقسَّمًا حسب day(event_time)، فأضف شرطًا على event_time. ويستنتج ClickHouse استبعاد الأقسام من هذا الشرط باستخدام مواصفات تقسيم Iceberg. راجع استبعاد الأقسام ومواصفة Iceberg.
اعرض فقط الأعمدة التي تحتاج إليها بدلًا من SELECT *. يقرأ ClickHouse تنسيق Parquet عمودًا بعمود من تخزين الكائنات، لذا فإن عمليات SELECT الأضيق تقلّل عدد البايتات المنقولة والمفكوك ضغطها. ضع عوامل التصفية الانتقائية في WHERE. بدءًا من ClickHouse 26.2+، أصبح PREWHERE مدعومًا أيضًا مع Iceberg وعمليات قراءة جداول البحيرات الأخرى، إذ يُجري التصفية على مستوى Parquet قبل قراءة الأعمدة المتبقية. ولا يزال استبعاد الأقسام يعتمد على تصفية الأعمدة المستخدمة في التقسيم، وليس على PREWHERE وحده. تُطبّق جداول Iceberg التي تتضمن position or equality deletes بكثافة تصفية merge-on-read أثناء الفحص. لذا توقّع عملًا أكبر لكل ملف مما قد يوحي به تشذيب manifest وحده. في عمليات النشر متعددة العقد، استخدم دوال الجداول الخاصة بـ cluster لتوزيع قراءات الملفات عبر النسخ المتماثلة.

القراءة المتوازية على العناقيد متعددة العقد

في ClickHouse Cloud والخدمات متعددة العقد مُدارة ذاتيًا، توزّع الإصدارات الخاصة بالعناقيد من دوال جداول البحيرات قراءات ملفات Parquet على النسخ المتماثلة. وتتولى العقدة البادئة توزيع الملفات على العُمّال بالتوازي. استخدم إصدارات العناقيد للقراءات على دفعات وعمليات التحميل المجدولة على الجداول الكبيرة. أما في عمليات النشر أحادية العقدة، فتكفي دالة الجدول القياسية. مرّر اسم العنقود كوسيط أول ('default' على ClickHouse Cloud). تتوفر إصدارات العناقيد لجميع التنسيقات المدعومة: يمكنك دمج قراءات العناقيد مع إعدادات أداء أخرى.

قيّد قراءات الدُفعات بنطاق اللقطات

بالنسبة إلى تحميلات الدُفعات المتكررة من جداول البحيرة، حدِّد نطاق كل تشغيل على مجموعة لقطات بدلًا من إعادة قراءة الجدول كاملًا. ومن دون هذه الحدود، قد يفحص ClickHouse جميع الإصدارات والملفات في كل تشغيل، مما يزيد عمليات القراءة من التخزين الكائني ووقت الاستعلام. خزّن معرّف اللقطة من آخر تحميل ناجح، واستخدمه كحدٍّ أدنى في التشغيل التالي.

تخزين ملفات Parquet مؤقتًا محليًا

يدعم كل من التنسيقين enable_filesystem_cache للاحتفاظ بملفات Parquet كثيرة الاستخدام على القرص المحلي بين الاستعلامات. في بيئات النشر المُدارة ذاتيًا، اضبط قرص التخزين المؤقت لنظام الملفات في إعدادات الخادم لكي تتوفر مساحة تخزين يكتب إليها هذا الإعداد. يدير ClickHouse Cloud التخزين المؤقت تلقائيًا. عيّن enable_filesystem_cache = 0 عند إجراء اختبارات الأداء حتى لا تُخفي نتائج التخزين المؤقت التغييرات بين مرات التشغيل.

Apache Iceberg

معظم تحسينات القراءة في Apache Iceberg مفعّلة افتراضيًا. تتحكم الإعدادات أدناه في استبعاد الأقسام، والتخزين المؤقت للبيانات الوصفية، وعدد مرات الاتصال بالكتالوج.

إعدادات القراءة

تقليل زمن وصول الكتالوج

تتطلب جداول Iceberg المتصلة بالكتالوج جلب البيانات الوصفية مع كل query ما لم تُخزَّن مؤقتًا. اجمع بين الإعدادين التاليين (26.4+):
  1. اضبط iceberg_metadata_async_prefetch_period_ms عند إنشاء الجدول لإجراء الجلب المسبق للبيانات الوصفية في الخلفية.
  2. اضبط iceberg_metadata_staleness_ms (26.3+) على الاستعلامات لقبول بيانات وصفية قديمة قليلًا مقابل تجنب رحلة الذهاب والإياب إلى الكتالوج.
تجلب قيمة 0 لـ staleness دائمًا أحدث البيانات الوصفية. زِد هذه النافذة لأعباء العمل كثيفة القراءة التي تتغير فيها الجداول على فترات متباعدة. عندما يختار ClickHouse ملف البيانات الوصفية غير الصحيح (توجد عدة ملفات .metadata.json في path الجدول)، ثبّت اختيار الملف باستخدام iceberg_metadata_file_path (25.4+) أو iceberg_metadata_table_uuid عند إنشاء الجدول. راجع تحديد ملف البيانات الوصفية.

السفر عبر الزمن

اقرأ لقطة تاريخية باستخدام iceberg_timestamp_ms أو iceberg_snapshot_id (كلاهما متاح بدءًا من 25.4). لا تعيّن كليهما في الاستعلام نفسه. افحص تسلسل اللقطات في system.iceberg_history (25.6+) قبل اختيار المعرّف. لعمليات تحميل الدُفعات المتكررة، راجع تقييد قراءات الدُفعات باللقطات.

عمليات الكتابة في Iceberg

إلى جانب allow_insert_into_iceberg ‏(25.7+، Beta بدءًا من 26.2)، يمكنك التحكم في حجم ملف الإخراج وعدد التقسيمات أثناء الإدراج: راجع الكتابة إلى بحيرات البيانات ومرجع محرك Iceberg.

Delta Lake

ابتداءً من الإصدار 25.6، يقرأ ClickHouse جداول Delta Lake على S3 وGCS باستخدام نواة Delta Lake المكتوبة بلغة Rust (allow_experimental_delta_kernel_rs، 25.5+). على Azure Blob Storage، استخدم deltaLakeAzure() مع القارئ legacy لأن هذه النواة معطّلة هناك. وبدون هذه النواة، لن تتوفر استبعاد الأقسام أو تغذية بيانات التغيير أو قراءة snapshot version.

Delta Kernel

يجب تمكين allow_experimental_delta_kernel_rs لاستخدام استبعاد الأقسام، وتغذية بيانات التغيير، وقراءة إصدارات اللقطات. ويكون مفعّلًا افتراضيًا على S3 وGCS بدءًا من الإصدار 25.5. فعِّله صراحةً في الإصدارات الأقدم أو عند استكشاف الأخطاء وإصلاحها:

إعدادات القراءة

تُطبِّق الجداول التي تحتوي على متجهات الحذف ‏(26.2+) تصفية على مستوى الصفوف أثناء القراءة. يتعامل ClickHouse مع ذلك تلقائيًا، لكن المسح في الجداول التي تكثر فيها DV يتطلب عملاً أكبر لكل ملف.

تغذية بيانات التغيير في Delta

لقراءة الصفوف التي تغيّرت فقط بين لقطتَي Delta، عيّن delta_lake_snapshot_start_version وdelta_lake_snapshot_end_version (25.12+). يجب أن تكون تغذية بيانات التغيير مفعّلة للجدول في المصدر الأصلي (delta.enableChangeDataFeed). عيّن كلاً من إصدارَي البداية والنهاية في إعدادات الاستعلام. سيؤدي تعيين إصدار النهاية فقط إلى حدوث خطأ.
خزّن إصدار النهاية بعد كل عملية تحميل ناجحة، ومرّره باعتباره إصدار البداية في التشغيل التالي. تتضمن النتيجة أعمدة CDF (_change_type, _commit_version, _commit_timestamp). تعامل مع هذه الأعمدة قبل تحميل البيانات إلى الجدول الهدف. للاطلاع على النمط العام للّقطات، راجع تقييد قراءات الدفعات باللقطات.

عمليات الكتابة في Delta Lake

إلى جانب allow_delta_lake_writes ‏(25.9+)، تحكَّم في حجم ملف الإخراج أثناء الإدراج:
تتطلب عمليات الكتابة استخدام Delta Kernel مع S3 أو GCS. راجع مرجع محرك DeltaLake للاطلاع على أمثلة.

استكشاف أخطاء استعلامات بحيرة البيانات وإصلاحها

غالبًا ما ترجع الاستعلامات البطيئة على بحيرة البيانات، أو التي تُرجع نتائج غير متوقعة، إلى عمليات قراءة البيانات الوصفية، أو استبعاد الأقسام، أو مشاكل الاتصال بـ الكتالوج. ابدأ بعمليات التحقق أدناه، ثم استخدم سجلات البيانات الوصفية الخاصة بكل format عند الحاجة.

التحقق من اتصال الكتالوج

لا يتحقق CREATE DATABASE مع DataLakeCatalog من بيانات الاعتماد. يمكن أن تظل قاعدة البيانات موجودة حتى إذا كان الاتصال بالكتالوج معطّلًا. اعتبارًا من ClickHouse 26.4، شغّل فحصًا صحيًا خفيفًا:
في الإصدارات الأقدم، تأكّد من الاتصال باستخدام SHOW TABLES FROM my_lake وافحص رسالة الخطأ. استخدم SHOW CREATE TABLE مع اسم جدول محاط بعلامتَي الاقتباس المائلتين للتحقّق من مسار التخزين الذي تم تحديده ونوع المحرّك:
إذا لم تظهر جداول كتالوج في system.tables، ففعِّل show_remote_databases_in_system_tables (25.8+). تُخفى جداول كتالوج افتراضيًا عن استبطان النظام. في الإصدارات السابقة لـ 26.6، استخدم اسمها السابق، show_data_lake_catalogs_in_system_tables.

اعرف الملفات التي تتم قراءتها

يكشف كلٌّ من Iceberg وDelta Lake عن الأعمدة الافتراضية (_path, _file, _size, _time, _etag) في كل عملية قراءة. نفّذ التجميع حسب _path لمعرفة ما إذا كان استبعاد الأقسام يعمل كما ينبغي، أو ما إذا كان الاستعلام يفحص ملفات أكثر من المتوقع. بالنسبة إلى جداول Iceberg ذات التقسيم المخفي، طبّق عامل التصفية على العمود المصدر (مثل event_time) لا على عمود قسم منفصل:

تحقّق من حجم المسح

قارن بين read_rows وread_bytes في system.query_log قبل إضافة عوامل التصفية أو ضبط الإعدادات وبعدها. تُظهر ProfileEvents مثل ReadBufferFromS3Bytes وCachedReadBufferReadFromCacheBytes مقدار البيانات التي جاءت من التخزين الكائني مقابل ذاكرة التخزين المؤقت المحلية. راجع تحسين الاستعلام للحصول على شرح كامل لـ query_log وEXPLAIN. عطّل enable_filesystem_cache عند إجراء اختبارات الأداء حتى لا تُخفي مرات الوصول الناجح إلى ذاكرة التخزين المؤقت الفروق بين التشغيلات.

سجلات البيانات الوصفية

يوفّر ClickHouse ثلاثة جداول نظام لأغراض تصحيح الأخطاء على مستوى البيانات الوصفية. فعِّل التسجيل على مستوى الاستعلام فقط. فهي ليست مخصّصة للمراقبة المستمرة. شغّل استعلامًا مع تمكين التسجيل، ثم نفّذ عملية flush للسجل، وبعد ذلك افحص السجلات الخاصة بذلك query_id:
في ClickHouse Cloud، تكون بيانات السجلات محلية لكل عقدة. استخدم clusterAllReplicas لرؤية الصورة الكاملة عبر النسخ المتماثلة. تؤدي مستويات السجل التفصيلية في Iceberg إلى تعطيل التخزين المؤقت للبيانات الوصفية لقوائم manifest والملفات، مما يبطئ الاستعلامات اللاحقة على الجدول نفسه. استخدم مستوى تفصيلاً عاليًا فقط أثناء التحقيق الفعلي. بالنسبة إلى مشكلات predicate في Delta Lake، فعّل delta_lake_throw_on_engine_predicate_error (25.8+) للإخفاق فورًا عندما يتعذر على النواة دفع عامل التصفية إلى الأسفل. راجع صفحتي المرجع iceberg_metadata_log وdelta_lake_metadata_log للاطلاع على تفاصيل الأعمدة وخيارات مستوى التفصيل.

الخطوات التالية

آخر تعديل في ٢٣ يوليو ٢٠٢٦