> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Parquet

> مرجع لتنسيق Parquet

| إدخال | إخراج | الاسم المستعار |
| - | - | - |
| ✔ | ✔ | |

## الوصف

يُعد [Apache Parquet](https://parquet.apache.org/) تنسيق تخزين عمودي شائعًا على نطاق واسع في نظام Hadoop البيئي. ويدعم ClickHouse عمليات القراءة والكتابة بهذا التنسيق.

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

يوضح الجدول أدناه كيفية تطابق أنواع بيانات Parquet مع [أنواع البيانات](https://clickhouse.com/docs/ar/reference/data-types/index.md) في ClickHouse.

| نوع Parquet (منطقي أو محوَّل أو مادي) | نوع بيانات ClickHouse |
| - | - |
| `BOOLEAN` | [Bool](https://clickhouse.com/docs/ar/reference/data-types/boolean.md) |
| `UINT_8` | [UInt8](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md) |
| `INT_8` | [Int8](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md) |
| `UINT_16` | [UInt16](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md) |
| `INT_16` | [Int16](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md)/[Enum16](https://clickhouse.com/docs/ar/reference/data-types/enum.md) |
| `UINT_32` | [UInt32](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md) |
| `INT_32` | [Int32](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md) |
| `UINT_64` | [UInt64](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md) |
| `INT_64` | [Int64](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md) |
| `DATE` | [Date32](https://clickhouse.com/docs/ar/reference/data-types/date.md) |
| `TIMESTAMP` | [DateTime64](https://clickhouse.com/docs/ar/reference/data-types/datetime64.md) |
| `TIME` | [Time64](https://clickhouse.com/docs/ar/reference/data-types/time64.md) |
| `FLOAT` | [Float32](https://clickhouse.com/docs/ar/reference/data-types/float.md) |
| `DOUBLE` | [Float64](https://clickhouse.com/docs/ar/reference/data-types/float.md) |
| `INT96` | [DateTime64(9, 'UTC')](https://clickhouse.com/docs/ar/reference/data-types/datetime64.md) |
| `BYTE_ARRAY`, `UTF8`, `ENUM`, `BSON` | [String](https://clickhouse.com/docs/ar/reference/data-types/string.md) |
| `JSON` | [JSON](https://clickhouse.com/docs/ar/reference/data-types/newjson.md) |
| `FIXED_LEN_BYTE_ARRAY` | [FixedString](https://clickhouse.com/docs/ar/reference/data-types/fixedstring.md) |
| `DECIMAL` | [Decimal](https://clickhouse.com/docs/ar/reference/data-types/decimal.md) |
| `LIST` | [Array](https://clickhouse.com/docs/ar/reference/data-types/array.md) |
| `MAP` | [Map](https://clickhouse.com/docs/ar/reference/data-types/map.md) |
| struct | [Tuple](https://clickhouse.com/docs/ar/reference/data-types/tuple.md) |
| `FLOAT16` | [Float32](https://clickhouse.com/docs/ar/reference/data-types/float.md) |
| `UUID` | [FixedString(16)](https://clickhouse.com/docs/ar/reference/data-types/fixedstring.md) |
| `INTERVAL` | [FixedString(12)](https://clickhouse.com/docs/ar/reference/data-types/fixedstring.md) |
| `Point` (GeoParquet) | [Point](https://clickhouse.com/docs/ar/reference/data-types/geo.md#point) |
| `MultiPoint` (GeoParquet) | [MultiPoint](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multipoint) |
| `LineString` (GeoParquet) | [LineString](https://clickhouse.com/docs/ar/reference/data-types/geo.md#linestring) |
| `Polygon` (GeoParquet) | [Polygon](https://clickhouse.com/docs/ar/reference/data-types/geo.md#polygon) |
| `MultiLineString` (GeoParquet) | [MultiLineString](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multilinestring) |
| `MultiPolygon` (GeoParquet) | [MultiPolygon](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multipolygon) |
| هندسة مختلطة/غير معروفة (GeoParquet) | [Geometry](https://clickhouse.com/docs/ar/reference/data-types/geo.md#geometry) |
| `GEOMETRY`, `GEOGRAPHY` | [Point](https://clickhouse.com/docs/ar/reference/data-types/geo.md#point) أو [MultiPoint](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multipoint) أو [LineString](https://clickhouse.com/docs/ar/reference/data-types/geo.md#linestring) أو [Polygon](https://clickhouse.com/docs/ar/reference/data-types/geo.md#polygon) أو [MultiLineString](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multilinestring) أو [MultiPolygon](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multipolygon) أو [Geometry](https://clickhouse.com/docs/ar/reference/data-types/geo.md#geometry)، راجع [أنواع البيانات الهندسية](#geo-types) |
| `VARIANT` | [Dynamic](https://clickhouse.com/docs/ar/reference/data-types/dynamic.md) |
| `FILE` | [Tuple](https://clickhouse.com/docs/ar/reference/data-types/tuple.md) من حقول `Nullable`، راجع [أدناه](#file-type) |

عند كتابة ملف Parquet، تُحوَّل أنواع البيانات التي لا تملك نوع Parquet مطابقًا إلى أقرب نوع متاح:

| نوع بيانات ClickHouse | نوع Parquet |
| - | - |
| [IPv4](https://clickhouse.com/docs/ar/reference/data-types/ipv4.md) | `UINT_32` |
| [IPv6](https://clickhouse.com/docs/ar/reference/data-types/ipv6.md) | `FIXED_LEN_BYTE_ARRAY` (16 بايت) |
| [Date](https://clickhouse.com/docs/ar/reference/data-types/date.md) (16 بت) | `DATE` (32 بت) |
| [DateTime](https://clickhouse.com/docs/ar/reference/data-types/datetime.md) (32 بت، ثوانٍ) | `TIMESTAMP` (64 بت، مللي ثانية) |
| [Int128/UInt128/Int256/UInt256](https://clickhouse.com/docs/ar/reference/data-types/int-uint.md) | `FIXED_LEN_BYTE_ARRAY` (16/32 بايت، little-endian) |
| [Point](https://clickhouse.com/docs/ar/reference/data-types/geo.md#point) | `BYTE_ARRAY` (WKB) + بيانات GeoParquet الوصفية، أو `GEOMETRY` مع `output_format_parquet_geometry_logical_type` |
| [MultiPoint](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multipoint) | `BYTE_ARRAY` (WKB) + بيانات GeoParquet الوصفية، أو `GEOMETRY` مع `output_format_parquet_geometry_logical_type` |
| [LineString](https://clickhouse.com/docs/ar/reference/data-types/geo.md#linestring) | `BYTE_ARRAY` (WKB) + بيانات GeoParquet الوصفية، أو `GEOMETRY` مع `output_format_parquet_geometry_logical_type` |
| [Polygon](https://clickhouse.com/docs/ar/reference/data-types/geo.md#polygon) | `BYTE_ARRAY` (WKB) + بيانات GeoParquet الوصفية، أو `GEOMETRY` مع `output_format_parquet_geometry_logical_type` |
| [MultiLineString](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multilinestring) | `BYTE_ARRAY` (WKB) + بيانات GeoParquet الوصفية، أو `GEOMETRY` مع `output_format_parquet_geometry_logical_type` |
| [MultiPolygon](https://clickhouse.com/docs/ar/reference/data-types/geo.md#multipolygon) | `BYTE_ARRAY` (WKB) + بيانات GeoParquet الوصفية، أو `GEOMETRY` مع `output_format_parquet_geometry_logical_type` |
| [Geometry](https://clickhouse.com/docs/ar/reference/data-types/geo.md#geometry) | `BYTE_ARRAY` (WKB)، أو `GEOMETRY` + بيانات GeoParquet الوصفية مع `output_format_parquet_geometry_logical_type` |

يمكن أن تكون 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 بدلًا من ذلك:

| نوع ClickHouse | النوع المنطقي في Parquet | النوع الفيزيائي | ترميز القيمة |
| - | - | - | - |
| `UInt128` | `DECIMAL(39, 0)` | `FIXED_LEN_BYTE_ARRAY(17)` | بايت إشارة صفري، يتبعه مقدار غير موقّع من 16 بايت بترتيب big-endian |
| `UInt256` | `DECIMAL(78, 0)` | `FIXED_LEN_BYTE_ARRAY(33)` | بايت إشارة صفري، يتبعه مقدار غير موقّع من 32 بايت بترتيب big-endian |
| `Int128` | `DECIMAL(39, 0)` | `FIXED_LEN_BYTE_ARRAY(17)` | قيمة بمتمم الاثنين من 16 بايت بترتيب big-endian، مع تمديد الإشارة إلى 17 بايت |
| `Int256` | `DECIMAL(77, 0)` | `FIXED_LEN_BYTE_ARRAY(33)` | قيمة بمتمم الاثنين من 32 بايت بترتيب big-endian، مع تمديد الإشارة إلى 33 بايت |

يوفر التمثيل العشري ترتيبًا رقميًا لإحصاءات مقاطع الأعمدة وفهارس الصفحات القياسية في 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 أنواع البيانات وفقًا للجدول أعلاه، ثم [يحوّل](https://clickhouse.com/docs/ar/reference/functions/regular-functions/type-conversion-functions.md#CAST) البيانات إلى نوع البيانات المحدد لعمود جدول ClickHouse. على سبيل المثال، يمكن قراءة عمود Parquet من النوع `UINT_32` إلى عمود ClickHouse من النوع [IPv4](https://clickhouse.com/docs/ar/reference/data-types/ipv4.md).

بالنسبة إلى بعض أنواع Parquet، لا يوجد نوع مطابق لها بشكل وثيق في ClickHouse. نقرأها كما يلي:

* تمثل `TIMESTAMP` مع `isAdjustedToUTC=false` وقت الساعة المحلي (حقول السنة والشهر واليوم والساعة والدقيقة والثانية والأجزاء من الثانية ضمن منطقة زمنية محلية، بغض النظر عن المنطقة الزمنية المحددة التي تُعد محلية)، تمامًا مثل SQL `TIMESTAMP 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.

## نوع Variant

يقرأ ClickHouse الأعمدة المخزّنة بترميز [`VARIANT`](https://github.com/apache/parquet-format/blob/master/VariantEncoding.md) في Parquet، كتلك التي يكتبها Spark 4.0، إلى النوع [`Dynamic`](https://clickhouse.com/docs/ar/reference/data-types/dynamic). ويُعَدّ العمود من نوع variant إذا كان مجموعةً مُعلَّمة بالنوع المنطقي `VARIANT` (الإصدار 1 من المواصفة). غير أن Spark 4.0 يكتب أعمدة variant دون هذا التعليم، ولذلك تُقرأ أيضًا بوصفها variant أي مجموعة لا تحتوي إلا على حقل `metadata` وحقل `value` من النوع `BYTE_ARRAY`. ويمكن تعطيل هذا السلوك عبر الإعداد `input_format_parquet_detect_variant_by_structure`، وعندها تُقرأ هذه المجموعة بوصفها `Tuple` من الحقلين الخامين كما كان الحال سابقًا؛ أما طلب النوع `Dynamic` أو `JSON` للعمود صراحةً فيؤدي إلى قراءته بوصفه variant بصرف النظر عن قيمة الإعداد.

تحتفظ كل قيمة بنوعها الخاص. إذ تُقرأ الأنواع الأولية في variant بوصفها أنواع بيانات ClickHouse المقابلة لها (فمثلًا: `int32` بوصفه `Int32`، و`decimal8` بوصفه `Decimal(18, S)`، و`timestamp` بوصفه `DateTime64(6, 'UTC')`، و`timestamp_ntz` بوصفه `DateTime64(6)`، و`binary` و`string` بوصفهما `String`، و`uuid` بوصفه `UUID`)، وتُقرأ قيمة `null` في variant بوصفها `NULL`، وتُقرأ كائنات variant بوصفها [`JSON`](https://clickhouse.com/docs/ar/reference/data-types/newjson) مع تسطيح الكائنات المتداخلة إلى مسارات مفصولة بنقاط (ويُعامَل الحقل ذو القيمة `null` على أنه غير موجود)، وتُقرأ مصفوفات variant التي تكون جميع عناصرها كائنات بوصفها `Array(JSON)`، في حين تُقرأ مصفوفات variant الأخرى بوصفها `Array(Dynamic)`. ويكون النوع في المستوى الأعلى `Dynamic` لا `JSON`، لأن قيمة variant ليست بالضرورة كائنًا.

ويمكن أيضًا قراءة عمود variant بوصفه [`JSON`](https://clickhouse.com/docs/ar/reference/data-types/newjson) بطلب هذا النوع صراحةً، كأن يُحدَّد في بنية الجدول أو في وسيط البنية الخاص بدالة الجدول `file`. وفي هذه الحالة يجب أن تكون كل قيمة كائنًا، وإلا يُطرح استثناء. وتُقرأ قيمة `null` في variant وقيمة `null` للعمود بأكمله بوصفهما كائنًا فارغًا. أما المسارات محددة النوع في نوع `JSON` المطلوب فتُحوَّل إلى أنواعها، بينما تُتخطّى المسارات المدرجة في `SKIP` و`SKIP REGEXP`.

لا تُدعَم أعمدة variant المجزّأة (أي المجموعات التي تحتوي على حقل `typed_value`) حتى الآن: فقراءة مثل هذا العمود تؤدي إلى إطلاق استثناء، مع بقاء إمكانية قراءة بقية أعمدة الملف، كما يتخطى استنتاج المخطط هذا العمود إذا كان الإعداد `input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference` مفعّلًا. كذلك لا تُدعَم كتابة أعمدة `Dynamic` أو `JSON` إلى Parquet بوصفها `VARIANT`.

## مراجع الملفات

تمثّل المجموعة المُعلَّمة بالنوع المنطقي [`FILE`](https://github.com/apache/parquet-format/blob/master/LogicalTypes.md#file) في Parquet مرجعًا إلى نطاق من البايتات، مخزَّنًا بشكل مضمّن أو في ملف خارجي. وتُقرأ بوصفها `Tuple` مسمّاة تضم الحقول الموجودة في الملف، وكلٌّ منها من النوع `Nullable`: الحقول `uri` و`content_type` و`checksum` من النوع `Nullable(String)`، والحقلان `offset` و`size` من النوع `Nullable(Int64)`، والحقل `inline` من النوع `Nullable(String)` ويحتوي على بايتات خام. أما مرجع الملف ذو القيمة `null` فيُقرأ بوصفه Tuple جميع عناصرها `NULL`. وكما هو الحال مع أي `Tuple`، يمكن قراءة مجموعة جزئية من الحقول بطلب `Tuple` تضم عددًا أقل من العناصر، أو قراءة حقول منفردة بوصفها أعمدة فرعية، مثل `file.uri`. ويجري التحقق من صحة مخطط المجموعة، إذ يجب ألا يحتوي إلا على هذه الحقول، وأن تكون جميعها `OPTIONAL` وبالأنواع المحددة في المواصفة، وإلا يُطرح استثناء. في المقابل، لا يجري التحقق من صحة القيم، فالقيمة التي لا تشكّل مرجعًا صالحًا (مثل `offset` دون `uri`) تُعاد كما هي مخزَّنة. ولا يحلّ ClickHouse هذه المراجع، أي أنه لا يقرأ الملفات الخارجية.

عند الكتابة، تُكتب `Tuple` كهذه (أي التي تكون أسماء عناصرها مجموعة جزئية غير فارغة من حقول `FILE`، ويكون فيها `offset` و`size` عددين صحيحين، وبقية العناصر من النوع `String` أو `FixedString`) بوصفها مجموعة مُعلَّمة بـ `FILE` إذا كان الإعداد [`output_format_parquet_write_file_logical_type`](https://clickhouse.com/docs/ar/reference/settings/formats/output-format#output_format_parquet_write_file_logical_type) مفعّلًا، وإلا فإنها تُكتب بوصفها مجموعة عادية.

## أنواع البيانات الهندسية (GeoParquet)

يدعم ClickHouse قراءة أعمدة البيانات الهندسية وكتابتها وفقًا لمواصفة [GeoParquet](https://geoparquet.org/) و[الأنواع المنطقية `GEOMETRY` و`GEOGRAPHY`](https://github.com/apache/parquet-format/blob/master/Geospatial.md) في Parquet. وتُخزَّن أعمدة البيانات الهندسية كحمولات `BYTE_ARRAY` مُرمَّزة بتنسيق [WKB](https://libgeos.org/specifications/wkb/) (أو WKT عند القراءة بالنسبة إلى GeoParquet). يستخدم GeoParquet مفتاح JSON باسم `geo` ضمن بيانات Parquet الوصفية على مستوى الملف يوضّح ترميز كل عمود هندسي ونوعه الهندسي ونظام CRS الخاص به، في حين تُوصِّف الأنواع المنطقية العمود نفسه مباشرةً، وتحتوي البيانات الوصفية لمقطع العمود على `GeospatialStatistics` (مستطيل الإحاطة وقائمة أنواع الأشكال الهندسية) بدلًا من إحصاءات القيم الدنيا والقصوى. ويمكن أن يجمع الملف الواحد بين الأسلوبين.

### سلوك القراءة

عند القراءة، تُحوَّل أعمدة البيانات الهندسية إلى [الأنواع الجغرافية](https://clickhouse.com/docs/ar/reference/data-types/geo.md) المناظرة لها في ClickHouse:

* يُقرأ العمود المُعرَّف كـ `Point` أو `MultiPoint` أو `LineString` أو `Polygon` أو `MultiLineString` أو `MultiPolygon` إلى نوع ClickHouse الجغرافي المطابق.
* يُقرأ العمود الذي يحتوي على أنواع هندسية متعددة أو غير معروفة إلى النوع [`Geometry`](https://clickhouse.com/docs/ar/reference/data-types/geo#geometry)، وهو `Variant` يضم جميع الأنواع الجغرافية المدعومة.
* بالنسبة إلى العمود ذي النوع المنطقي `GEOMETRY` أو `GEOGRAPHY`، يُؤخذ نوع الشكل الهندسي من البيانات الوصفية لـ GeoParquet إن كانت موجودة في الملف. وإلا، فإذا كانت `GeospatialStatistics` لجميع مقاطع العمود تُدرج نوع شكل هندسي ثنائي الأبعاد واحدًا ومتطابقًا، يُقرأ العمود إلى النوع الجغرافي المطابق، وإلا فيُقرأ إلى `Geometry`. وإذا طُلب نوع جغرافي صراحةً، يُفَك ترميز القيم مباشرةً إلى ذلك النوع.
* لا يتضمن ClickHouse نوعًا منفصلًا للبيانات الجغرافية الكروية، لذا تُقرأ أعمدة `GEOGRAPHY` إلى الأنواع الجغرافية نفسها التي تُقرأ إليها أعمدة `GEOMETRY` (حيث تمثل الإحداثيات خط الطول وخط العرض)، ولا تُمثَّل خوارزمية استيفاء الحواف (المَعلمة `algorithm`). كما لا يُمثَّل نظام الإحداثيات المرجعي (المَعلمة `crs`، وقيمتها الافتراضية `OGC:CRS84`). والأشكال الهندسية ذات الإحداثيات Z أو M غير مدعومة.
* ترتيب الفرز للنوعين المنطقيين `GEOMETRY` و`GEOGRAPHY` غير محدد، لذا تُتجاهَل إحصاءات القيم الدنيا/القصوى وفهرس العمود لمثل هذه الأعمدة. ومع تفعيل [`input_format_parquet_spatial_filter_push_down`](https://clickhouse.com/docs/ar/reference/settings/formats/input-format#input_format_parquet_spatial_filter_push_down)، يُستخدم مستطيل الإحاطة من `GeospatialStatistics` لتخطي مجموعات الصفوف.
* إذا كان نوع العمود المطلوب هو `String`، فتُتجاهَل البيانات الوصفية الخاصة بـ GeoParquet والنوع المنطقي وتُعاد حمولة الشكل الهندسي الخام المرمَّزة كما هي — سواء كانت بايتات WKB أو WKT، بحسب الترميز الذي يعلنه عمود GeoParquet. وينطبق ذلك أيضًا إذا كان الإعداد [`input_format_parquet_allow_geoparquet_parser`](https://clickhouse.com/docs/ar/reference/settings/formats/input-format#input_format_parquet_allow_geoparquet_parser) مضبوطًا على `0` ولم يُطلب أي نوع جغرافي صراحةً.

### سلوك الكتابة

عند الكتابة، تُرمَّز الأعمدة ذات المستوى الأعلى من النوع `Point` أو `MultiPoint` أو `LineString` أو `Polygon` أو `MultiLineString` أو `MultiPolygon` على هيئة `BYTE_ARRAY` ‏(WKB)، وتُضاف بيانات `geo` الوصفية المناسبة بتنسيق JSON إلى تذييل ملف Parquet. كما يُرمَّز [`Geometry`](https://clickhouse.com/docs/ar/reference/data-types/geo#geometry) ذو المستوى الأعلى من النوع `Variant` أيضًا كحمولة `BYTE_ARRAY` بتنسيق WKB (إذ تُحوَّل قيمه الفرعية إلى WKB وتُخزَّن في عمود `Nullable(String)`)، ولكن افتراضيًا لا تُصدَر له أي بيانات وصفية `geo`، لذلك يُقرأ مجددًا على أنه `String`. وتُكتب هذه الأعمدة افتراضيًا على هيئة `BYTE_ARRAY` مع إحصاءات القيم الدنيا والقصوى. وعند تفعيل الإعداد [`output_format_parquet_geometry_logical_type`](https://clickhouse.com/docs/ar/reference/settings/formats/output-format#output_format_parquet_geometry_logical_type)، تُوسَم جميع هذه الأعمدة بالنوع المنطقي `GEOMETRY` مع نظام الإحداثيات المرجعي الافتراضي (`OGC:CRS84`)، وتحتوي البيانات الوصفية لمقاطع أعمدتها على `GeospatialStatistics` (مستطيل الإحاطة وأنواع الأشكال الهندسية) من دون إحصاءات القيم الدنيا والقصوى ومن دون فهرس للأعمدة، كما تقتضي المواصفة، ويُوصَف عمود `Geometry` في بيانات `geo` الوصفية بقائمة فارغة من أنواع الأشكال الهندسية، لذلك يُقرأ مجددًا على أنه `Geometry`. ويكون هذا الإعداد معطّلًا افتراضيًا لأن القارئات التي لا تتعرّف على هذا النوع المنطقي (مثل Arrow C++ و`pyarrow` قبل الإصدار 20) تعجز عن فتح الملف بأكمله. أما الأنواع الأخرى المرتبطة بالبيانات الجغرافية، مثل [`Ring`](https://clickhouse.com/docs/ar/reference/data-types/geo#ring)، فتُكتب باستخدام تمثيلها الأصلي الداخلي من دون أي بيانات وصفية لـ GeoParquet. ويمكن تعطيل هذا السلوك بالكامل عبر ضبط [`output_format_parquet_geometadata`](https://clickhouse.com/docs/ar/reference/settings/formats/output-format#output_format_parquet_geometadata) على `0`، وفي هذه الحالة حتى أنواع البيانات الجغرافية المدعومة تُكتب باستخدام تمثيلها الأصلي الداخلي (`Point` كـ `Tuple(Float64, Float64)`، و`LineString` كـ `Array(Point)`، و`Polygon` كـ `Array(Array(Point))`، وهكذا)، ولا تُصدَر أي بيانات وصفية لـ GeoParquet.

يجب أن تظهر أعمدة البيانات الهندسية في جذر المخطط أو تكون متداخلة داخل `Tuple` ‏(`struct`)؛ أما تضمينها داخل `Array` أو `Map` فغير مدعوم. كذلك، لا يدعم النوع `Nullable` الأعمدة الجغرافية.

## مثال للاستخدام

### إدراج البيانات

باستخدام ملف Parquet باسم `football.parquet` ويحتوي على البيانات التالية:

```text theme={null}
    ┌───────date─┬─season─┬─home_team─────────────┬─away_team───────────┬─home_team_goals─┬─away_team_goals─┐
 1. │ 2022-04-30 │   2021 │ Sutton United         │ Bradford City       │               1 │               4 │
 2. │ 2022-04-30 │   2021 │ Swindon Town          │ Barrow              │               2 │               1 │
 3. │ 2022-04-30 │   2021 │ Tranmere Rovers       │ Oldham Athletic     │               2 │               0 │
 4. │ 2022-05-02 │   2021 │ Port Vale             │ Newport County      │               1 │               2 │
 5. │ 2022-05-02 │   2021 │ Salford City          │ Mansfield Town      │               2 │               2 │
 6. │ 2022-05-07 │   2021 │ Barrow                │ Northampton Town    │               1 │               3 │
 7. │ 2022-05-07 │   2021 │ Bradford City         │ Carlisle United     │               2 │               0 │
 8. │ 2022-05-07 │   2021 │ Bristol Rovers        │ Scunthorpe United   │               7 │               0 │
 9. │ 2022-05-07 │   2021 │ Exeter City           │ Port Vale           │               0 │               1 │
10. │ 2022-05-07 │   2021 │ Harrogate Town A.F.C. │ Sutton United       │               0 │               2 │
11. │ 2022-05-07 │   2021 │ Hartlepool United     │ Colchester United   │               0 │               2 │
12. │ 2022-05-07 │   2021 │ Leyton Orient         │ Tranmere Rovers     │               0 │               1 │
13. │ 2022-05-07 │   2021 │ Mansfield Town        │ Forest Green Rovers │               2 │               2 │
14. │ 2022-05-07 │   2021 │ Newport County        │ Rochdale            │               0 │               2 │
15. │ 2022-05-07 │   2021 │ Oldham Athletic       │ Crawley Town        │               3 │               3 │
16. │ 2022-05-07 │   2021 │ Stevenage Borough     │ Salford City        │               4 │               2 │
17. │ 2022-05-07 │   2021 │ Walsall               │ Swindon Town        │               0 │               3 │
    └────────────┴────────┴───────────────────────┴─────────────────────┴─────────────────┴─────────────────┘
```

أدرِج البيانات:

```sql theme={null}
INSERT INTO football FROM INFILE 'football.parquet' FORMAT Parquet;
```

### قراءة البيانات

يمكنك قراءة البيانات باستخدام تنسيق `Parquet`:

```sql theme={null}
SELECT *
FROM football
INTO OUTFILE 'football.parquet'
FORMAT Parquet
```

> [!TIP]
>
> Parquet هو تنسيق ثنائي لا يظهر في الطرفية بصيغة يمكن للبشر قراءتها. استخدم `INTO OUTFILE` لإخراج ملفات Parquet.

لتبادل البيانات مع Hadoop، يمكنك استخدام [`محرك الجدول HDFS`](https://clickhouse.com/docs/ar/reference/engines/table-engines/integrations/hdfs).

## إعدادات الصيغة

| الإعداد | الوصف | الافتراضي |
| - | - | - |
| `input_format_parquet_case_insensitive_column_matching` | تجاهل حالة الأحرف عند مطابقة أعمدة Parquet مع أعمدة CH. | `0` |
| `input_format_parquet_preserve_order` | تجنّب إعادة ترتيب الصفوف عند القراءة من ملفات Parquet. وعادةً ما يؤدي ذلك إلى إبطاء العملية كثيرًا. | `0` |
| `input_format_parquet_filter_push_down` | عند القراءة من ملفات Parquet، تخطَّ مجموعات الصفوف بالكامل استنادًا إلى تعبيرات WHERE/PREWHERE وإحصاءات الحد الأدنى/الحد الأقصى في البيانات الوصفية لـ Parquet. | `1` |
| `input_format_parquet_bloom_filter_push_down` | عند قراءة ملفات Parquet، تُتخطّى مجموعات الصفوف كاملةً استنادًا إلى تعبيرات WHERE ومرشح bloom filter في بيانات Parquet الوصفية. | `0` |
| `input_format_parquet_dictionary_filter_push_down` | عند قراءة ملفات Parquet (باستخدام القارئ v3)، تُتخطّى مجموعات الصفوف كاملةً استنادًا إلى تعبيرات WHERE/PREWHERE ومحتويات صفحة القاموس، في شروط المساواة و`IN`، عندما تكون جميع صفحات البيانات لجزء العمود مُرمَّزة باستخدام القاموس. تمثل القيمة الحد الأقصى لحجم صفحة القاموس (بالبايت) الذي يُطبَّق عليه هذا التحسين؛ اضبطها على `0` لتعطيله. له أولوية على مرشح bloom filter عند توفر كليهما. | `1048576` |
| `input_format_parquet_allow_missing_columns` | السماح بوجود أعمدة مفقودة عند قراءة تنسيقات إدخال Parquet | `1` |
| `input_format_parquet_local_file_min_bytes_for_seek` | الحد الأدنى من البايتات المطلوب للقراءة المحلية (للملف) لتنفيذ seek بدلًا من القراءة مع التجاهل في تنسيق إدخال Parquet | `8192` |
| `input_format_parquet_enable_row_group_prefetch` | تمكين الجلب المسبق لمجموعات الصفوف أثناء تحليل Parquet. حاليًا، لا يدعم الجلب المسبق إلا التحليل أحادي الخيط. | `1` |
| `input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference` | تخطي الأعمدة ذات الأنواع غير المدعومة أثناء استنتاج المخطط لصيغة Parquet | `0` |
| `input_format_parquet_max_block_size` | الحد الأقصى لحجم الكتلة لقارئ Parquet. | `65409` |
| `input_format_parquet_prefer_block_bytes` | متوسط عدد بايتات الكتلة التي يُخرجها قارئ Parquet | `16744704` |
| `input_format_parquet_enable_json_parsing` | عند قراءة ملفات Parquet، تُحلَّل أعمدة JSON على أنها عمود JSON في ClickHouse. | `1` |
| `input_format_parquet_allow_geoparquet_parser` | عند قراءة ملفات Parquet، يتم التعرّف على البيانات الوصفية `geo` الخاصة بـ GeoParquet والنوعين المنطقيين `GEOMETRY` و`GEOGRAPHY`، وفكّ ترميز الأعمدة الهندسية (WKB أو WKT، وفقًا للترميز المُعلَن للعمود) كأنواع بيانات Geo في ClickHouse. إذا كانت القيمة `0`، فستُعرَض الأعمدة الهندسية بصيغتها الفيزيائية الخام (`String`). | `1` |
| `output_format_parquet_row_group_size` | الحجم المستهدف لمجموعة الصفوف، محسوبًا بالصفوف. | `1000000` |
| `output_format_parquet_row_group_size_bytes` | حجم مجموعة الصفوف المستهدف بالبايت، قبل الضغط. | `536870912` |
| `output_format_parquet_string_as_string` | استخدم نوع String في Parquet بدلًا من Binary لأعمدة String. | `1` |
| `output_format_parquet_fixed_string_as_fixed_byte_array` | استخدم النوع FIXED\_LEN\_BYTE\_ARRAY في Parquet بدلًا من Binary لأعمدة FixedString. | `1` |
| `output_format_parquet_wide_integer_as_decimal` | اكتب `Int128` و`UInt128` و`Int256` و`UInt256` كقيم `DECIMAL` قياسية في Parquet بترتيب big-endian بدلًا من مصفوفات بايتات ثابتة قديمة بترتيب little-endian. | `0` |
| `output_format_parquet_compression_method` | طريقة الضغط لتنسيق إخراج Parquet. ترميزات الضغط المدعومة: snappy وlz4 وbrotli وzstd وgzip وnone (غير مضغوط) | `zstd` |
| `output_format_parquet_parallel_encoding` | نفّذ ترميز Parquet باستخدام عدة سلاسل تنفيذ. | `1` |
| `output_format_parquet_data_page_size` | حجم الصفحة المستهدف بالبايت قبل الضغط. | `1048576` |
| `output_format_parquet_batch_size` | تحقّق من حجم الصفحة كل هذا العدد من الصفوف. يُنصح بتقليله إذا كان متوسط حجم القيم في الأعمدة يتجاوز بضعة كيلوبايتات. | `1024` |
| `output_format_parquet_write_page_index` | إتاحة إمكانية كتابة فهرس الصفحة في ملفات Parquet. | `1` |
| `output_format_parquet_geometadata` | اكتب بيانات GeoParquet الوصفية `geo` في تذييل ملف Parquet، ورمّز أعمدة ClickHouse الجغرافية ذات المستوى الأعلى ([`Point`](https://clickhouse.com/docs/ar/reference/data-types/geo#point)، [`MultiPoint`](https://clickhouse.com/docs/ar/reference/data-types/geo#multipoint)، [`LineString`](https://clickhouse.com/docs/ar/reference/data-types/geo#linestring)، [`Polygon`](https://clickhouse.com/docs/ar/reference/data-types/geo#polygon)، [`MultiLineString`](https://clickhouse.com/docs/ar/reference/data-types/geo#multilinestring)، [`MultiPolygon`](https://clickhouse.com/docs/ar/reference/data-types/geo#multipolygon)) بتنسيق WKB. إذا كانت القيمة `0`، فستُكتب هذه الأعمدة باستخدام تمثيلها الأصلي الأساسي (مثل `Point` على هيئة `Tuple(Float64, Float64)`) ولن يتم إخراج أي بيانات GeoParquet وصفية. | `1` |
| `output_format_parquet_geometry_logical_type` | علِّم الأعمدة الجغرافية المكانية المكتوبة بتنسيق WKB بالنوع المنطقي `GEOMETRY` في Parquet، واكتب لها `GeospatialStatistics` بدلًا من إحصاءات الحد الأدنى/الحد الأقصى. لا يكون لهذا الإعداد أي تأثير إذا كانت قيمة `output_format_parquet_geometadata` هي `0`. | `0` |
| `output_format_parquet_write_file_logical_type` | اكتب `Tuple` مُسمّى تتطابق أسماء عناصره مع حقول النوع المنطقي `FILE` في Parquet، على هيئة مجموعة مُعلَّمة بالنوع `FILE`؛ راجع [مراجع الملفات](#file-type). | `0` |
| `input_format_parquet_import_nested` | إعداد مهمل، لا يفعل شيئًا. | `0` |
| `input_format_parquet_local_time_as_utc` | true | يحدّد نوع البيانات الذي يستخدمه استنتاج المخطط للطوابع الزمنية في Parquet عندما تكون isAdjustedToUTC=false. إذا كانت القيمة true: ‏DateTime64(..., 'UTC')، وإذا كانت false: ‏DateTime64(...). ولا يُعدّ أيّ من السلوكين صحيحًا تمامًا، لأن ClickHouse لا يوفّر نوع بيانات للوقت المحلي وفق ساعة النظام. وعلى نحوٍ غير بديهي، يُرجَّح أن تكون القيمة 'true' هي الخيار الأقل خطأً، لأن تنسيق الطابع الزمني 'UTC' على هيئة String سينتج تمثيلًا صحيحًا للوقت المحلي. |
