العروض المادية

1. إنشاء الجدول الهدف باسم النموذج
2. إنشاء ClickHouse عرض مادي بالاسم <model_name>_mv

-- models/events_mv.sql
{{
    config(
        materialized='materialized_view',
        engine='SummingMergeTree()',
        order_by='(event_date, event_type)'
    )
}}

SELECT
    toStartOfDay(event_time) AS event_date,
    event_type,
    count() AS total
FROM {{ source('raw', 'events') }}
GROUP BY event_date, event_type

--mv1:begin
select a,b,c from {{ source('raw', 'table_1') }}
--mv1:end
union all
--mv2:begin
select a,b,c from {{ source('raw', 'table_2') }}
--mv2:end

{{config(
    materialized='materialized_view',
    engine='MergeTree()',
    order_by='(id)',
    on_schema_change='fail'  # this setting
)}}

{{config(
    materialized='materialized_view',
    engine='MergeTree()',
    order_by='(id)',
    catchup=False  # this setting
)}}

• تشترك جميع الموارد (الجدول الهدف + MVs) في الإعدادات نفسها. وإذا كانت عدة MVs تشير إلى الجدول الهدف نفسه، فيجب تعريفها معًا باستخدام صياغة UNION ALL.
• لا يمكن التعامل مع أي من هذه الموارد بشكل منفصل، إذ يجب إدارة جميعها باستخدام ملف النموذج نفسه.
• لا يمكنك بسهولة التحكم في اسم كل MV.
• تتشارك جميع الإعدادات بين الجدول الهدف وMVs، مما يصعّب تهيئة كل مورد على حدة ويجعل من الصعب تحديد التهيئة التي تخص كل مورد.

• موارد منفصلة بالكامل: أصبح الآن بالإمكان تعريف كل مورد على حدة، مما يحسّن سهولة القراءة.
• تطابق 1:1 بين موارد dbt وCH: يمكنك الآن استخدام أدوات dbt لإدارتها وتكرارها كلٌّ على حدة.
• إتاحة تهيئات مختلفة: أصبح الآن بالإمكان تطبيق تهيئة مختلفة على كل مورد.
• لم تعد هناك حاجة للالتزام باتفاقيات التسمية: تُنشأ الآن جميع الموارد باستخدام الاسم الذي تحدده لها، وليس الاسم المخصّص المضاف إليه اللاحقة _mv في MVs.

• تعريف الجدول الهدف ليس نهجًا طبيعيًا في dbt: فهو ليس استعلام SQL يقرأ من جدول مصدر، لذا تفقد هنا عمليات التحقق الخاصة بـ dbt. سيظل SQL الخاص بـ MV خاضعًا للتحقق باستخدام أدوات dbt المساعدة، كما سيُتحقق من توافقه مع أعمدة الجدول الهدف على مستوى CH.
• وجدنا بعض المشكلات المرتبطة بقيود الدالة ref(): نحتاج إلى استخدامها للإشارة إلى النماذج فيما بينها، لكن لا يمكن استخدامها إلا للإشارة إلى النماذج upstream، وليس downstream. وهذا يسبب بعض المشكلات في هذا التنفيذ. لقد أنشأنا issue في مستودع dbt-core، ونجري حاليًا نقاشًا معهم للبحث عن حلول ممكنة (dbt-labs/dbt-core#12319):
  • عند استدعاء ref() من داخل كتلة config، فإنها تُرجع النموذج الحالي، لا النموذج المُشار إليه. وهذا يمنعنا من تعريفه في قسم config()، ويجبرنا على استخدام comment لإضافة هذه التبعية. ونحن نتبع النمط نفسه الموضح في وثائق dbt باستخدام أسلوب “—depends_on:”.
  • تعمل ref() بالنسبة لنا لأنها تفرض إنشاء الجدول الهدف أولًا، ولكن في مخطط التبعيات في الوثائق المُولَّدة، سيُرسَم الجدول الهدف على أنه تبعية upstream أخرى، وليس downstream، مما يجعل فهمه أكثر صعوبة قليلًا.
  • يفرض unit-test علينا أيضًا تعريف بعض البيانات للجدول الهدف حتى عندما تكون الفكرة ألا نقرأ منه. والحل البديل هنا هو ببساطة ترك بيانات هذا الجدول فارغة.

{{
    config(
        materialized='table',
        engine='SummingMergeTree()',
        order_by='(event_date, event_type)',
        partition_by='toYYYYMM(event_date)'
    )
}}

SELECT
    toDate(now()) AS event_date,
    '' AS event_type,
    toUInt64(0) AS total
WHERE 0  -- Creates empty table with correct schema

{{ config(materialized='materialized_view') }}
{{ materialization_target_table(ref('events_daily')) }}

SELECT
    toStartOfDay(event_time) AS event_date,
    event_type,
    count() AS total
FROM {{ source('raw', 'page_events') }}
GROUP BY event_date, event_type

{{ config(materialized='materialized_view') }}
{{ materialization_target_table(ref('events_daily')) }}

SELECT
    toStartOfDay(event_time) AS event_date,
    event_type,
    count() AS total
FROM {{ source('raw', 'mobile_events') }}
GROUP BY event_date, event_type

-- models/page_events_aggregator.sql
{{ config(
    materialized='materialized_view',
    catchup=True  -- this is the default value so you don't need to actually set it.
) }}
{{ materialization_target_table(ref('events_daily')) }}
...

1. إنشاء جدول مؤقت جديد
2. تنفيذ INSERT-SELECT باستخدام SQL الخاص بكل MV
3. تبديل الجدولين ذريًا

-- models/events_daily.sql
{{
    config(
        materialized='table',
        engine='SummingMergeTree()',
        order_by='(event_date, event_type)',
        repopulate_from_mvs_on_full_refresh=True
    )
}}
...

1. حدِّث استدعاء materialization_target_table()
2. شغِّل dbt run --full-refresh -s your_mv_model

• قد تكون العروض المادية مهيأة باستخدام catchup=False، أو قد يكون الجدول الهدف مهيأ باستخدام repopulate_from_mvs_on_full_refresh=False، ولذلك لا يتم تنفيذ تحميل البيانات التاريخية عند إنشاء العروض المادية أو عند إعادة إنشاء الجدول الهدف. هذا هو السلوك المتوقع، لذا إذا كنت تريد إعادة إدراج البيانات باستخدام SQL الخاص بالعروض المادية، فتأكد من ضبط catchup=True في العرض المادي (وهذه هي القيمة الافتراضية) أو repopulate_from_mvs_on_full_refresh=True في الجدول الهدف. وتأكد من عدم تفعيل الخيارين معًا في الوقت نفسه لتجنب التكرار. راجع قسم التهيئة لمزيد من التفاصيل.
• أثناء تنفيذ dbt run --full-refresh، إذا كانت العروض المادية تستخدم القيمة الافتراضية catchup=True، فسيُعاد إنشاء الهدف، وستُعيد العروض المادية إدراج البيانات تباعًا. لتجنب هذا الوضع، راجع التحديث الكامل مع الأهداف الصريحة.

• قد يكون كلٌّ من catchup=True على العروض المادية وrepopulate_from_mvs_on_full_refresh=True على الجدول الهدف مفعّلًا: أبقِ واحدًا منهما فقط بحسب العمليات التي تريد تشغيلها. راجع قسم الإعدادات لمزيد من التفاصيل.
• لم يتم تعريف الجدول الهدف باستخدام WHERE 0: يجب إنشاء الجدول الهدف فارغًا، لكن قد يُدرج الاستعلام الداخلي بيانات إذا لم يتم تضمين WHERE 0. تأكد من تضمين العبارة.

SELECT
    name as mv_name,
    replaceRegexpOne(
        create_table_query,
        '.*TO\\s+`?([^`\\s(]+)`?\\.`?([^`\\s(]+)`?.*',
        '\\1.\\2'
    ) AS target_table
FROM system.tables
WHERE database = 'your_schema'
  AND engine = 'MaterializedView'

الجدول <table_name> يُستخدم كجدول هدف بواسطة عرض مادي يديره dbt. سيتم ضبط mv_on_schema_change تلقائيًا على “fail” لمنع فقدان البيانات.

• يعرّف نموذج العرض المادي {{ materialization_target_table(ref('your_target')) }} بشكل صحيح
• يتضمن نموذج العرض المادي materialized='materialized_view' في إعداداته
• تم تشغيل كلٍّ من العرض المادي والجدول الهدف مرة واحدة على الأقل

-- models/events_daily.sql
{{
    config(
        materialized='table',
        engine='MergeTree()',
        order_by='(event_date, event_type)'
    )
}}

SELECT
    toDate(now()) AS event_date,
    '' AS event_type,
    toUInt64(0) AS total
WHERE 0

• إذا كان هناك MV واحد فقط مُعرَّف، فسيكون اسمه: <old_model_name>_mv
• إذا كانت هناك عدة MVs مُعرَّفة، فسيكون اسم كلٍّ منها: <old_model_name>_mv_<name_in_comments>

--mv1:begin
select a, b, c from {{ source('raw', 'table_1') }}
--mv1:end
union all
--mv2:begin
select a, b, c from {{ source('raw', 'table_2') }}
--mv2:end

-- models/my_model_mv_mv1.sql
{{ config(materialized='materialized_view') }}
{{ materialization_target_table(ref('events_daily')) }}

select a, b, c from {{ source('raw', 'table_1') }}

-- models/my_model_mv_mv2.sql
{{ config(materialized='materialized_view') }}
{{ materialization_target_table(ref('events_daily')) }}

select a, b, c from {{ source('raw', 'table_2') }}

• بما أن العروض المادية في ClickHouse تعمل بوصفها مشغلات إدراج، فهي لا تلتقط البيانات إلا ما دامت موجودة. وإذا حُذف عرض مادي وأُعيد إنشاؤه (على سبيل المثال أثناء --full-refresh)، فلن تُعالَج أي صفوف أُدرجت في جدول المصدر خلال تلك الفترة بواسطة العرض المادي. ويُشار إلى ذلك بأن العرض المادي يكون “أعمى”.
• تستند جميع عمليات catchup المختلفة إلى عمليات INSERT INTO ... SELECT باستخدام SQL الخاص بالعروض المادية، وهي مستقلة عن آلية عمل العروض المادية. وبمجرد بدء INSERT، فإنه لا يلتقط البيانات الجديدة، لكن العرض المادي المُرفَق سيلتقطها.

{{
    config(
        materialized='materialized_view',
        engine='MergeTree()',
        order_by='(event_date)',
        refreshable={
            "interval": "EVERY 5 MINUTE",
            "randomize": "1 MINUTE",
            "append": True,
            "depends_on": ['schema.depend_on_model'],
            "depends_on_validation": True
        }
    )
}}

SELECT
    toStartOfDay(event_time) AS event_date,
    count() AS total
FROM {{ source('raw', 'events') }}
GROUP BY event_date

{{
    config(
        materialized='materialized_view',
        refreshable={
            "interval": "EVERY 1 HOUR",
            "append": False
        }
    )
}}
{{ materialization_target_table(ref('events_daily')) }}

SELECT
    toStartOfDay(event_time) AS event_date,
    event_type,
    count() AS total
FROM {{ source('raw', 'events') }}
GROUP BY event_date, event_type

• عند إنشاء عرض مادي قابل للتحديث (MV) في ClickHouse وله تبعية، لا يُصدر ClickHouse خطأ إذا كانت التبعية المحددة غير موجودة وقت الإنشاء. وبدلًا من ذلك، يظل العرض المادي القابل للتحديث في حالة غير نشطة، منتظرًا استيفاء التبعية قبل أن يبدأ في معالجة التحديثات أو إجراء التحديث. هذا السلوك مقصود من حيث التصميم، لكنه قد يؤدي إلى تأخر توفر البيانات إذا لم تُعالَج التبعية المطلوبة بسرعة. لذا ينبغي التأكد من أن جميع التبعيات معرّفة بشكل صحيح وموجودة قبل إنشاء عرض مادي قابل للتحديث.
• حتى الآن، لا يوجد “ربط dbt” فعلي بين mv وتبعياته، ولذلك لا يكون ترتيب الإنشاء مضمونًا.
• لم تُختبَر ميزة التحديث مع عدة mvs تُوجَّه إلى النموذج الهدف نفسه.