الوصف
يُعد Apache Parquet تنسيق تخزين عمودي شائعًا على نطاق واسع في نظام Hadoop البيئي. ويدعم ClickHouse عمليات القراءة والكتابة بهذا التنسيق.مطابقة أنواع البيانات
يوضح الجدول أدناه كيفية تطابق أنواع بيانات Parquet مع أنواع البيانات في ClickHouse.
عند كتابة ملف Parquet، تُحوَّل أنواع البيانات التي لا تملك نوع Parquet مطابقًا إلى أقرب نوع متاح:
يمكن أن تكون Arrays متداخلة، ويمكن أن تأخذ قيمة من النوع
Nullable كوسيط. كما يمكن أيضًا أن تكون الأنواع Tuple وMap متداخلة.
الأعداد الصحيحة واسعة النطاق
افتراضيًا، يكتب ClickHouse القيمInt128 وUInt128 وInt256 وUInt256 كقيم FIXED_LEN_BYTE_ARRAY(16/32) غير مرفقة بتعليقات توضيحية وبترتيب little-endian. يظل هذا التمثيل القديم هو الافتراضي كي تتمكن إصدارات ClickHouse الأقدم من قراءة الملفات.
عيّن output_format_parquet_wide_integer_as_decimal = 1 لاستخدام تمثيل DECIMAL القياسي في Parquet بدلًا من ذلك:
يوفر التمثيل العشري ترتيبًا رقميًا لإحصاءات مقاطع الأعمدة وفهارس الصفحات القياسية في Parquet، مما يتيح لـ ClickHouse استخدام تقليم القيم الدنيا/العليا لمجموعات الصفوف والصفحات. يقرأ ClickHouse كلا الترميزين. بالنسبة إلى الدقة العشرية 39، يعيد استنتاج المخطط النوع
Decimal(39, 0)، المدعوم بـ Decimal256؛ حدّد بنية صريحة من Int128 أو UInt128 لاستعادة نوع عدد صحيح واسع النطاق. تتجاوز الدقة العشرية 77 أو 78 نطاق Decimal256 في ClickHouse، لذا تتطلب قراءة تلك الملفات بنية صريحة متوافقة من Int256 أو UInt256. مع بنية صريحة لعدد صحيح واسع النطاق، يقبل ClickHouse القيم العشرية القياسية المخزنة إما كـ BYTE_ARRAY أو FIXED_LEN_BYTE_ARRAY بأي عرض صالح، ويتحقق من نطاق كل قيمة بعد إزالة تمديد الإشارة.
تدعم بعض عملاء Parquet الدقة العشرية حتى 38 فقط، بينما تدعم أنواع الأعداد العشرية عالية المستوى في Arrow الدقة حتى 76 فقط. قد يرفض هؤلاء العملاء تمثيل الدقة 77/78 رغم أن مخططه وعرضه الفيزيائي البالغ 33 بايت يتوافقان مع Parquet. اترك الإعداد معطّلًا عندما يجب أن تقرأ الملفات إصدارات ClickHouse الأقدم أو العملاء ذوو الحدود العشرية الأصغر.
قد تختلف أنواع بيانات أعمدة جداول ClickHouse عن الحقول المقابلة في بيانات Parquet المُدرجة. عند إدراج البيانات، يفسّر ClickHouse أنواع البيانات وفقًا للجدول أعلاه، ثم يحوّل البيانات إلى نوع البيانات المحدد لعمود جدول ClickHouse. على سبيل المثال، يمكن قراءة عمود Parquet من النوع UINT_32 إلى عمود ClickHouse من النوع IPv4.
بالنسبة إلى بعض أنواع Parquet، لا يوجد نوع مطابق لها بشكل وثيق في ClickHouse. نقرأها كما يلي:
- تمثل
TIMESTAMPمعisAdjustedToUTC=falseوقت الساعة المحلي (حقول السنة والشهر واليوم والساعة والدقيقة والثانية والأجزاء من الثانية ضمن منطقة زمنية محلية، بغض النظر عن المنطقة الزمنية المحددة التي تُعد محلية)، تمامًا مثل SQLTIMESTAMP WITHOUT TIME ZONE. إلا أن ClickHouse يقرؤها كما لو كانت طابعًا زمنيًا بتوقيت UTC. على سبيل المثال، تصبح القيمة2025-09-29 18:42:13.000(التي تمثل قراءة لساعة محلية) هي2025-09-29 18:42:13.000(DateTime64(3, 'UTC')الذي يمثل نقطة زمنية). وإذا حُوِّلت إلى String، فإنها تعرض السنة والشهر واليوم والساعة والدقيقة والثانية والأجزاء من الثانية بشكل صحيح، ويمكن بعد ذلك تفسيرها على أنها تقع ضمن منطقة زمنية محلية ما بدلًا من UTC. وعلى نحو غير بديهي، فإن تغيير النوع منDateTime64(3, 'UTC')إلىDateTime64(3)لن يفيد، لأن كلا النوعين يمثل نقطة زمنية لا قراءة ساعة، لكنDateTime64(3)سيُنسَّق بشكل غير صحيح باستخدام المنطقة الزمنية المحلية. - يُقرأ
INTERVALحاليًا على أنهFixedString(12)مع التمثيل الثنائي الخام للفاصل الزمني، كما هو مُرمَّز في ملف Parquet.
الأنواع الجغرافية (GeoParquet)
يدعم ClickHouse قراءة أعمدة الهندسة وكتابتها وفقًا لمواصفة GeoParquet. وتُخزَّن أعمدة الهندسة كحمولاتBYTE_ARRAY مُرمَّزة بتنسيق WKB (أو WKT عند القراءة)، مع مفتاح JSON باسم geo ضمن بيانات Parquet الوصفية على مستوى الملف يوضّح ترميز كل عمود هندسي ونوعه الهندسي ونظام CRS الخاص به.
سلوك القراءة
عند القراءة، تُحوَّل أعمدة الهندسة إلى الأنواع الجغرافية المناظرة لها في ClickHouse:- يُقرأ العمود المُعرَّف كـ
PointأوMultiPointأوLineStringأوPolygonأوMultiLineStringأوMultiPolygonإلى نوع ClickHouse الجغرافي المطابق. - يُقرأ العمود الذي يحتوي على أنواع هندسية متعددة أو غير معروفة إلى النوع
Geometry، وهوVariantيضم جميع الأنواع الجغرافية المدعومة. - إذا كان نوع العمود المطلوب هو
String، فتُتجاهَل البيانات الوصفية الخاصة بـ GeoParquet وتُعاد حمولة الشكل الهندسي الخام المرمَّزة كما هي — سواء كانت بايتات WKB أو WKT، بحسب الترميز الذي يعلنه عمود GeoParquet. وينطبق ذلك أيضًا إذا كان الإعدادinput_format_parquet_allow_geoparquet_parserمضبوطًا على0.
سلوك الكتابة
عند الكتابة، تُرمَّز الأعمدة ذات المستوى الأعلى من النوعPoint أو MultiPoint أو LineString أو Polygon أو MultiLineString أو MultiPolygon على هيئة BYTE_ARRAY (WKB)، وتُضاف بيانات geo الوصفية المناسبة بتنسيق JSON إلى تذييل ملف Parquet. كما يُرمَّز Geometry ذو المستوى الأعلى من النوع Variant أيضًا كحمولة BYTE_ARRAY بتنسيق WKB (إذ تُحوَّل قيمه الفرعية إلى WKB وتُخزَّن في عمود Nullable(String))، ولكن لا تُصدَر له أي بيانات وصفية geo، لذلك لا تُتعرَّف النتيجة كعمود هندسي من نوع GeoParquet عند القراءة. أما الأنواع الأخرى المرتبطة بالبيانات الجغرافية، مثل Ring، فتُكتب باستخدام تمثيلها الأصلي الداخلي من دون أي بيانات وصفية لـ GeoParquet. ويمكن تعطيل هذا السلوك بالكامل عبر ضبط output_format_parquet_geometadata على 0، وفي هذه الحالة حتى أنواع البيانات الجغرافية المدعومة تُكتب باستخدام تمثيلها الأصلي الداخلي (Point كـ Tuple(Float64, Float64)، وLineString كـ Array(Point)، وPolygon كـ Array(Array(Point))، وهكذا)، ولا تُصدَر أي بيانات وصفية لـ GeoParquet.
يجب أن تظهر أعمدة Geometry في جذر المخطط أو تكون متداخلة داخل Tuple (struct)؛ أما تضمينها داخل Array أو Map فغير مدعوم. كذلك، لا يدعم النوع Nullable الأعمدة الجغرافية.
مثال للاستخدام
إدراج البيانات
باستخدام ملف Parquet باسمfootball.parquet ويحتوي على البيانات التالية:
قراءة البيانات
يمكنك قراءة البيانات باستخدام تنسيقParquet:
محرك الجدول HDFS.