إتقان ملفات JSONL: البنية، حالات الاستخدام، والمزايا الرئيسية

يحتوي ملف JSONL على قيمة JSON كاملة واحدة في كل سطر. وتطلق عليه الوثائق الرسمية اسم "تنسيق نص JSON Lines، والمعروف أيضاً باسم JSON المفصول بسطر جديد". هذه القاعدة الفردية هي السبب في أنه يتدفق بشكل جيد، ولماذا ينجو من القراءات الجزئية، ولماذا لا يفتحه برنامج جداول البيانات.

ما هو ملف JSONL؟

إن JSON Lines هو تنسيق نصي للسجلات. وتصفه المواصفات بأنه "تنسيق مناسب لتخزين البيانات المهيكلة التي يمكن معالجتها سجلاً واحداً في كل مرة".

توضح الوثائق صراحةً أين يتناسب هذا التنسيق. فهو "يعمل بشكل جيد مع أدوات معالجة النصوص بأسلوب unix ومسارات الأوامر (shell pipelines)"، وتضيف الصفحة أنه "تنسيق رائع لملفات السجلات". كما يوصف أيضاً بأنه "تنسيق مرن لتمرير الرسائل بين العمليات المتعاونة".

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

هناك مواصفة ثانية وثيقة الصلة بها. مواصفات NDJSON مباشرة في هذا الشأن: "لا يوجد حالياً معيار لنقل عينات من نصوص JSON داخل بروتوكول تدفق". وحالة الاستخدام المذكورة لها هي "تقديم عينات متعددة من نصوص JSON عبر بروتوكولات التدفق مثل TCP أو UNIX Pipes".

كيف يتم هيكلة ملف JSONL

المتطلبات الثلاثة

تدرج وثائق JSON Lines ثلاثة متطلبات بالضبط. الأول هو ترميز UTF-8. وهو يحمل تحذيراً مستعاراً من JSON نفسه: "مثل معيار JSON، يجب ألا يتم تضمين علامة ترتيب البايت (U+FEFF)".

والثاني هو أن كل سطر عبارة عن قيمة JSON صالحة. وتشير الصفحة إلى أن "القيم الأكثر شيوعاً ستكون كائنات أو مصفوفات، ولكن يُسمح بأي قيمة JSON". ثم تذكر الحالة الاستثنائية التي يقع فيها الناس: "null هي قيمة صالحة ولكن السطر الفارغ ليس كذلك".

والثالث هو أن مُنهي السطر هو \n. لا تزال نهايات الأسطر في Windows تعمل. والسبب المذكور ميكانيكي: "هذا يعني أن \r\n مدعوم أيضاً لأن المسافات البيضاء المحيطة يتم تجاهلها ضمنياً عند تحليل قيم JSON".

ما يجب ألا يظهر داخل السطر

هذا هو القيد الذي يجعل التنسيق يعمل. تنص مواصفات NDJSON على ذلك كشرط: "يجب ألا تحتوي نصوص JSON على أسطر جديدة أو محارف إرجاع العربة (carriage returns)".

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

السطر الأخير، والأسطر الفارغة

هناك تفصيلان يختلفان بين المواصفتين، وكلاهما يهم عندما يتم رفض الملف.

لنأخذ السطر الجديد الختامي. تقول مواصفات JSON Lines إن "تضمين مُنهي السطر بعد آخر قيمة JSON في الملف أمر موصى به بشدة ولكنه ليس مطلوباً".

أما بالنسبة للأسطر الفارغة، فتختلف المواصفتان. مواصفات JSON Lines صارمة: السطر الفارغ ليس قيمة صالحة. بينما مواصفات NDJSON متساهلة، حيث تسمح بأن "المحلل قد يتجاهل الأسطر الفارغة بصمت"، مع اشتراط أن "هذا السلوك يجب أن يكون موثقاً".

الامتدادات وأنواع الوسائط

ينقسم التسمية أيضاً. تقول مواصفات JSON Lines إن الملفات "يمكن حفظها بامتداد الملف .jsonl". وبالنسبة لنوع الوسائط، تقول إن "نوع MIME قد يكون application/jsonl، ولكن هذا لم يتم توحيده بعد". بينما تقول مواصفات NDJSON إن نوع الوسائط "يجب أن يكون application/x-ndjson" والامتداد "يجب أن يكون .ndjson".

بالنسبة للضغط، توصي مواصفات JSON Lines بضواغط التدفق: "يوصى باستخدام gzip أو bzip2 لتوفير المساحة، مما ينتج عنه ملفات .jsonl.gz أو .jsonl.bz2".

هناك اتفاقية صغيرة تستحق المعرفة عندما تقرأ رسالة خطأ. تطلق محررات النصوص على السطر الأول اسم "السطر 1". وتوسع الوثائق ذلك: "يجب أيضاً تسمية القيمة الأولى في ملف JSON Lines بـ 'القيمة 1'".

ما الذي يُستخدم فيه JSONL

ستصادف عادةً ملف .jsonl في واحدة من أربع حالات.

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

تحميلات مستودعات البيانات. تعد وثائق BigQuery من Google مثالاً جيداً على المكانة الرسمية لهذا التنسيق. فهي تدعم تحميل "بيانات JSON المفصولة بسطر جديد (ndJSON) من Cloud Storage"، وتدرج أداة اختيار تنسيق الملف الخيار كـ "JSONL (JSON المفصول بسطر جديد)".

صادرات واجهة برمجة التطبيقات (API) للسجلات المتداخلة. البيانات التي لا يمكن تسويتها بشكل نظيف في أعمدة تحتفظ بتداخلها في كل سطر. وتعد سطور الطلبات ذات الأعداد المتغيرة من العناصر هي الحالة الكلاسيكية.

مجموعات بيانات التعلم الآلي. عادةً ما يتم توزيع مجموعات التدريب والتقييم بهذه الطريقة، لأن حلقة التدريب تقرأ السجلات واحداً تلو الآخر.

القاسم المشترك هو التدفق. يصبح الخيار البديهي عندما يتم إنتاج الملف بشكل تدريجي أو استهلاكه بشكل تدريجي.

JSONL مقابل JSON مقابل CSV

	JSONL	JSON	CSV
وحدة الملف	قيمة واحدة لكل سطر	قيمة واحدة للملف بأكمله	صف واحد لكل سطر
بيانات متداخلة	نعم، لكل سجل	نعم	ليس بشكل أصلي
إضافة سجل	إضافة سطر	إعادة كتابة الحاوية	إضافة صف
القراءة الجزئية مفيدة	نعم	نادراً	نعم
يفتح في برنامج جداول البيانات	لا	لا	عادةً
قد تختلف السجلات في الشكل	نعم	نعم	لا، الأعمدة ثابتة
مقروء بشرياً في المحرر	نعم، سطر طويل واحد لكل منها	نعم، عند وضع مسافة بادئة	نعم

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

بالنسبة للبديل الثنائي الموجه نحو الأعمدة، يغطي شرح Parquet نفس المجال من جانب التخزين. بالنسبة لأبسط حالة جدولية، يغطي تحليل TSV النصوص المفصولة بعلامات جدولة.

المزايا الرئيسية

الكتابة بالإضافة فقط. السجل الجديد هو سطر جديد. لا يجب تغيير أي شيء سابق في الملف.

قراءات التدفق. يمكن للمستهلك معالجة السجل الأول قبل كتابة السجل رقم مليوني.

التسامح مع الأخطاء. يظل الملف المبتور قابلاً للقراءة حتى آخر سطر كامل. بينما تكون مصفوفة JSON المبتورة غير قابلة للقراءة تماماً في العادة.

بقاء التداخل. يظل الهيكل الذي كان سيتعين على ملف CSV تسويته سليماً داخل كل سجل.

صديق للـ Shell. تنسب الوثائق الفضل لمعالجة النصوص بأسلوب unix ومسارات الأوامر (shell pipelines)، لأن الملف الموجه نحو الأسطر يعمل مع الأدوات الموجهة نحو الأسطر.

دعم مستودعات البيانات. تنص وثائق BigQuery على القاعدة التي تفرضها: "يجب أن يكون كل كائن JSON في سطر منفصل في الملف".

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

يحل هذا التنسيق مشكلة النقل والإضافة. لكنه لا يحل أياً من الأسئلة التي لديك حول المحتويات.

الضغط هو مقايضة حقيقية وليس مكسباً مجانياً. وثائق BigQuery صريحة بشأن التكلفة: "إذا كنت تستخدم ضغط gzip، فلن يتمكن BigQuery من قراءة البيانات بالتوازي". وتضيف أن "تحميل بيانات JSON المضغوطة في BigQuery أبطأ من تحميل البيانات غير المضغوطة". وتوصي صفحة التنسيق نفسها بـ gzip لتوفير المساحة. كلا الأمرين صحيحان، وهما يسيران في اتجاهين متعاكسين.

كما أنه مطول أيضاً. يكرر كل سطر اسم كل مفتاح، لذا فإن مجموعة السجلات العريضة تكون أكبر بكثير من نفس البيانات في تنسيق عمودي.

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

كيفية العمل مع ملف JSONL إذا لم تكن مهندساً

هذه هي الفجوة العملية. تتوقع أدوات الأعمال صفوفاً وأعمدة، ولن يفتح ملف .jsonl بالطريقة التي يفتح بها ملف CSV.

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

من هناك، يكون العمل عبارة عن تحليل عادي. تدرج صفحة أسعار Powerdrill Bloom عمليات التحميل لملفات Excel و CSV و PDF والمستندات، لذا فإن المستخرج المسطح يدخل مباشرة. يتم طرح الأسئلة بلغة طبيعية بدلاً من كتابتها كاستعلامات. يغطي CSV AI assistant هذا المسار، وتغطي موصلات البيانات الحالات التي يكون فيها سحب البيانات من مصدرها أفضل من تصديرها.

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

الخاتمة

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

ما لا يضمنه هو جدول. في اللحظة التي يصل فيها الملف إلى شخص يحتاج إلى إجابات بدلاً من مسار معالجة، فإن الخطوة التالية المفيدة هي مستخرج مسطح وسؤال.

إذا كان هذا هو وضعك الحالي، فجرب Powerdrill Bloom مع الملف المحول وابدأ بـ تحويله إلى مخطط بياني.

الأسئلة الشائعة

ما الذي يُستخدم فيه ملف JSONL؟

يُستخدم لتدفقات السجلات: ملفات السجلات، وصادرات الأحداث، وتحميلات مستودعات البيانات، ومجموعات بيانات التعلم الآلي. تذكر وثائق التنسيق ملفات السجلات ومسارات الأوامر (shell pipelines) على وجه التحديد. العامل المشترك هو أن السجلات تُكتب أو تُقرأ واحداً تلو الآخر.

ما الفرق بين JSONL و NDJSON؟

كلاهما يصفان الفكرة نفسها بأوراق رسمية مختلفة. يستخدم JSON Lines الامتداد .jsonl ويشير إلى أن application/jsonl لم يتم توحيده بعد. بينما يحدد NDJSON الامتداد .ndjson و application/x-ndjson، ويسمح للمحللات بتجاهل الأسطر الفارغة.

هل يمكنني فتح ملف JSONL في Excel؟

ليس عن طريق النقر المزدوج عليه، لأن كل سطر عبارة عن قيمة JSON وليس صفاً من الخلايا. النهج المعتاد هو تسوية الحقول التي تحتاجها إلى CSV أو Excel أولاً، أو استخدام أداة تقرأ التنسيق مباشرة.

لماذا لا يمكن للسجل أن يمتد عبر أسطر متعددة في JSONL؟

لأن محرف السطر الجديد هو فاصل السجلات. تنص مواصفات NDJSON على أن "يجب ألا تحتوي نصوص JSON على أسطر جديدة أو محارف إرجاع العربة (carriage returns)". وبالتالي، يجب تقليص تنسيق JSON المنسق (pretty-printed) إلى سطر واحد لكل سجل.

هل يُسمح بالسطر الفارغ في ملف JSONL؟

تختلف المواصفتين. تنص JSON Lines على أن "null هي قيمة صالحة ولكن السطر الفارغ ليس كذلك". بينما يسمح NDJSON للمحلل بتجاهل الأسطر الفارغة بصمت، بشرط أن يكون هذا السلوك موثقاً.