تكامل Amazon S3 مع ClickHouse Cloud

اربط تخزين الكائنات لديك بـ ClickHouse Cloud بسلاسة.

يوفّر S3 ClickPipe طريقة مُدارة بالكامل وعالية الاعتمادية لإدخال البيانات من Amazon S3 ومخازن الكائنات المتوافقة مع S3 إلى ClickHouse Cloud. وهو يدعم كلاً من الإدخال لمرة واحدة والإدخال المستمر مع ضمان المعالجة مرة واحدة فقط.

يمكن نشر S3 ClickPipes وإدارتها يدويًا باستخدام ClickPipes UI، وكذلك برمجيًا باستخدام OpenAPI وTerraform.

​

مصادر البيانات المدعومة

الاسم	الشعار	التفاصيل
Amazon S3		يتطلب الإدخال المستمر الترتيب المعجمي افتراضيًا، ولكن يمكن تهيئته أيضًا لإدخال الملفات بأي ترتيب.
Cloudflare R2 متوافق مع S3		يتطلب الإدخال المستمر الترتيب المعجمي. ولا يدعم الوضع غير المرتب.
DigitalOcean Spaces متوافق مع S3		يتطلب الإدخال المستمر الترتيب المعجمي. ولا يدعم الوضع غير المرتب.
OVH Object Storage متوافق مع S3		يتطلب الإدخال المستمر الترتيب المعجمي. ولا يدعم الوضع غير المرتب.

نظرًا لاختلاف تنسيقات URL وتنفيذات واجهة برمجة تطبيقات بين موفري خدمات تخزين الكائنات، ليست كل الخدمات المتوافقة مع S3 مدعومة بشكل مباشر. إذا كنت تواجه مشكلات مع خدمة غير مُدرجة أعلاه، فيُرجى التواصل مع فريقنا.

​

التنسيقات المدعومة

• JSON
• CSV
• TSV
• Parquet
• Avro

​

الميزات

​

الإدخال لمرة واحدة

افتراضيًا، يحمّل S3 ClickPipe جميع الملفات التي يطابقها نمط معيّن من الحاوية المحددة إلى جدول الوجهة في ClickHouse ضمن عملية دفعية واحدة. وبمجرد اكتمال مهمة الإدخال، يتوقف ClickPipe تلقائيًا. ويوفر وضع الإدخال لمرة واحدة هذا ضمان المعالجة مرة واحدة فقط، مما يضمن معالجة كل ملف بشكل موثوق من دون تكرار.

​

الإدخال المستمر

عند تمكين الإدخال المستمر، تقوم ClickPipes بإدخال البيانات باستمرار من المسار المحدد. ولتحديد ترتيب الإدخال، يعتمد S3 ClickPipe افتراضيًا على الترتيب المعجمي الضمني للملفات. كما يمكن تهيئته لإدخال الملفات بأي ترتيب باستخدام قائمة انتظار Amazon SQS متصلة بالحاوية.

​

الترتيب المعجمي

بشكل افتراضي، يفترض S3 ClickPipe أن الملفات تُضاف إلى الحاوية وفق الترتيب المعجمي، ويعتمد على هذا الترتيب الضمني لإدخال الملفات بالتسلسل. وهذا يعني أن أي ملف جديد يجب أن يكون اسمه أكبر معجميًا من آخر ملف جرى إدخاله. على سبيل المثال، ستُدخَل الملفات المسماة file1 وfile2 وfile3 بالتسلسل، ولكن إذا أُضيف ملف جديد باسم file 0 إلى الحاوية، فسيتم تجاهله لأن اسم الملف ليس أكبر معجميًا من آخر ملف جرى إدخاله.

في هذا الوضع، ينفّذ S3 ClickPipe تحميلًا أوليًا لـ جميع الملفات في المسار المحدد، ثم يفحص وجود ملفات جديدة على فاصل زمني قابل للتهيئة (30 ثانية افتراضيًا). لبدء الإدخال المستمر بعد ملف محدد، هيّئ Start after. ستتخطى ClickPipes الملفات التي تكون أقل من القيمة المُهيأة أو مساوية لها معجميًا، وتتابع إدخال الملفات الأحدث من تلك النقطة.

​

بأي ترتيب

راجع تهيئة الوضع غير المرتب للإدخال المستمر للحصول على إرشادات خطوة بخطوة.

يمكن تهيئة S3 ClickPipe لإدخال الملفات التي لا تملك ترتيبًا ضمنيًا عبر إعداد قائمة انتظار Amazon SQS متصلة بالحاوية، مع استخدام Amazon EventBridge اختياريًا كموجّه للأحداث. يتيح ذلك لـ ClickPipes الاستماع إلى أحداث إنشاء الكائنات وإدخال أي ملفات جديدة بغض النظر عن اصطلاح تسمية الملفات.

الوضع غير المرتب مدعوم فقط مع Amazon S3، وهو غير مدعوم للحاويات العامة أو الخدمات المتوافقة مع S3. كما يتطلب إعداد قائمة انتظار Amazon SQS متصلة بالحاوية، مع استخدام Amazon EventBridge اختياريًا كموجّه للأحداث.

في هذا الوضع، ينفّذ S3 ClickPipe تحميلًا أوليًا لكل الملفات في المسار المحدد، ثم يستمع إلى أحداث ObjectCreated:* في قائمة الانتظار التي تطابق المسار المحدد. وسيتم تجاهل أي رسالة تخص ملفًا سبق رصده، أو ملفًا لا يطابق المسار، أو حدثًا من نوع مختلف. لإدخال الملفات التي تُسلَّم عبر قائمة الانتظار فقط، فعّل تخطي التحميل الأولي. عند تفعيله، تتخطى ClickPipes الفحص الأولي للملفات الموجودة في المسار المحدد وتعالج فقط الملفات التي تُسلَّم عبر قائمة انتظار SQS.

تعيين بادئة/لاحقة للأحداث اختياري. وإذا فعلت ذلك، فتأكد من أنها تطابق المسار المحدد لـ ClickPipe. لا يتيح S3 وجود قواعد إشعارات متعددة ومتداخلة لأنواع الأحداث نفسها.

تُدخَل الملفات عند بلوغ الحد المعيّن في max insert bytes أو max file count، أو بعد فاصل زمني قابل للتهيئة (30 ثانية افتراضيًا). وإذا جرى تهيئة DLQ، فستُعاد الرسائل الفاشلة إلى قائمة الانتظار وتُعالَج مجددًا حتى عدد المرات المحدد في المعلَمة maxReceiveCount الخاصة بـ DLQ.

نوصي بشدة بتهيئة Dead-Letter-Queue (DLQ) لقائمة انتظار SQS، لتسهيل تصحيح الرسائل الفاشلة وإعادة محاولة معالجتها.

EventBridge إلى SQS

يمكن أيضًا إرسال إشعارات أحداث S3 إلى SQS عبر Amazon EventBridge. وهذا هو النهج الموصى به لمعظم حالات الاستخدام، لأن EventBridge يدعم تصفية أحداث أكثر تقدّمًا، والتوزيع إلى عدة وجهات، كما أنه لا يخضع لقيود S3 التي تفرض قاعدة إشعار واحدة فقط لكل نوع حدث ولكل بادئة. راجع تهيئة الوضع غير المرتب للإدخال المستمر للحصول على إرشادات خطوة بخطوة.

SNS إلى SQS

يمكن أيضًا إرسال إشعارات أحداث S3 إلى SQS عبر موضوع SNS. ويمكن استخدام ذلك إذا واجهت بعض قيود التكامل المباشر بين S3 وSQS. في هذه الحالة، ستحتاج إلى تفعيل خيار تسليم الرسائل الخام.

​

مطابقة أنماط الملفات

تتبع Object Storage ClickPipes معيار POSIX لمطابقة أنماط الملفات. جميع الأنماط حساسة لحالة الأحرف وتطابق المسار الكامل بعد اسم حاوية. ولتحسين الأداء، استخدم النمط الأكثر تحديدًا قدر الإمكان (على سبيل المثال، data-2024-*.csv بدلًا من *.csv).

​

الأنماط المدعومة

النمط	الوصف	مثال	يطابق
?	يطابق حرفًا واحدًا تمامًا (باستثناء /)	data-?.csv	data-1.csv, data-a.csv, data-x.csv
*	يطابق صفرًا أو أكثر من الأحرف (باستثناء /)	data-*.csv	data-1.csv, data-001.csv, data-report.csv, data-.csv
** تكراري	يطابق صفرًا أو أكثر من الأحرف (بما في ذلك /). يتيح اجتياز المجلدات بشكل تكراري.	logs/**/error.log	logs/error.log, logs/2024/error.log, logs/2024/01/error.log

أمثلة:

• https://bucket.s3.amazonaws.com/folder/*.csv
• https://bucket.s3.amazonaws.com/logs/**/data.json
• https://bucket.s3.amazonaws.com/file-?.parquet
• https://bucket.s3.amazonaws.com/data-2024-*.csv.gz

​

الأنماط غير المدعومة

النمط	الوصف	مثال	البدائل
{abc,def}	توسيع الأقواس المعقوفة.	{logs,data}/file.csv	أنشئ ClickPipes منفصلة لكل path.
{N..M}	توسيع النطاق العددي	file-{1..100}.csv	استخدم file-*.csv أو file-?.csv.

أمثلة:

• https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json
• https://bucket.s3.amazonaws.com/file-{1..100}.csv
• https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet

​

ضمان المعالجة مرة واحدة فقط

قد تحدث أنواع مختلفة من حالات الفشل عند استيعاب مجموعة بيانات كبيرة، ما قد يؤدي إلى عمليات إدراج جزئية أو بيانات مكررة. يتميز Object Storage ClickPipes بالقدرة على تحمل حالات فشل الإدراج ويوفر ضمان المعالجة مرة واحدة فقط. ويتحقق ذلك باستخدام جداول مرحلية مؤقتة. تُدرج البيانات أولًا في الجداول المرحلية. وإذا حدث خطأ ما أثناء عملية الإدراج هذه، يمكن إفراغ الجدول المرحلي ثم إعادة محاولة الإدراج من حالة نظيفة. ولا تُنقل الأقسام من الجدول المرحلي إلى الجدول الهدف إلا بعد اكتمال عملية الإدراج ونجاحها. لقراءة المزيد عن هذه الاستراتيجية، اطّلع على منشور المدونة هذا.

​

الأعمدة الافتراضية

لتتبّع الملفات التي تم إدخالها، أدرِج العمود الافتراضي _file ضمن قائمة تعيين الأعمدة. يحتوي العمود الافتراضي _file على اسم ملف الكائن المصدر، ويمكن استخدامه للاستعلام عن الملفات التي تمت معالجتها.

​

التحكم في الوصول

​

الأذونات

يدعم S3 ClickPipe حاويات S3 العامة والخاصة. ولا يدعم حاويات Requester Pays.

​

حاوية S3

يجب أن تسمح حاويات S3 بالإجراءات التالية ضمن سياسة الحاوية:

• s3:GetObject
• s3:ListBucket

​

قائمة انتظار SQS

عند استخدام الوضع غير المرتب، يجب أن تسمح سياسة قائمة الانتظار في SQS بالإجراءات التالية:

• sqs:ReceiveMessage
• sqs:DeleteMessage
• sqs:GetQueueAttributes
• sqs:ListQueues

​

المصادقة

​

بيانات اعتماد IAM

لاستخدام مفاتيح الوصول للمصادقة، اختر Credentials ضمن Authentication method عند إعداد اتصال ClickPipe. بعد ذلك، أدخِل معرّف مفتاح الوصول (مثل AKIAIOSFODNN7EXAMPLE) ومفتاح الوصول السري (مثل wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) في الحقلين Access key وSecret key، على الترتيب.

​

IAM role

لاستخدام الوصول المستند إلى الأدوار في المصادقة، اختر IAM role ضمن Authentication method عند إعداد اتصال ClickPipe.

اتّبع هذا الدليل لإنشاء دور بسياسة الثقة المطلوبة للوصول إلى S3. ثم أدخِل ARN لدور IAM ضمن IAM role ARN.

​

الوصول إلى الشبكة

تستخدم S3 ClickPipes مسارين منفصلين على الشبكة لاكتشاف البيانات الوصفية وإدخال البيانات: خدمة ClickPipes وخدمة ClickHouse Cloud، على التوالي. إذا كنت تريد تهيئة طبقة إضافية من أمان الشبكة (على سبيل المثال، لأسباب تتعلق بالامتثال)، فيجب تهيئة الوصول إلى الشبكة لكلا المسارين.

• بالنسبة إلى التحكم في الوصول المستند إلى عناوين IP، يجب أن تسمح سياسة حاوية S3 بعناوين IP الثابتة لمنطقة خدمة ClickPipes والمُدرجة هنا، بالإضافة إلى عناوين IP الثابتة الخاصة بخدمة ClickHouse Cloud. للحصول على عناوين IP الثابتة لمنطقة ClickHouse Cloud الخاصة بك، افتح نافذة طرفية ونفّذ:

  # استبدل <your-region> بمنطقة ClickHouse Cloud الخاصة بك
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .egress_ips[]'
  

• بالنسبة إلى التحكم في الوصول المستند إلى VPC endpoint، يجب أن تكون حاوية S3 في المنطقة نفسها التي توجد فيها خدمة ClickHouse Cloud، وأن يقيّد عمليات GetObject على معرّفات VPC endpoint الخاصة بخدمة ClickHouse Cloud. للحصول على VPC endpoints لمنطقة ClickHouse Cloud الخاصة بك، افتح نافذة طرفية ونفّذ:

  # استبدل <your-region> بمنطقة ClickHouse Cloud الخاصة بك
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .s3_endpoints[]'
  

​

الإعدادات المتقدمة

يوفّر ClickPipes إعدادات افتراضية مناسبة تلبي متطلبات معظم حالات الاستخدام. وإذا كانت حالة الاستخدام لديك تتطلب ضبطًا إضافيًا أكثر دقة، فيمكنك تعديل الإعدادات التالية:

الإعداد	القيمة الافتراضية	الوصف
Max insert bytes	10GB	عدد البايتات التي تُعالَج في دفعة إدراج واحدة.
Max file count	100	الحد الأقصى لعدد الملفات التي تُعالَج في دفعة إدراج واحدة.
Max threads	auto(3)	الحد الأقصى لعدد الخيوط المتزامنة لمعالجة الملفات.
Max insert threads	1	الحد الأقصى لعدد خيوط الإدراج المتزامنة لمعالجة الملفات.
Min insert block size bytes	1GB	الحد الأدنى لحجم البايتات في الكتلة التي يمكن إدراجها في جدول.
Max download threads	4	الحد الأقصى لعدد خيوط التنزيل المتزامنة.
Object storage polling interval	30s	يضبط الحد الأقصى لمدة الانتظار قبل إدراج البيانات في عنقود ClickHouse.
Start after	None	للإدخال المستمر المرتب، يتخطى الملفات التي يقل اسمها أو مسارها عن اسم الملف أو المسار المُكوَّن أو يساويه وفق الترتيب المعجمي.
Skip initial load	false	للإدخال المستمر غير المرتب، يتخطى الفحص الأولي للملفات الموجودة ويعالج إشعارات الكائنات فقط من قائمة انتظار SQS المُكوَّنة.
Parallel distributed insert select	2	إعداد parallel distributed insert select.
Parallel view processing	false	ما إذا كان سيتم تمكين الدفع إلى العروض المرفقة بالتوازي بدلًا من التسلسل.
Use cluster function	true	ما إذا كانت الملفات ستُعالَج بالتوازي عبر عدة عُقد.

​

التحجيم

يتم تحجيم Object Storage ClickPipes استنادًا إلى الحد الأدنى لحجم خدمة ClickHouse كما تحدده إعدادات التحجيم التلقائي الرأسي المُهيأة. ويُحدَّد حجم ClickPipe عند إنشاء الـ ClickPipe. ولن تؤثر أي تغييرات لاحقة على إعدادات خدمة ClickHouse في حجم ClickPipe.

لزيادة معدل النقل في عمليات استيعاب البيانات الكبيرة، نوصي بتحجيم خدمة ClickHouse قبل إنشاء ClickPipe.

​

القيود المعروفة

​

حجم الملف

لن تحاول ClickPipes سوى استيعاب الكائنات التي يبلغ حجمها 10GB أو أقل. وإذا كان حجم الملف أكبر من 10GB، فسيُضاف سجل خطأ إلى جدول الأخطاء المخصص في ClickPipes.

​

التوافق

على الرغم من أن بعض الخدمات متوافقة مع S3، فإنها تستخدم بنية URL مختلفة قد لا يتمكن S3 ClickPipe من تحليلها (على سبيل المثال، Backblaze B2)، أو تتطلب تكاملًا مع خدمات قائمة انتظار خاصة بكل مزوّد من أجل إدخال البيانات بشكل مستمر وغير مرتب. إذا كنت تواجه مشكلات مع خدمة غير مدرجة ضمن مصادر البيانات المدعومة، يُرجى التواصل مع فريقنا.

​

دعم العروض

العروض المُجسَّدة على الجدول الهدف مدعومة أيضًا. ستنشئ ClickPipes جداول مرحلية ليس فقط للجدول الهدف، بل أيضًا لأي عرض مُجسَّد تابع له.

لا ننشئ جداول مرحلية للعروض غير المُجسَّدة. وهذا يعني أنه إذا كان لديك جدول هدف يتبعه عرض مُجسَّد واحد أو أكثر في المراحل اللاحقة، فينبغي أن تتجنب هذه العروض المُجسَّدة تحديد البيانات عبر عرض من الجدول الهدف. وإلا، فقد تلاحظ فقدان بعض البيانات في العرض المُجسَّد.