قالب Dataflow من BigQuery إلى ClickHouse

قالب BigQuery إلى ClickHouse هو مسار معالجة دفعي يُدخِل البيانات من جدول BigQuery إلى جدول ClickHouse. يمكن للقالب قراءة الجدول بالكامل أو تصفية سجلات محددة باستخدام استعلام SQL مُقدَّم.

متطلبات مسار المعالجة

يجب أن يكون جدول BigQuery المصدر موجودًا.
يجب أن يكون جدول ClickHouse الهدف موجودًا.
يجب أن يكون مضيف ClickHouse متاحًا من الأجهزة العاملة في Dataflow.

معلمات القالب

اسم المعلمة	وصف المعلمة	مطلوب	ملاحظات
`jdbcUrl`	عنوان URL لـ JDBC الخاص بـ ClickHouse بالتنسيق `jdbc:clickhouse://<host>:<port>/<schema>`.	✅	لا تُضِف اسم المستخدم وكلمة المرور كخيارات JDBC. ويمكن إضافة أي خيار JDBC آخر في نهاية عنوان URL الخاص بـ JDBC. بالنسبة إلى مستخدمي ClickHouse Cloud، أضِف `ssl=true&sslmode=NONE` إلى `jdbcUrl`.
`clickHouseUsername`	اسم مستخدم ClickHouse المستخدم للمصادقة.	✅
`clickHousePassword`	كلمة مرور ClickHouse المستخدمة للمصادقة.	✅
`clickHouseTable`	جدول ClickHouse الهدف الذي ستُدرَج فيه البيانات.	✅
`maxInsertBlockSize`	الحد الأقصى لحجم الكتلة للإدراج، إذا كنا نتحكم في إنشاء الكتل للإدراج (خيار `ClickHouseIO`).		خيار `ClickHouseIO`.
`insertDistributedSync`	إذا كان هذا الإعداد مُمكّنًا، فإن insert query إلى Distributed تنتظر حتى يتم إرسال البيانات إلى جميع العقد في cluster. (خيار `ClickHouseIO`).		خيار `ClickHouseIO`.
`insertQuorum`	بالنسبة إلى استعلامات INSERT في جدول Replicated، انتظر اكتمال الكتابة إلى العدد المحدد من replicas واجعل إضافة البيانات خطية. 0 - معطّل.		خيار `ClickHouseIO`. هذا الإعداد معطّل في إعدادات الخادم الافتراضية.
`insertDeduplicate`	بالنسبة إلى استعلامات INSERT في جدول Replicated، يحدد ما إذا كان ينبغي تنفيذ إزالة التكرار لكتل الإدراج.		خيار `ClickHouseIO`.
`maxRetries`	الحد الأقصى لعدد محاولات إعادة التنفيذ لكل عملية insert.		خيار `ClickHouseIO`.
`InputTableSpec`	جدول BigQuery المطلوب القراءة منه. حدِّد إما `inputTableSpec` أو `query`. وعند تعيينهما معًا، تكون الأولوية للمعلمة `query`. مثال: `<BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>`.		يقرأ البيانات مباشرةً من تخزين BigQuery باستخدام BigQuery Storage Read API. انتبه إلى قيود Storage Read API.
`outputDeadletterTable`	جدول BigQuery المخصّص للرسائل التي تعذّر وصولها إلى جدول الإخراج. إذا لم يكن الجدول موجودًا، فسيتم إنشاؤه أثناء تنفيذ مسار المعالجة. وإذا لم يتم تحديده، فسيُستخدم `<outputTableSpec>_error_records`. على سبيل المثال: `<PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>`.
`query`	استعلام SQL المستخدم لقراءة البيانات من BigQuery. إذا كانت مجموعة بيانات BigQuery في مشروع مختلف عن job الخاصة بـ Dataflow، فحدِّد الاسم الكامل لمجموعة البيانات في استعلام SQL، على سبيل المثال: `<PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>`. تكون القيمة الافتراضية GoogleSQL ما لم تكن `useLegacySql` تساوي `true`.		يجب تحديد `inputTableSpec` أو `query`. وإذا عيّنت المعلمتين معًا، يستخدم القالب المعلمة `query`. مثال: `SELECT * FROM sampledb.sample_table`.
`useLegacySql`	اضبطها على `true` لاستخدام SQL القديمة. لا تنطبق هذه المعلمة إلا عند استخدام المعلمة `query`. القيمة الافتراضية هي `false`.
`queryLocation`	تكون مطلوبة عند القراءة من عرض مصرَّح له بدون إذن الوصول إلى الجدول الأساسي. على سبيل المثال، `US`.
`queryTempDataset`	حدِّد مجموعة بيانات موجودة لإنشاء الجدول المؤقت لتخزين نتائج query. على سبيل المثال، `temp_dataset`.
`KMSEncryptionKey`	عند القراءة من BigQuery باستخدام مصدر query، استخدم مفتاح Cloud KMS هذا لتشفير أي جداول مؤقتة يتم إنشاؤها. على سبيل المثال، `projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key`.

يمكن الاطلاع على القيم الافتراضية لجميع معلمات ClickHouseIO في موصل Apache Beam لـ ClickHouseIO

مخطط جدولَي المصدر والهدف

لتحميل مجموعة بيانات BigQuery إلى ClickHouse بكفاءة، ينفّذ مسار المعالجة عملية استنتاج للأعمدة عبر المراحل التالية:

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

ومع ذلك، يجب أن تتضمن مجموعة بيانات BigQuery لديك (سواء كانت جدولًا أو استعلامًا) أسماء الأعمدة نفسها تمامًا الموجودة في جدول ClickHouse الهدف.

مطابقة أنواع البيانات

تُحوَّل أنواع BigQuery استنادًا إلى تعريف جدول ClickHouse لديك. لذلك، يوضّح الجدول أعلاه المطابقة الموصى بها التي ينبغي اعتمادها في جدول ClickHouse الهدف (لجدول أو query معيّن في BigQuery):

نوع BigQuery	نوع ClickHouse	ملاحظات
نوع Array	نوع Array	يجب أن يكون النوع الداخلي أحد أنواع البيانات الأولية المدعومة والمذكورة في هذا الجدول.
نوع Boolean	نوع Bool
نوع Date	نوع Date
نوع Datetime	نوع Datetime	يعمل أيضًا مع `Enum8` و`Enum16` و`FixedString`.
نوع String	نوع String	في BigQuery، تُعد جميع أنواع Int (`INT`, `SMALLINT`, `INTEGER`, `BIGINT`, `TINYINT`, `BYTEINT`) أسماء مستعارة لـ `INT64`. نوصي بتعيين حجم Integer المناسب في ClickHouse، لأن القالب سيحوّل العمود استنادًا إلى نوع العمود المحدد (`Int8`, `Int16`, `Int32`, `Int64`).
الأنواع الرقمية - أنواع Integer	أنواع Integer	في BigQuery، تُعد جميع أنواع Int (`INT`, `SMALLINT`, `INTEGER`, `BIGINT`, `TINYINT`, `BYTEINT`) أسماء مستعارة لـ `INT64`. نوصي بتعيين حجم Integer المناسب في ClickHouse، لأن القالب سيحوّل العمود استنادًا إلى نوع العمود المحدد (`Int8`, `Int16`, `Int32`, `Int64`). كما سيحوّل القالب أيضًا أنواع Int غير المعيّنة إذا استُخدمت في جدول ClickHouse (`UInt8`, `UInt16`, `UInt32`, `UInt64`).
الأنواع الرقمية - أنواع Float	أنواع Float	أنواع ClickHouse المدعومة: `Float32` و`Float64`

تشغيل قالب

يتوفر قالب ‏BigQuery إلى ClickHouse للتشغيل عبر Google Cloud CLI.

احرص على مراجعة هذا المستند، ولا سيما الأقسام الواردة أعلاه، لفهم متطلبات تهيئة قالب والمتطلبات المسبقة الخاصة به فهمًا كاملًا.

Google Cloud Console
Google Cloud CLI

سجّل الدخول إلى Google Cloud Console وابحث عن DataFlow.

اضغط على الزر CREATE JOB FROM TEMPLATE
بعد فتح نموذج قالب، أدخل اسم المهمة وحدد المنطقة المطلوبة.
في حقل DataFlow Template، اكتب ClickHouse أو BigQuery، ثم اختر قالب ‏BigQuery to ClickHouse
بعد الاختيار، سيتوسع النموذج ليتيح لك إدخال تفاصيل إضافية:
- عنوان JDBC URL لخادم ClickHouse، بالتنسيق التالي jdbc:clickhouse://host:port/schema.
- اسم مستخدم ClickHouse.
- اسم الجدول الهدف في ClickHouse.

خيار كلمة مرور ClickHouse مُشار إليه على أنه اختياري، وذلك لحالات الاستخدام التي لا تكون فيها كلمة مرور مُعدّة. لإضافتها، يُرجى التمرير إلى أسفل حتى خيار Password for ClickHouse Endpoint.

خصّص وأضف أي إعدادات مرتبطة بـ BigQuery/ClickHouseIO، كما هو موضح في قسم معلمات القالب

تثبيت `gcloud` CLI وتهيئته

إذا لم يكن gcloud CLI مثبتًا بالفعل، فثبّته.
اتبع قسم Before you begin في هذا الدليل لإعداد التهيئات والإعدادات والأذونات المطلوبة لتشغيل DataFlow قالب.

تشغيل الأمر

استخدم الأمر gcloud dataflow flex-template run لتشغيل مهمة Dataflow تستخدم Flex قالب.فيما يلي مثال على الأمر:

gcloud dataflow flex-template run "bigquery-clickhouse-dataflow-$(date +%Y%m%d-%H%M%S)" \
 --template-file-gcs-location "gs://clickhouse-dataflow-templates/bigquery-clickhouse-metadata.json" \
 --parameters inputTableSpec="<bigquery table id>",jdbcUrl="jdbc:clickhouse://<clickhouse host>:<clickhouse port>/<schema>?ssl=true&sslmode=NONE",clickHouseUsername="<username>",clickHousePassword="<password>",clickHouseTable="<clickhouse target table>"

شرح مكوّنات الأمر

اسم المهمة: النص الذي يلي الكلمة المفتاحية run هو اسم المهمة الفريد.
ملف قالب: يحدد JSON file المشار إليه بواسطة --template-file-gcs-location بنية قالب وتفاصيل المعلمات المقبولة. مسار الملف المذكور عام وجاهز للاستخدام.
Parameters: تُفصل Parameters بفواصل. وبالنسبة إلى المعلمات النصية، أَحِط القيم بعلامات اقتباس مزدوجة.

الاستجابة المتوقعة

بعد تشغيل الأمر، ينبغي أن ترى استجابة مشابهة لما يلي:

job:
  createTime: '2025-01-26T14:34:04.608442Z'
  currentStateTime: '1970-01-01T00:00:00Z'
  id: 2025-01-26_06_34_03-13881126003586053150
  location: us-central1
  name: bigquery-clickhouse-dataflow-20250126-153400
  projectId: ch-integrations
  startTime: '2025-01-26T14:34:04.608442Z'

مراقبة المهمة

انتقل إلى علامة التبويب Dataflow Jobs في Google Cloud Console لمراقبة حالة المهمة. ستجد تفاصيل المهمة، بما في ذلك مدى التقدّم وأي أخطاء:

استكشاف الأخطاء وإصلاحها

خطأ تجاوز الحد الإجمالي للذاكرة (الرمز 241)

يحدث هذا الخطأ عندما تستنفد ClickHouse الذاكرة أثناء معالجة دفعات كبيرة من البيانات. لحل هذه المشكلة:

زيادة موارد المثيل: قم بترقية خادم ClickHouse إلى مثيل أكبر مزود بذاكرة أكبر للتعامل مع حمل معالجة البيانات.
تقليل حجم الدفعة: عدّل حجم الدفعة في إعدادات مهمة Dataflow لإرسال أجزاء أصغر من البيانات إلى ClickHouse، مما يقلل استهلاك الذاكرة لكل دفعة. يمكن أن تساعد هذه التغييرات في تحقيق توازن في استخدام الموارد أثناء إدخال البيانات.

الشيفرة المصدرية للقالب

تتوفّر الشيفرة المصدرية للقالب في:

GoogleCloudPlatform/DataflowTemplates — المستودع الأصلي على Google Cloud Platform.
ClickHouse/DataflowTemplates — النسخة المتفرعة الخاصة بـ ClickHouse.

​متطلبات مسار المعالجة

​معلمات القالب

​مخطط جدولَي المصدر والهدف

​مطابقة أنواع البيانات

​تشغيل قالب

​تثبيت gcloud CLI وتهيئته

​تشغيل الأمر

​شرح مكوّنات الأمر

​الاستجابة المتوقعة

​مراقبة المهمة

​استكشاف الأخطاء وإصلاحها

​خطأ تجاوز الحد الإجمالي للذاكرة (الرمز 241)

​الشيفرة المصدرية للقالب

متطلبات مسار المعالجة

معلمات القالب

مخطط جدولَي المصدر والهدف

مطابقة أنواع البيانات

تشغيل قالب

تثبيت `gcloud` CLI وتهيئته

تشغيل الأمر

شرح مكوّنات الأمر

الاستجابة المتوقعة

مراقبة المهمة

استكشاف الأخطاء وإصلاحها

خطأ تجاوز الحد الإجمالي للذاكرة (الرمز 241)

الشيفرة المصدرية للقالب