محوّل Parquet إلى CSV

ماذا يفعل هذا المحوّل

Apache Parquet هو التنسيق الذي يكتبه اليوم أي خط بيانات تقريبًا: عمودي، مضغوط، ثنائي، مصمَّم لمحركات التحليل. ممتاز للآلة، عديم الفائدة للعين البشرية. لا يمكنك فتحه في محرر نصوص، ولا إرساله إلى زميل يعيش داخل الجداول، ولا لصقه في تذكرة دعم. أما CSV فهو النقيض: أخرق في التحليل، لكنه مقروء في كل مكان.

هذه الصفحة تصل بين الطرفين بأبسط طريقة ممكنة. تختار ملف .parquet من قرصك، فتفك الصفحة ترميزه، وتخبرك بعدد الصفوف والأعمدة التي وجدتها، وتعرض معاينة، ثم تسلّمك ملف CSV للتنزيل. لا حساب، ولا طابور انتظار، ولا شريط رفع، لأن العملية كلها تجري دون أي خادم.

هذه النقطة الأخيرة هي سبب وجود الأداة. معظم محوّلات Parquet على الإنترنت ليست سوى نموذج يرسل ملفك إلى خادم خلفي. وإذا كان الملف يحوي سجلات عملاء أو رواتب أو معرّفات مرضى أو أي شيء تحكمه سياسة بيانات، فإن ذلك الإرسال هو المشكلة كلها. هنا التحويل شفرة JavaScript تعمل داخل تبويبك، وتقرأ بايتات سلّمها المتصفح للصفحة أصلًا لحظة اختيارك للملف.

الاستخدام في أربع خطوات

1. اختر ملف .parquet من حقل الملفات؛ لا يحدث شيء قبل ذلك.
2. اختر الفاصل. الفاصلة هي الافتراضية، والفاصلة المنقوطة تناسب الجداول المضبوطة على لغات تُستخدم فيها الفاصلة كعلامة عشرية، أما مسافة الجدولة فتنتج ملف TSV يُلصق بنظافة في أغلب برامج الجداول.
3. قرّر إن كان السطر الأول سيحمل أسماء الأعمدة. مربع العناوين مفعّل مسبقًا، وتبديله يعيد بناء الناتج فورًا دون قراءة الملف من جديد.
4. اقرأ المعاينة ثم اضغط تنزيل CSV. تعرض المعاينة أول 200 صف كي تبقى الصفحة سريعة، بينما يحتوي الملف المنزَّل دائمًا على كل صفوف ملف Parquet.

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

كيف يخزّن Parquet جدولًا، ولماذا التحويل ليس بسيطًا

ملف CSV تدفق من الصفوف، أما Parquet فيفعل العكس: يخزّن كل عمود على حدة داخل كتل تسمى row groups، وداخل كل row group يعيش العمود في chunk مؤلَّف من صفحات. وكل صفحة قد تكون مضغوطة، وقد تُرمَّز القيم داخلها بطرق مختلفة عدة.

لذلك تعني قراءته تقشير عدة طبقات:

• تذييل الملف يحوي المخطط وموقع كل chunk، مُسلسلًا ببروتوكول Thrift المضغوط. ينتهي الملف بأربع بايتات للطول ثم العلامة النصية PAR1، وهي العلامة نفسها المكتوبة في بدايته. غياب إحدى العلامتين يعني إما أنه ليس Parquet وإما أنه بُتر أثناء النسخ.
• كل صفحة قد تكون مضغوطة. تفك هذه الأداة الصفحات غير المضغوطة وصفحات Snappy وصفحات Gzip، وهي مجتمعة تغطي الغالبية الساحقة من الملفات التي تكتبها pandas و PyArrow و Polars و DuckDB و Spark.
• القيم داخل الصفحة مُرمَّزة. التخطيط المسطّح والقاموس و run-length وعائلة delta و byte-stream-split كلها مدعومة، في صفحات البيانات v1 وفي التخطيط الأحدث v2 على السواء.
• القيم الفارغة لا تُخزَّن كقيم. يسجّل Parquet مستوى تعريف لكل صف، ويستخدم المحوّل تلك المستويات ليعيد كل قيمة إلى صفها الصحيح ويترك مواضع الفراغ خالية.

لا شيء من هذا يهم حين تنجح العملية، لكنه يهم حين تفشل: لأن فاكّ الترميز يفهم كل طبقة، فإن الملف غير المدعوم ينتج رسالة محددة عن الضغط أو الترميز أو التداخل، بدلًا من ملف CSV مشوَّه بصمت.

مثال محلول: ما القيم التي ستراها

ثلاثة أنواع في Parquet ليس لها مقابل مباشر في CSV، لذا يستحق الأمر توضيح ما يُكتب بالضبط.

عمود تاريخ. يخزّن النوع DATE عدادًا بسيطًا من 32 بت لعدد الأيام منذ 1 يناير 1970. إذا كان الرقم المخزَّن 19723، فإن اليوم رقم 19723 بعد بداية الحقبة هو 1 يناير 2024، وتُكتب الخلية 2024-01-01. لا يُطبَّق أي توقيت زمني، لأن التاريخ لا يحمل وقتًا يمكن إزاحته.

طابع زمني بالميكروثانية. يخزّن عمود TIMESTAMP بدقة الميكروثانية عدادًا من 64 بت للميكروثواني منذ بداية الحقبة. خذ القيمة 1704112215123456، واقسمها على 1,000,000 لتحصل على 1704112215 ثانية كاملة، أي 1 يناير 2024 عند 12:30:15 بتوقيت UTC، ويتبقى 123456 ميكروثانية. تُكتب الخلية 2024-01-01 12:30:15.123456. وتُحذف الأصفار الأخيرة من الكسر، فالطابع الذي يقع على ثانية كاملة يُكتب دون جزء عشري.

عمود عشري. يُخزَّن العمود DECIMAL(12,2) كعدد صحيح مع مقياس. العدد 1230 بمقياس 2 يعني 12.30، ويُكتب حرفيًا 12.30. لهذا السبب لا ينبغي أبدًا تمرير عمود مالي عبر عدد عائم: النص يحفظ القيمة الدقيقة وعدد المنازل العشرية الذي وعد به المخطط.

تُكتب القيم المنطقية true و false، وتتحول القيم الفارغة إلى خانات خالية، أما الأعمدة الثنائية التي ليست نصًا صالحًا بترميز UTF-8 فتُكتب بصيغة base64 كي لا تُفسد البايتات الخام بنية الملف.

أين يثبت المحوّل غير المتصل جدواه

الحالة الأوضح هي السرية: تصدير لسجلات مستخدمين تحتاج إلى إلقاء نظرة عليه قبل أن يقترب من قرص مشترك. لا شيء يغادر الحاسوب، فلا تُلوى أي سياسة.

الحالة الثانية هي الاحتكاك. يرسل زميل عيّنة Parquet، وتريد التحقق من ثلاثة أعمدة، وتثبيت Python مع PyArrow لفحص ملف ستحذفه بعد خمس دقائق ثمن سخيف. أما فتح تبويب فلا.

الحالة الثالثة جهاز لا تملك حق تهيئته: حاسوب عمل مقفل، أو جهاز عميل، أو محطة مختبر لا تُثبَّت عليها الحزم. المتصفح موجود هناك أصلًا.

الحالة الرابعة هي التعليم. رؤية الجدول نفسه أولًا ككتلة ثنائية معتمة ثم كنص صريح تجعل الفرق بين التخزين العمودي والتخزين الصفّي ملموسًا بصورة نادرًا ما يحققها رسم توضيحي.

أخطاء شائعة وكيف تتجنبها

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

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

توقّع التوقيت المحلي. تُكتب الطوابع الزمنية بتوقيت UTC. يخزّن Parquet الطابع عادة كلحظة زمنية، وتحويله إلى المنطقة التي يصادف وجود جهازك فيها كان سيغيّر كل القيم بصمت. أزِح القيم لاحقًا وعن قصد إن احتجت التوقيت المحلي.

إدخال تصدير متداخل. يُرفض الملف الذي يحوي أعمدة struct أو list أو map. سطّحه أولًا باستخدام pandas.json_normalize أو unnest في Polars أو استعلام DuckDB يختار الحقول الطرفية، ثم اكتب ملف Parquet مسطّحًا وحوّله هنا.

الحدود: متى لا تكون هذه الأداة مناسبة

تقرأ الأداة الملف كاملًا في الذاكرة، لذا فإن عمليات التصدير الضخمة — من بضع مئات الميغابايت فصاعدًا — تُعالَج بشكل أفضل عبر DuckDB أو نص برمجي صغير يمرّ على row groups تدفقيًا. ويُرفض ضغط Zstd و Brotli و LZ4 بدل فك ترميزه نصف فكّ؛ أعد كتابة تلك الملفات بضغط Snappy أو Gzip. أما ملفات Parquet المشفّرة فغير مدعومة عن قصد. والمخططات المتداخلة تبقى خارج النطاق، لأن طيّ عمود قائمة داخل خانة CSV قرار يخص بياناتك، ولا يصح لمحوّل عام أن يتخذه بصمت.

الخصوصية

لا تتضمن الصفحة أي شفرة رفع، ولا تجمع أي تحليلات عن ملفك، ولا تُجري أي اتصال شبكي أثناء التحويل. يُقرأ الملف عبر واجهة الملفات الخاصة بالمتصفح ويُفكّ ترميزه داخل التبويب. وإن أردت دليلًا لا وعدًا: حمّل الصفحة، ثم اقطع الاتصال بالإنترنت، ثم حوّل ملفًا. ستعمل الأداة كما هي تمامًا، لأنه لم يكن هناك يومًا شيء في الطرف الآخر من السلك.