التجسيدات

يغطي هذا القسم جميع خيارات التجسيد المتاحة في dbt-clickhouse، بما في ذلك الميزات التجريبية.

يوضح الجدول التالي التهيئات المشتركة بين بعض استراتيجيات التجسيد المتاحة. للحصول على معلومات تفصيلية حول التهيئات العامة لنماذج dbt، راجع توثيق dbt:

ملاحظة: بالنسبة إلى materialized views، فجميع محركات *MergeTree مدعومة.

إذا واجهت مشكلات عند الاتصال بـ ClickHouse من dbt باستخدام أحد المحركات المذكورة أعلاه، فيُرجى الإبلاغ عن مشكلة هنا.

يحتوي ClickHouse على عدة أنواع/مستويات من "الإعدادات". في إعدادات النموذج أعلاه، يمكن ضبط نوعين منها. يشير settings إلى بند SETTINGS المستخدم في عبارات DDL من نوع CREATE TABLE/VIEW، لذا تكون هذه عمومًا إعدادات خاصة بـ محرك جدول ClickHouse المحدد. أما query_settings الجديدة فتُستخدم لإضافة بند SETTINGS إلى استعلامات INSERT وDELETE المستخدمة في تجسيد النموذج ( بما في ذلك التجسيدات التزايدية). توجد مئات من إعدادات ClickHouse، وليس من الواضح دائمًا أيّها إعداد "جدول" وأيّها إعداد "مستخدم" (مع أن الأخيرة تكون متاحة عمومًا في جدول system.settings.) وبوجه عام، يُوصى باستخدام القيم الافتراضية، وينبغي التحقق بعناية من أي استخدام لهذه الخصائص واختباره.

ملاحظة: تتطلب خيارات إعدادات العمود أدناه تفعيل عقود النموذج.

models:
  - name: table_column_configs
    description: 'Testing column-level configurations'
    config:
      contract:
        enforced: true
    columns:
      - name: ts
        data_type: timestamp
        codec: ZSTD
      - name: x
        data_type: UInt8
        ttl: ts + INTERVAL 1 DAY

يحدّد dbt تلقائيًا نوع البيانات لكل عمود من خلال تحليل SQL المستخدم لإنشاء النموذج. ومع ذلك، قد لا تتمكّن هذه العملية في بعض الحالات من تحديد نوع البيانات بدقة، مما يؤدي إلى تعارضات مع الأنواع المحددة في خاصية data_type الخاصة بالعقد. ولمعالجة ذلك، نوصي باستخدام الدالة CAST() في SQL الخاص بالنموذج لتحديد النوع المطلوب صراحةً. على سبيل المثال:

{{
    config(
        materialized="materialized_view",
        engine="AggregatingMergeTree",
        order_by=["event_type"],
    )
}}

select
  -- event_type may be infered as a String but we may prefer LowCardinality(String):
  CAST(event_type, 'LowCardinality(String)') as event_type,
  -- countState() may be infered as `AggregateFunction(count)` but we may prefer to change the type of the argument used:
  CAST(countState(), 'AggregateFunction(count, UInt32)') as response_count, 
  -- maxSimpleState() may be infered as `SimpleAggregateFunction(max, String)` but we may prefer to also change the type of the argument used:
  CAST(maxSimpleState(event_type), 'SimpleAggregateFunction(max, LowCardinality(String))') as max_event_type
from {{ ref('user_events') }}
group by event_type

يمكن إنشاء نموذج dbt على هيئة عرض في ClickHouse وتهيئته باستخدام الصيغة التالية:

ملف المشروع (dbt_project.yml):

models:
  <resource-path>:
    +materialized: view

أو كتلة config (models/<model_name>.sql):

{{ config(materialized = "view") }}

يمكن إنشاء نموذج dbt كـ جدول ClickHouse، وتهيئته باستخدام الصيغة التالية:

ملف المشروع (dbt_project.yml):

models:
  <resource-path>:
    +materialized: table
    +order_by: [ <column-name>, ... ]
    +engine: <engine-type>
    +partition_by: [ <column-name>, ... ]

أو كتلة config (models/<model_name>.sql):

{{ config(
    materialized = "table",
    engine = "<engine-type>",
    order_by = [ "<column-name>", ... ],
    partition_by = [ "<column-name>", ... ],
      ...
    ]
) }}

يمكنك إضافة فهارس تخطي البيانات ضمن تجسيدات table باستخدام إعداد indexes:

{{ config(
        materialized='table',
        indexes=[{
          'name': 'your_index_name',
          'definition': 'your_column TYPE minmax GRANULARITY 2'
        }]
) }}

يمكنك إضافة الإسقاطات إلى نمطي الـ التجسيد table وdistributed_table باستخدام إعداد projections. يتطلب كل إدخال إسقاط مفتاح query أو index، وليس كليهما.

ملاحظة: بالنسبة إلى الجداول الموزعة، يُطبَّق الإسقاط على الجداول _local، لا على جدول الوكيل الموزَّع. ملاحظة: يؤدي تحديد كل من query وindex في إدخال الإسقاط نفسه إلى ظهور خطأ في وقت الترجمة البرمجية.

استخدم query لتعريف استعلام إسقاط كامل:

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'your_projection_name',
               'query': 'SELECT department, avg(age) AS avg_age GROUP BY department'
           }
       ]
) }}

استخدم index كاختصار نحوي لإسقاطات الفهارس خفيفة الوزن التي تستخدم العمود الافتراضي _part_offset. مرّر اسم عمود واحد أو قائمة أعمدة للترتيب وفقًا لها:

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'proj_by_age',
               'index': 'age'
           }
       ]
) }}

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'proj_by_dept_age',
               'index': ['department', 'age']
           }
       ]
) }}

ينشئ dbt-clickhouse تلقائيًا عبارات DDL المناسبة لكل إصدار:

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

تعريف النموذج في dbt_project.yml:

models:
  <resource-path>:
    +materialized: incremental
    +order_by: [ <column-name>, ... ]
    +engine: <engine-type>
    +partition_by: [ <column-name>, ... ]
    +unique_key: [ <column-name>, ... ]
    +inserts_only: [ True|False ]

أو كتلة config داخل models/<model_name>.sql:

{{ config(
    materialized = "incremental",
    engine = "<engine-type>",
    order_by = [ "<column-name>", ... ],
    partition_by = [ "<column-name>", ... ],
    unique_key = [ "<column-name>", ... ],
    inserts_only = [ True|False ],
      ...
    ]
) }}

الإعدادات الخاصة بهذا النوع من التجسيد مُدرجة أدناه:

يدعم dbt-clickhouse ثلاث استراتيجيات للنماذج التزايدية.

تاريخيًا، لم يكن لدى ClickHouse سوى دعم محدود للتحديثات وعمليات الحذف، وذلك على شكل "mutations" غير متزامنة. ولمحاكاة سلوك dbt المتوقع، ينشئ dbt-clickhouse افتراضيًا جدولًا مؤقتًا جديدًا يحتوي على جميع السجلات "القديمة" غير المتأثرة (غير المحذوفة وغير المعدَّلة)، بالإضافة إلى أي سجلات جديدة أو محدَّثة، ثم يستبدل هذا الجدول المؤقت أو يُجري له EXCHANGE مع علاقة النموذج التزايدي الحالية. وهذه هي الاستراتيجية الوحيدة التي تحافظ على العلاقة الأصلية إذا حدث خطأ ما قبل اكتمال العملية؛ ولكن نظرًا لأنها تتضمن نسخًا كاملًا للجدول الأصلي، فقد تكون مكلفة جدًا وبطيئة في التنفيذ.

تستخدم استراتيجية delete+insert عمليات الحذف خفيفة الوزن لإزالة الصفوف المتأثرة، ثم تُدرج الصفوف الجديدة. ولأنها لا تنسخ الجدول بأكمله، فإن أداءها أفضل بكثير من استراتيجية "legacy". يؤدي تعيين use_lw_deletes: true في ملف التعريف إلى جعل delete+insert استراتيجية التزايدية الافتراضية.

هناك بعض التحذيرات المهمة عند استخدام هذه الاستراتيجية:

• تعمل مباشرةً على الجدول المتأثر من دون إنشاء أي جداول وسيطة أو مؤقتة، لذا إذا حدثت مشكلة أثناء العملية، فمن المرجح أن تصبح بيانات النموذج التزايدي في حالة غير صالحة.
• تتطلب إعداد ClickHouse ‏allow_nondeterministic_mutations. يفعّله المهايئ تلقائيًا لجلساته الخاصة متى أمكن ذلك. وعندما يتعذر تفعيله (على سبيل المثال، إذا كان للقراءة فقط بالنسبة إلى مستخدم dbt الخاص بك)، فإن السلوك يعتمد على كيفية اختيار الاستراتيجية: فالنماذج التي تعتمد على الاستراتيجية الافتراضية تعود بصمت إلى استراتيجية legacy، بينما تفشل النماذج التي تعيّن delete+insert أو microbatch صراحةً في وقت التشغيل، ويفشل use_lw_deletes: true في ملف التعريف عند الاتصال.
• في بعض الحالات النادرة جدًا، قد يؤدي استخدام incremental_predicates غير الحتمية إلى حدوث حالة سباق للعناصر المحدَّثة أو المحذوفة. ولضمان نتائج متسقة، ينبغي أن تقتصر المسندات التزايدية على الاستعلامات الفرعية التي تتعامل مع بيانات لن تُعدَّل أثناء التجسيد التزايدي.

تُعد الاستراتيجية التزايدية microbatch إحدى ميزات dbt-core منذ الإصدار 1.9، وقد صُممت للتعامل بكفاءة مع تحويلات البيانات الكبيرة ذات السلاسل الزمنية. وفي dbt-clickhouse، تستند هذه الاستراتيجية إلى الاستراتيجية التزايدية الحالية delete_insert من خلال تقسيم الزيادة إلى دفعات زمنية محددة مسبقًا استنادًا إلى إعدادات النموذج event_time و batch_size.

إلى جانب التعامل مع التحويلات الكبيرة، تتيح microbatch ما يلي:

• إعادة معالجة الدفعات الفاشلة.
• الاكتشاف التلقائي لـالتنفيذ المتوازي للدفعات.
• الاستغناء عن الحاجة إلى منطق شرطي معقد في الاستدراك اللاحق للبيانات التاريخية.

للاطلاع على استخدام microbatch بالتفصيل، راجع الوثائق الرسمية.

تحل هذه الاستراتيجية محل الإعداد inserts_only في الإصدارات السابقة من dbt-clickhouse. ويعتمد هذا النهج ببساطة على إضافة صفوف جديدة إلى العلاقة الحالية. ونتيجة لذلك، لا تُزال الصفوف المكررة، ولا يوجد جدول مؤقت أو وسيط. وهو النهج الأسرع إذا كانت الصفوف المكررة إما مسموحًا بها في البيانات أو مستبعَدة بواسطة الاستعلام التزايدي أو عبارة WHERE/عامل التصفية.

[IMPORTANT] حاليًا، لا تعمل استراتيجية insert_overwrite بشكل كامل مع التجسيدات الموزعة.

تنفّذ الخطوات التالية:

1. إنشاء جدول مرحلي (مؤقت) له البنية نفسها الخاصة بعلاقة النموذج التزايدي: CREATE TABLE <staging> AS <target>.
2. إدراج السجلات الجديدة فقط (الناتجة عن SELECT) في الجدول المرحلي.
3. استبدال الأقسام الجديدة فقط (الموجودة في الجدول المرحلي) في الجدول الهدف.

يوفّر هذا النهج المزايا التالية:

• إنه أسرع من الاستراتيجية الافتراضية لأنه لا ينسخ الجدول بأكمله.
• إنه أكثر أمانًا من الاستراتيجيات الأخرى لأنه لا يعدّل الجدول الأصلي حتى تكتمل عملية INSERT بنجاح: ففي حال حدوث فشلٍ أثناء التنفيذ، لا يتم تعديل الجدول الأصلي.
• يطبّق أفضل ممارسات هندسة البيانات المتعلقة بـ"عدم قابلية الأقسام للتغيير"، مما يبسّط المعالجة التزايدية والمتوازية للبيانات، وعمليات التراجع، وغير ذلك.

تتطلب هذه الاستراتيجية تعيين partition_by في إعدادات النموذج. وتتجاهل جميع المعلمات الأخرى الخاصة بالاستراتيجية في إعدادات النموذج.

ينشئ تجسيد materialized_view عرضًا ماديًا في ClickHouse يعمل كمشغّل إدراج، إذ يحوّل الصفوف الجديدة من الجدول المصدر ويُدرجها تلقائيًا في الجدول الهدف. ويُعد هذا أحد أقوى أساليب التجسيد المتاحة في dbt-clickhouse.

نظرًا لتفاصيله، لهذا التجسيد صفحة مخصّصة مستقلة. انتقل إلى دليل العروض المادية للاطلاع على الوثائق الكاملة

يمكن إنشاء نموذج dbt بصفته قاموس في ClickHouse. عند كل dbt run، يُستبدل الـ قاموس بتعريف النموذج الحالي باستخدام CREATE OR REPLACE DICTIONARY.

يصبح استعلام SQL الخاص بالنموذج هو استعلام مصدر القاموس:

{{ config(
       materialized='dictionary',
       fields=[
           ('id', 'UInt64'),
           ('name', 'String'),
       ],
       primary_key='id',
       layout='HASHED()',
       lifetime='MIN 0 MAX 300'
) }}

select id, name from {{ source('raw', 'people') }}

عند استخدام source_type='http' (أو خيار table)، لا يُستخدم SQL الخاص بالنموذج كمصدر، لكن dbt لا يزال يتطلب body — لذا استخدم العنصر النائب select 1:

{{ config(
       materialized='dictionary',
       fields=[
           ('LocationID', 'UInt16 DEFAULT 0'),
           ('Borough', 'String'),
           ('Zone', 'String'),
       ],
       primary_key='LocationID',
       layout='HASHED()',
       lifetime='MIN 0 MAX 0',
       source_type='http',
       url='https://datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi/taxi_zone_lookup.csv',
       format='CSVWithNames'
) }}

select 1

راجع اختبارات قاموس للاطلاع على مزيد من الأمثلة، بما في ذلك قواميس من النوعين range وdirect.

يُنشأ الجدول الموزع باتباع الخطوات التالية:

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

ملاحظات:

• تتضمن استعلامات dbt-clickhouse الآن تلقائيًا الإعداد insert_distributed_sync = 1 لضمان تنفيذ عمليات التجسيد التزايدي اللاحقة بشكل صحيح. وقد يؤدي ذلك إلى تنفيذ بعض عمليات insert في الجداول الموزعة ببطء أكبر من المتوقع.

{{
    config(
        materialized='distributed_table',
        order_by='id, created_at',
        sharding_key='cityHash64(id)',
        engine='ReplacingMergeTree'
    )
}}

select id, created_at, item
from {{ source('db', 'table') }}

CREATE TABLE db.table_local on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = ReplacingMergeTree
    ORDER BY (id, created_at);

CREATE TABLE db.table on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = Distributed ('cluster', 'db', 'table_local', cityHash64(id));

تُدرج أدناه الإعدادات الخاصة بنوع materialization هذا:

نموذج تزايدي يستند إلى الفكرة نفسها التي يقوم عليها الجدول الموزّع، وتكمن الصعوبة الرئيسية في معالجة جميع الاستراتيجيات التزايدية على نحو صحيح.

1. استراتيجية Append تُدرِج البيانات فقط في الجدول الموزّع.
2. استراتيجية Delete+Insert تُنشئ جدولًا موزّعًا مؤقتًا للتعامل مع جميع البيانات على كل شارد.
3. الاستراتيجية الافتراضية (القديمة) تُنشئ جداول موزّعة مؤقتة ووسيطة للسبب نفسه.

لا تُستبدل إلا جداول الشاردات، لأن الجدول الموزّع لا يحتفظ بالبيانات. ولا يُعاد تحميل الجدول الموزّع إلا عند تمكين وضع full_refresh أو عند احتمال تغيّر بنية الجدول.

{{
    config(
        materialized='distributed_incremental',
        engine='MergeTree',
        incremental_strategy='append',
        unique_key='id,created_at'
    )
}}

select id, created_at, item
from {{ source('db', 'table') }}

CREATE TABLE db.table_local on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = MergeTree;

CREATE TABLE db.table on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = Distributed ('cluster', 'db', 'table_local', cityHash64(id));

تتيح لقطات dbt تسجيل التغييرات التي تطرأ على نموذج قابل للتعديل بمرور الوقت. ويتيح ذلك بدوره تنفيذ استعلامات على النماذج عند نقطة زمنية محددة، بحيث يمكن للمحللين "الرجوع بالزمن" للاطلاع على الحالة السابقة للنموذج. وهذه الوظيفة مدعومة من خلال موصل ClickHouse، ويجري تكوينها باستخدام الصيغة التالية:

كتلة config في snapshots/<model_name>.sql:

{{
   config(
     schema = "<schema-name>",
     unique_key = "<column-name>",
     strategy = "<strategy>",
     updated_at = "<updated-at-column-name>",
   )
}}

لمزيد من المعلومات حول التهيئة، اطّلِع على صفحة مرجع إعدادات اللقطات.

لا تُدعَم إلا عقود أنواع الأعمدة المتطابقة تمامًا. على سبيل المثال، سيفشل العقد الذي يحدد نوع العمود UInt32 إذا كان الـ model يعيد UInt64 أو أي نوع عدد صحيح آخر. كما أن ClickHouse لا تدعم إلا قيود CHECK على مستوى الجدول/الـ model بالكامل. ولا يتم دعم المفتاح الأساسي، أو المفتاح الخارجي، أو القيد الفريد، أو قيود CHECK على مستوى العمود. (راجع وثائق ClickHouse حول مفاتيح المفتاح الأساسي وORDER BY.)