الميزات والإعدادات

في هذا القسم، نقدّم توثيقًا لبعض الميزات المتاحة لـ dbt مع ClickHouse.

للاتصال بـ ClickHouse من dbt، ستحتاج إلى إضافة ملف تعريف إلى ملف profiles.yml. ويتبع ملف تعريف ClickHouse البنية التالية:

your_profile_name:
  target: dev
  outputs:
    dev:
      type: clickhouse

      # Optional
      schema: [default] # ClickHouse database for dbt models
      driver: [http] # http or native.  If not set this will be autodetermined based on port setting
      host: [localhost] 
      port: [8123]  # If not set, defaults to 8123, 8443, 9000, 9440 depending on the secure and driver settings 
      user: [default] # User for all database operations
      password: [<empty string>] # Password for the user
      cluster: [<empty string>] # If set, certain DDL/table operations will be executed with the `ON CLUSTER` clause using this cluster. Distributed materializations require this setting to work. See the following ClickHouse Cluster section for more details.
      verify: [True] # Validate TLS certificate if using TLS/SSL
      secure: [False] # Use TLS (native protocol) or HTTPS (http protocol)
      client_cert: [null] # Path to a TLS client certificate in .pem format
      client_cert_key: [null] # Path to the private key for the TLS client certificate
      server_host_name: [null] # Override the TLS SNI and hostname verification target. Useful when connecting via a DNS alias (e.g. an internal CNAME or AWS PrivateLink endpoint) where the TLS certificate is issued for a different hostname than the one used in `host`.
      retries: [1] # Number of times to retry a "retriable" database exception (such as a 503 'Service Unavailable' error)
      compression: [<empty string>] # Use gzip compression if truthy (http), or compression type for a native connection
      connect_timeout: [10] # Timeout in seconds to establish a connection to ClickHouse
      send_receive_timeout: [300] # Timeout in seconds to receive data from the ClickHouse server
      cluster_mode: [False] # Use specific settings designed to improve operation on Replicated databases (recommended for ClickHouse Cloud)
      use_lw_deletes: [False] # Use the strategy `delete+insert` as the default incremental strategy.
      check_exchange: [True] # Validate that clickhouse support the atomic EXCHANGE TABLES command.  (Not needed for most ClickHouse versions)
      local_suffix: [_local] # Table suffix of local tables on shards for distributed materializations.
      local_db_prefix: [<empty string>] # Database prefix of local tables on shards for distributed materializations. If empty, it uses the same database as the distributed table.
      allow_automatic_deduplication: [False] # Enable ClickHouse automatic deduplication for Replicated tables
      tcp_keepalive: [False] # Native client only, specify TCP keepalive configuration. Specify custom keepalive settings as [idle_time_sec, interval_sec, probes].
      reuse_connections: [True] # Re-use the same connection across models. Set to `False` to close the connection at the end of each model — useful on multi-replica ClickHouse Cloud services where the load balancer routes by TCP connection. Note: disabling connection reuse adds a new TCP/TLS handshake per model, which increases total `dbt run` wall time (typically ~200-500 ms per model). Combine with `threads > 1` for the best balance between distribution and throughput.
      custom_settings: [{}] # A dictionary/mapping of custom ClickHouse settings for the connection - default is empty.
      database_engine: '' # Database engine to use when creating new ClickHouse schemas (databases).  If not set (the default), new databases will use the default ClickHouse database engine (usually Atomic).
      threads: [1] # Number of threads to use when running queries. Before setting it to a number higher than 1, make sure to read the [read-after-write consistency](#read-after-write-consistency) section.
      
      # Native (clickhouse-driver) connection settings
      sync_request_timeout: [5] # Timeout for server ping
      compress_block_size: [1048576] # Compression block size if compression is enabled

مُعرّف relation الخاص بنموذج dbt، أي database.schema.table، غير متوافق مع ClickHouse لأن ClickHouse لا يدعم schema. لذلك نستخدم نهجًا مبسّطًا هو schema.table، حيث يشير schema هنا إلى قاعدة بيانات ClickHouse. ولا يُنصح باستخدام قاعدة البيانات default.

في كثير من البيئات، لا يُعد استخدام عبارة SET للاحتفاظ بإعداد من إعدادات ClickHouse عبر جميع استعلامات DBT أمرًا موثوقًا، وقد يؤدي إلى حالات فشل غير متوقعة. وينطبق ذلك خصوصًا عند استخدام اتصالات HTTP عبر موازن تحميل يوزّع الاستعلامات على عدة عُقد (مثل ClickHouse Cloud)، مع أن هذا قد يحدث أيضًا في بعض الحالات مع اتصالات ClickHouse الأصلية. لذلك، نوصي — كأفضل ممارسة — بتهيئة أي إعدادات ClickHouse مطلوبة في الخاصية "custom_settings" ضمن ملف تعريف DBT، بدلًا من الاعتماد على عبارة "SET" في pre-hook كما يُقترح أحيانًا.

لتجنّب ظهور تحذير، تأكد من تعيين قيمة لـ quote_columns بشكل صريح في ملف dbt_project.yml. راجع التوثيق الخاص بـ quote_columns لمزيد من المعلومات.

seeds:
  +quote_columns: false  #or `true` if you have CSV column headers with spaces

عند استخدام عنقود ClickHouse، عليك مراعاة أمرين:

• ضبط إعداد cluster.
• ضمان اتساق القراءة بعد الكتابة، خاصةً إذا كنت تستخدم أكثر من threads.

يتيح إعداد cluster في ملف تعريف لـ dbt-clickhouse التشغيل على عنقود ClickHouse. وإذا تم تعيين cluster في ملف تعريف، فسيتم إنشاء جميع النماذج باستخدام العبارة ON CLUSTER افتراضيًا—باستثناء النماذج التي تستخدم محرّك Replicated. ويشمل ذلك:

• إنشاء قاعدة البيانات
• عمليات تجسيد للعروض
• عمليات تجسيد للجداول وIncremental
• عمليات تجسيد الموزعة

لن تتضمن محرّكات Replicated العبارة ON CLUSTER، لأنها مصممة لإدارة النسخ المتماثل داخليًا.

لـ تعطيل الإنشاء المستند إلى العنقود لنموذج معيّن، أضِف config ‏disable_on_cluster:

{{ config(
        engine='MergeTree',
        materialized='table',
        disable_on_cluster='true'
    )
}}

لن تتأثر استراتيجيتا التجسيد من نوعي table وincremental مع المحرك غير المكرّر بإعداد cluster (إذ لن يُنشأ النموذج إلا على العقدة المتصل بها).

التوافق

إذا كان النموذج قد أُنشئ من دون إعداد cluster، فسيكتشف dbt-clickhouse هذه الحالة ويشغّل جميع أوامر DDL/DML لهذا النموذج من دون بند on cluster.

يعتمد dbt على نموذج اتساق القراءة بعد الإدراج. وهذا لا يتوافق مع عناقيد ClickHouse التي تضم أكثر من نسخة متماثلة إذا لم تتمكن من ضمان توجيه جميع العمليات إلى النسخة المتماثلة نفسها. قد لا تواجه مشكلات في استخدامك اليومي لـ dbt، لكن توجد بعض الاستراتيجيات التي يمكنك اتباعها، بحسب عنقودك، لضمان ذلك:

• إذا كنت تستخدم عنقود ClickHouse Cloud، فما عليك سوى تعيين select_sequential_consistency: 1 في خاصية custom_settings ضمن ملف التعريف الخاص بك. يمكنك العثور على مزيد من المعلومات حول هذا الإعداد هنا.
• إذا كنت تستخدم عنقودًا ذاتي الاستضافة، فتأكد من إرسال جميع طلبات dbt إلى النسخة المتماثلة نفسها في ClickHouse. وإذا كان لديك موازن تحميل أمامه، فحاول استخدام آلية replica aware routing/sticky sessions حتى تتمكن دائمًا من الوصول إلى النسخة المتماثلة نفسها. ولا يُنصح بإضافة الإعداد select_sequential_consistency = 1 في العناقيد خارج ClickHouse Cloud غير موصى بها.

تتضمن وحدات الماكرو التالية لتسهيل إنشاء جداول وعروض خاصة بـ ClickHouse:

• engine_clause – تستخدم خاصية engine في تهيئة النموذج لتعيين محرك جدول في ClickHouse. يستخدم dbt-clickhouse المحرك MergeTree افتراضيًا.
• partition_cols – تستخدم خاصية partition_by في تهيئة النموذج لتعيين مفتاح تقسيم في ClickHouse. لا يتم تعيين مفتاح تقسيم افتراضيًا.
• order_cols – تستخدم تهيئة النموذج order_by لتعيين مفتاح ORDER BY/الترتيب في ClickHouse. إذا لم يتم تحديده، فسيستخدم ClickHouse القيمة tuple() الفارغة وسيكون الجدول غير مرتب
• primary_key_clause – تستخدم خاصية primary_key في تهيئة النموذج لتعيين مفتاح أساسي في ClickHouse. بشكل افتراضي، يتم تعيين مفتاح أساسي، ويستخدم ClickHouse عبارة ORDER BY بوصفها المفتاح الأساسي.
• on_cluster_clause – تستخدم خاصية cluster في ملف تعريف لإضافة عبارة ON CLUSTER إلى بعض عمليات dbt: التجسيدات الموزعة، وإنشاء العروض، وإنشاء قاعدة البيانات.
• ttl_config – تستخدم خاصية ttl في تهيئة النموذج لتعيين expression خاصة بـ table TTL في ClickHouse. لا يتم تعيين TTL افتراضيًا.

يُبسّط الماكرو s3source عملية تحديد بيانات ClickHouse مباشرةً من S3 باستخدام دالة الجدول S3 في ClickHouse. ويعمل ذلك من خلال تعبئة معلمات دالة الجدول S3 انطلاقًا من قاموس تهيئة مُسمّى (يجب أن ينتهي اسم القاموس بـ s3). يبحث الماكرو أولًا عن القاموس في vars الخاصة بالملف التعريفي، ثم في تهيئة النموذج. ويمكن أن يحتوي القاموس على أيٍّ من المفاتيح التالية المستخدمة لتعبئة معلمات دالة الجدول S3:

عرّف التهيئة المشتركة في dbt_project.yml (يجب أن ينتهي اسم القاموس بـ s3):

vars:
  taxi_s3:
    bucket: 'datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi'
    fmt: 'TabSeparatedWithNames'

ثم استدعِ الماكرو في نموذج. ويمكن أيضًا تمرير أيٍّ من المُعاملات أعلاه مباشرةً عند الاستدعاء، بحيث تكون لها الأسبقية على القيم في القاموس:

select * from {{ clickhouse_s3source('taxi_s3', path='/trips_4.gz') }}

راجع ملف اختبار S3 للاطّلاع على مزيد من الأمثلة.

يدعم dbt-clickhouse الآن معظم وحدات الماكرو متعددة قواعد البيانات المضمنة في dbt Core، مع الاستثناءات التالية:

• تُنفَّذ دالة SQL ‏split_part في ClickHouse باستخدام الدالة splitByChar. وتتطلب هذه الدالة استخدام سلسلة نصية ثابتة بوصفها الفاصل لـ "split"، لذا ستُفسَّر المعلَمة delimeter المستخدمة مع هذا الماكرو على أنها سلسلة نصية، لا اسم عمود
• وبالمثل، تتطلب دالة SQL ‏replace في ClickHouse سلاسل نصية ثابتة للمعلَمتين old_chars و new_chars، لذا ستُفسَّر هاتان المعلَمتان على أنهما سلاسل نصية بدلًا من أسماء أعمدة عند استدعاء هذا الماكرو.

قدّم dbt Core v1.10 دعمًا لتكامل الكتالوج، ما يتيح للمهايئات إنشاء النماذج فعليًا في كتالوجات خارجية تدير تنسيقات الجداول المفتوحة مثل Apache Iceberg. هذه الميزة ليست مدعومة بعد بشكل أصلي في dbt-clickhouse. يمكنك متابعة التقدّم في تنفيذ هذه الميزة عبر التذكرة #489 على GitHub.

أضاف ClickHouse مؤخرًا دعمًا أصليًا لجداول Apache Iceberg وكتالوجات البيانات. لا تزال معظم الميزات experimental، لكن يمكنك استخدامها بالفعل إذا كنت تستخدم إصدارًا حديثًا من ClickHouse.

• يمكنك استخدام ClickHouse للاستعلام عن جداول Iceberg المخزّنة في تخزين الكائنات (S3 وAzure Blob Storage وGoogle Cloud Storage) باستخدام محرك جدول Iceberg ودالة الجدول Iceberg.

• بالإضافة إلى ذلك، يوفّر ClickHouse محرك قاعدة البيانات DataLakeCatalog، الذي يتيح الاتصال بكتالوجات بيانات خارجية، بما في ذلك AWS Glue Catalog وDatabricks Unity Catalog وHive Metastore وREST Catalogs. ويتيح لك ذلك الاستعلام مباشرةً عن بيانات تنسيقات الجداول المفتوحة (Iceberg وDelta Lake) من الكتالوجات الخارجية من دون تكرار البيانات.

يمكنك قراءة البيانات من جداول Iceberg أو من الكتالوجات ضمن مشروع dbt الخاص بك، إذا كنت قد عرّفتها مسبقًا في عنقود ClickHouse لديك باستخدام الأدوات المذكورة أعلاه. ويمكنك الاستفادة من وظيفة source في dbt للإشارة إلى هذه الجداول في مشاريع dbt الخاصة بك. على سبيل المثال، إذا كنت تريد الوصول إلى جداولك في كتالوج REST، فيمكنك:

1. إنشاء قاعدة بيانات تشير إلى كتالوج خارجي:

-- Example with REST Catalog
SET allow_experimental_database_iceberg = 1;

CREATE DATABASE iceberg_catalog
ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
SETTINGS 
    catalog_type = 'rest', 
    storage_endpoint = 'http://minio:9000/lakehouse', 
    warehouse = 'demo'

2. عرِّف قاعدة بيانات كتالوج وجداولها كمصادر في dbt: تذكَّر أن الجداول يجب أن تكون متاحة بالفعل في ClickHouse

version: 2

sources:
  - name: external_catalog
    database: iceberg_catalog
    tables:
      - name: orders
      - name: customers

3. استخدم جداول الكتالوج في نماذج dbt:

SELECT 
    o.order_id,
    c.customer_name,
    o.order_date
FROM {{ source('external_catalog', 'orders') }} o
INNER JOIN {{ source('external_catalog', 'customers') }} c
    ON o.customer_id = c.customer_id

من مزايا هذه الحلول البديلة:

• ستحصل على وصول فوري إلى أنواع مختلفة من الجداول الخارجية والكتالوجات الخارجية دون الحاجة إلى انتظار توفر تكامل كتالوج dbt الأصلي.
• سيتوفر لك مسار ترحيل سلس عند إتاحة دعم الكتالوج الأصلي.

لكن توجد حاليًا بعض القيود:

• إعداد يدوي: يجب إنشاء جداول Iceberg وقواعد بيانات الكتالوج يدويًا في ClickHouse قبل أن يمكن الرجوع إليها في dbt.
• لا توجد DDL على مستوى الكتالوج: لا يمكن لـ dbt إدارة العمليات على مستوى الكتالوج، مثل إنشاء جداول Iceberg أو حذفها في الكتالوجات الخارجية. لذلك، لن تتمكن حاليًا من إنشائها من خلال موصل dbt. وقد تُضاف في المستقبل إمكانية إنشاء الجداول باستخدام محركات Iceberg().
• عمليات الكتابة: حاليًا، تكون الكتابة إلى جداول Iceberg/Data Catalog محدودة. راجع وثائق ClickHouse لمعرفة الخيارات المتاحة.