المرجع التقني

يُفضَّل عدم استخدام المستخدم default؛ وبدلاً من ذلك، أنشئ مستخدمًا مخصّصًا لاستخدامه مع وجهة Fivetran هذه فقط. ستؤدي الأوامر التالية، عند تنفيذها باستخدام المستخدم default، إلى إنشاء مستخدم جديد باسم fivetran_user ومنحه الامتيازات المطلوبة.

CREATE USER fivetran_user IDENTIFIED BY '<password>'; -- use a secure password generator

GRANT CURRENT GRANTS ON *.* TO fivetran_user;

بالإضافة إلى ذلك، يمكنك سحب صلاحية الوصول إلى بعض قواعد البيانات من المستخدم fivetran_user. على سبيل المثال، بتنفيذ تعليمة SQL التالية، نقيّد الوصول إلى قاعدة البيانات default:

REVOKE ALL ON default.* FROM fivetran_user;

يمكنك تنفيذ هذه العبارات في وحدة تحكم ClickHouse SQL.

تدعم وجهة ClickHouse Cloud ملف إعداد JSON اختياريًا لحالات الاستخدام المتقدمة. ويتيح لك هذا الملف ضبط سلوك الوجهة بدقة من خلال تجاوز الإعدادات الافتراضية التي تتحكم في أحجام الدُفعات، والتوازي، ومجمّعات الاتصال، ومهلات الطلبات.

يجب أن يكون الملف بصيغة JSON صالحة وأن يتوافق مع المخطط الموضّح أدناه.

إذا احتجت إلى تعديل الإعداد بعد الإعداد الأولي، يمكنك تحرير إعدادات الوجهة في لوحة معلومات Fivetran ورفع ملف مُحدَّث.

يحتوي ملف الإعداد على قسم رئيسي:

{
  "destination_configurations": { ... }
}

يمكنك ضمنه تحديد الإعدادات التالية التي تتحكم في السلوك الداخلي لموصل وجهة ClickHouse نفسه. تؤثر هذه الإعدادات في كيفية معالجة الموصل للبيانات قبل إرسالها إلى ClickHouse.

جميع الحقول اختيارية. إذا لم يتم تحديد حقل، فستُستخدم القيمة الافتراضية. إذا كانت قيمة ما خارج النطاق المسموح، فستُبلغ الوجهة عن خطأ أثناء المزامنة. تُتجاهل الحقول غير المعروفة بصمت (مع تسجيل تحذير) ولا تتسبب في أخطاء، مما يتيح التوافق المستقبلي عند إضافة إعدادات جديدة.

مثال:

{
  "destination_configurations": {
    "write_batch_size": 50000,
    "select_batch_size": 200
  }
}

تربط وجهة Fivetran ClickHouse أنواع بيانات Fivetran بأنواع ClickHouse على النحو التالي:

يمكن لمصادر Fivetran إرسال قيم التاريخ والوقت ضمن النطاق 0001-01-01, 9999-12-31. تكون نطاقات أنواع التاريخ في ClickHouse Cloud أضيق، لذا تُقصَر القيم الواقعة خارج النطاق المدعوم بصمت على أقرب حد:

• الحد الأعلى لـ INSTANT هو 2262-04-11 23:47:16 لأن DateTime64(9) يخزّن النانوثواني منذ epoch بصيغة int64، وتوافق 2^63 - 1 نانوثانية هذا التاريخ. يدعم ClickHouse نفسه DateTime64 بدقة <= 9 حتى 2299-12-31 23:59:59.
• الحد الأعلى لـ LOCALDATETIME مقيَّد أيضًا عند 2262-04-11 23:47:16 بسبب خلل معروف في مشغّل ClickHouse للغة Go، حيث يُستدعى time.Time.UnixNano() لجميع درجات دقة DateTime64 قبل تغيير المقياس، مما يسبب overflow في int64 للتواريخ التي تتجاوز 2262 حتى عند الدقة 0.

تستخدم وجهة ClickHouse Cloud محركًا من نوع Replacing من عائلة SharedMergeTree (وتحديدًا، SharedReplacingMergeTree)، ويُحدَّد الإصدار بواسطة العمود _fivetran_synced.

يُنشأ كل عمود، باستثناء المفاتيح الأساسية (مفاتيح الترتيب) وأعمدة البيانات الوصفية الخاصة بـ Fivetran، بنوع Nullable(T)، حيث إن T هو نوع في ClickHouse Cloud استنادًا إلى تعيين أنواع البيانات.

تختلف بنية الجدول بحسب وضع المزامنة المُعدّ للموصل: الحذف المنطقي (الافتراضي) أو وضع السجل التاريخي (SCD Type 2).

في وضع الحذف المنطقي، يتضمن كل جدول وجهة أعمدة البيانات الوصفية التالية:

على سبيل المثال، يحتوي جدول المصدر users على عمود مفتاح أساسي id (INT) وعمود عادي name (STRING). سيُعرَّف جدول الوجهة على النحو التالي:

CREATE TABLE `users`
(
    `id`                Int32,
    `name`              Nullable(String),
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY id
SETTINGS index_granularity = 8192

في هذه الحالة، يُختار العمود id كمفتاح فرز للجدول.

إذا كان جدول المصدر يحتوي على عدة مفاتيح أساسية، فستُستخدم بحسب ترتيب ظهورها في تعريف جدول المصدر في Fivetran.

على سبيل المثال، توجد جدول مصدر باسم items يضم أعمدة المفتاح الأساسي id (INT) وname (STRING)، بالإضافة إلى عمود عادي إضافي هو description (STRING). سيُعرَّف جدول الوجهة على النحو التالي:

CREATE TABLE `items`
(
    `id`                Int32,
    `name`              String,
    `description`       Nullable(String),
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, name)
SETTINGS index_granularity = 8192

في هذه الحالة، يُختار العمودان id وname كمفتاحَي فرز للجدول.

إذا كان الجدول المصدر لا يحتوي على مفاتيح أساسية، فستضيف Fivetran معرّفًا فريدًا في عمود باسم _fivetran_id. لنفترض وجود جدول events لا يضم في المصدر سوى العمودين event (STRING) وtimestamp (LOCALDATETIME). في هذه الحالة، يكون جدول الوجهة كما يلي:

CREATE TABLE events
(
    `event`             Nullable(String),
    `timestamp`         Nullable(DateTime),
    `_fivetran_id`      String,
    `_fivetran_synced`  DateTime64(9, 'UTC'),
    `_fivetran_deleted` Bool
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY _fivetran_id
SETTINGS index_granularity = 8192

نظرًا لأن _fivetran_id فريد، ولعدم وجود خيارات أخرى للمفتاح الأساسي، يُستخدم كمفتاح فرز للجدول.

عند تمكين وضع السجل التاريخي، تحتفظ الوجهة بكل إصدار من كل سجل بدلًا من استبدال القيم السابقة. وهذا يطبّق Slowly Changing Dimension Type 2 ‏(SCD Type 2)، مع الحفاظ على سجل تدقيق كامل لجميع التغييرات.

في وضع السجل التاريخي، يتضمن كل جدول وجهة أعمدة البيانات الوصفية التالية:

يُدرج العمود _fivetran_start دائمًا في عبارة ORDER BY باعتباره العنصر الأخير في مفتاح الفرز المركب. وهذا يتيح وجود عدة إصدارات من السجل نفسه (بأوقات بدء مختلفة) معًا داخل الجدول.

عند تحديث سجل:

• تُضبط قيمة _fivetran_end في الإصدار السابق على قيمة _fivetran_start في الإصدار الجديد ناقص نانوثانية واحدة، وتُضبط قيمة _fivetran_active على false.
• يُدرج الإصدار الجديد مع ضبط _fivetran_active على true وضبط _fivetran_end على 2262-04-11 23:47:16.000000000 (وهي القيمة القصوى لـ DateTime64(9)).

على سبيل المثال، يحتوي الجدول المصدر users على العمود id (INT) كمفتاح أساسي، والأعمدة العادية name (STRING) وstatus (STRING). وسيُعرَّف الجدول الوجهة في وضع السجل التاريخي على النحو التالي:

CREATE TABLE `users`
(
    `id`               Int32,
    `name`             Nullable(String),
    `status`           Nullable(String),
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, _fivetran_start)
SETTINGS index_granularity = 8192

في هذه الحالة، يشكّل id و _fivetran_start مفتاح الفرز المركّب.

بعد بضع عمليات المزامنة، قد يحتوي الجدول على البيانات التالية:

يحتوي السجل id=1 على إصدارين: الإصدار الأصلي (name 1، غير نشط) والإصدار المحدَّث (name 11، نشط). أما السجل id=2، فلديه إصدار واحد فقط، وهو النشط حاليًا.

إذا كان الجدول المصدر يحتوي على عدة مفاتيح أساسية، فستُدرَج جميعها في ORDER BY مع _fivetran_start باعتباره العنصر الأخير.

على سبيل المثال، لنفترض وجود جدول مصدر باسم items يحتوي على عمودَي مفتاح أساسي هما id (INT) وname (STRING)، بالإضافة إلى عمود عادي آخر هو description (STRING). ويُعرَّف جدول الوجهة في وضع السجل التاريخي على النحو التالي:

CREATE TABLE `items`
(
    `id`               Int32,
    `name`             String,
    `description`      Nullable(String),
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (id, name, _fivetran_start)
SETTINGS index_granularity = 8192

في هذه الحالة، يُشكّل id وname و_fivetran_start مفتاح الفرز المركب.

إذا كان جدول المصدر لا يحتوي على مفاتيح أساسية، فستضيف Fivetran معرّفًا فريدًا في عمود باسم _fivetran_id، وسيُضاف _fivetran_start إلى مفتاح الفرز. لنفترض وجود جدول events لا يحتوي في المصدر إلا على العمودين event (STRING) وtimestamp (LOCALDATETIME). ويكون جدول الوجهة في وضع السجل التاريخي كما يلي:

CREATE TABLE events
(
    `event`            Nullable(String),
    `timestamp`        Nullable(DateTime),
    `_fivetran_id`     String,
    `_fivetran_synced` DateTime64(9, 'UTC'),
    `_fivetran_start`  DateTime64(9, 'UTC'),
    `_fivetran_end`    Nullable(DateTime64(9, 'UTC')),
    `_fivetran_active` Nullable(Bool)
) ENGINE = SharedReplacingMergeTree('/clickhouse/tables/{uuid}/{shard}', '{replica}', _fivetran_synced)
ORDER BY (_fivetran_id, _fivetran_start)
SETTINGS index_granularity = 8192

نظرًا إلى أن _fivetran_id و_fivetran_start يشكّلان مفتاح الفرز المركب.

ينفّذ SharedReplacingMergeTree إلغاء تكرار البيانات في الخلفية فقط أثناء عمليات الدمج وفي وقت غير معلوم. ومع ذلك، يمكن اختيار أحدث إصدار من البيانات من دون تكرارات عند الحاجة باستخدام الكلمة المفتاحية FINAL:

SELECT *
FROM example FINAL
LIMIT 1000 

راجِع قسم تحسين استعلامات القراءة" في دليل استكشاف الأخطاء وإصلاحها للاطّلاع على نصائح حول تحسين الاستعلامات.

تعيد وجهة ClickHouse Cloud المحاولة عند حدوث أخطاء شبكة عابرة باستخدام خوارزمية التراجع الأسي. وهذا آمن حتى إذا قامت الوجهة بإدراج البيانات، لأن محرك الجدول SharedReplacingMergeTree يتعامل مع أي نُسخ مكررة محتملة.