JSON Toolkit

jq والملفات JSON الكبيرة: لماذا يفجّر ‎-s الذاكرة وكيف تعالج بالبث

الخلاصة: تجميع مئات ميغابايتات من سجلات JSON بواسطة jq -s ينتهي بنفاد الذاكرة، بينما ينتج reduce inputs الإحصاءة نفسها ببضعة ميغابايتات من الرام. قياسًا على عينة من ٢٢٠ ميغابايت ومليوني سطر: يبلغ slurp ذروته عند ٢,٠٨ غيغابايت مقابل ٣,٥ ميغابايت للمُجمع البثقي. يشرح هذا المقال آلية استهلاك الذاكرة، والمعالجة سطرًا بسطر للـ JSONL، وأحداث المسارات في --stream، وثلاثة فخاخ حقيقية، بينها المخرجات الفارغة الصامتة لـ ‎-n --stream.

متقدمقراءة نحو 6 دقيقةنُشر في 2026-11-12حُدِّث في 2026-11-12
مقارنة الذاكرة بين jq البثقي و‎-s على ملفات JSON الكبيرة

jq يفك الترميز بسرعة، لكن كل موتة تقريبًا أمام ملف بحجم مئات الميغابايتات تعود إلى الراية نفسها: ‎-s‎ يحمل المدخل كله في مصفوفة عملاقة واحدة، وتصل ذروة RSS بسهولة إلى أضعاف حجم الملف.

ملف واحد، استعلامان: ذاكرة أقل بـ ٥٨٠ مرة

نبدأ بقياس. العينة سجل JSONL بحجم ٢٢٠ ميغابايت و٢٬٠٠٠٬٠٠٠ سطر (سجل طلب واحد في كل سطر: timestamp، level، path، status، duration_ms، uid). البيئة: jq 1.7 على Linux x86_64، وسُجلت ذروة RSS عبر ‎/usr/bin/time -v‎:

الاستعلام المهمة المدة ذروة RSS
jq -s 'group_by(.level) | ...' العد حسب level ١٠٫١ث ٢,٠٨ غيغابايت (~٩٫٥ ضعف حجم الملف)
jq -n 'reduce inputs ...' العد نفسه ٤٫٧ث ٣,٥ ميغابايت
jq -r 'select(...) | .path' ترشيح سطرًا بسطر ٢٫٦ث ٣,٦ ميغابايت

الإحصاءة نفسها، ذاكرة أقل بـ ٥٨٠ مرة، وأسرع أيضًا. هذه ليست علّة في jq — ‎-s‎ يعني بحكم التعريف «اقرأ الكل في مصفوفة»؛ معظم الناس ببساطة لا يحسبون هذه الكلفة الافتراضية. المصادر الخارجية توافق: شهادة تجربة ٢,٣ غيغابايت من JSONL لدى مجتمع Huawei Cloud تحكي القصة نفسها تمامًا — نفاد ذاكرة مع slurp، ثم المُجمع البثقي ينتهي في ٤٧ ثانية عند RSS يفوق ٣٠ ميغابايت بقليل. وقد قاست Dratini.tech على مدخل بحجم ٢,٥ غيغابايت ‎jq -s‎ يقتله OOM killer حتى على آلة بـ ١٦ غيغابايت فأكثر، بينما أكملت الخط الشائع في ٤٨٫٢ ثانية عند ٨٤ ميغابايت.

الخلاصة أولًا: إذا تجاوز الملف نصف الذاكرة المتاحة، فـ ‎-s‎ ليس مرشحًا أصلًا. قِس ثلاثة أشياء قبل كتابة أي شيء: ‎ls -lh‎ للحجم، ‎free -m‎ لهامش الذاكرة، ‎wc -l‎ لعدد الأسطر.

إلى أين تذهب الذاكرة فعلًا

‎jq -s‎ (slurp) موثّق كـ «قراءة كل المدخلات في مصفوفة». الكلفة الفعلية تفوق النص بكثير: بعد فك الترميز يحتفظ jq بشجرة من بنى C، وكل كائن ومصفوفة وسلسلة ورقم يحمل عقدته الخاصة مع بياناته الوصفية. صارت ٢٢٠ ميغابايت من نصنا أكثر قليلًا من ٢ غيغابايت من البنى — تضخم بنحو ٩٫٥ ضعفًا. ويزيد ‎group_by‎ على ذلك بالفرز والتجميع في الذاكرة، بما يضخّم الذروة.

مستند JSON كبير واحد يسلك السلوك ذاته. بوضع السجل نفسه في مصفوفة جذر بحجم ٣٠٠ ميغابايت ثم الاستخراج بمرشّح عادي:

الاستعلام المدة ذروة RSS
jq '.[] | select(.level=="ERROR") | .uid' (المستند كله) ٤٫٧ث ١,٨٥ غيغابايت
jq --stream 'select(...)' (أحداث المسارات) ١٣٫٤ث ٣,٤ ميغابايت

فك الترميز الكامل يبلغ ذروته عند نحو ١,٨ غيغابايت — يبني jq الشجرة كاملة قبل أن يُنفَّذ المرشّح. يبدّل ‎--stream‎ نحو ثلاثة أضعاف وقت التنفيذ بذاكرة أصغر ٥٤٠ مرة. النموذج المفصل لهذا التضخم مطوّر في من أين تأتي الذاكرة.

سجلات JSONL: القراءة سطرًا بسطر بثّ أصلًا

إذا كان «ملفك الكبير» في حقيقة الأمر JSONL — كائن واحد في كل سطر — فالسلوك الافتراضي لـ jq بثّ فعلًا: يُفك ويُبثّ كل سطر باستقلال، و‎-s‎ ليس عبثًا فحسب بل ضار:

# العد حسب level: سطرًا بسطر، والتجميع في الصدفة
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# ترشيح + استخراج: select أولًا، والأسطر غير المطابقة تُطرح فورًا
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

عادتان ينبغي إلزامهما:

  • select في أول الخطّ منذ البداية. يرشّح jq بمجرد فك سطر؛ الترشيح بعد التحويلات يهدر الحساب.
  • -r للسلاسل الخام. بدونه يكون الناتج سلسلة JSON بين علامتي تنصيص، وسيعدّ ‎uniq -c‎ ‎"ERROR"‎ و‎ERROR‎ قيمتين مختلفتين.

للأسطر التالفة استخدم ‎fromjson?‎: ‎jq -r 'fromjson? | .level'‎ يتجاوز الأسطر غير القابلة للفك بصمت، والقطعة المبتورة لا تقتل الخطّ كله. الشكل نفسه مغطى في الكتيّب العملي لـ JSONL؛ وهذا المقال عن الأوامر التي تعالجه.

التجميع الشامل: reduce inputs يبقي الحالة محدودة

الترشيح سطرًا بسطر شأن الصدفة، لكن حين يجب أن يتم التجميع داخل jq نفسه — عدّادات حسب level، متوسط مدة حسب path — فالمفتاح ‎reduce‎ مع ‎inputs‎، لحالة محدودة:

# العد حسب level: الذاكرة تتبع حجم النتيجة لا حجم الملف
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# متوسط المدة حسب path: الحالة زوج ثابت {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

تفصيلان:

  • ‎-n‎ تعني ألا يستهلك jq المدخل الأول كقيمة ابتدائية؛ ‎inputs‎ نفسه يبثّ كل سجل. انسَ ‎-n‎ فيُبتلع السجل الأول كحالة ابتدائية.
  • حالة المُجمع يجب أن تكون ثابتة الشكل — عدّادات ومراكم فقط. بمجرد أن تدفع الأسطر المطابقة في مصفوفة داخل المُجمع تعود الذاكرة تنمو مع حجم البيانات، ولم يعد للبثّ أي قيمة.

من هنا ٣,٥ ميغابايت في الجدول: مرّ غيغابايتان ولم يبقَ إلا جدول تجزئة.

مستند كبير واحد: أحداث مسارات ‎--stream

حين يكون المدخل مستند جذر عملاقًا واحدًا (تصدير بحجم مئات الميغابايتات بلا حدود أسطر)، استخدم ‎--stream‎. بدل القيم الكاملة، يبثّ تتابعًا من أحداث «مسار + قيمة ورقية»:

# الحدث يبدو هكذا: مصفوفة مسار + قيمة عددية
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

الاستخراج من تيار الأحداث يفرض مطابقة الشكل الكامل للمسار — العمق، وأسماء الأعضاء، ومواضع الفهارس — لأن فحص المركّب الأخير وحده سيأخذ أيضًا المفاتيح المتجانسة في الكائنات المتداخلة:

# rows[i].id فقط، متجاهلًا meta.id وأبناء العمومة الأعمق
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

يبقى التجميع ‎reduce inputs‎ ذا شكل ثابت (مع ‎-n --stream‎ يجب استهلاك الأحداث عبر ‎inputs‎ — انظر الفخاخ). ولإعادة البناء — تحويل تيار الأحداث ثانيةً إلى كائنات كاملة — ادمج ‎truncate_stream‎ و‎fromstream‎. ولمحة اختيار الأدوات حسب الحجم في ملف JSON أكبر من اللازم؟.

ثلاثة فخاخ حقيقية

الفخ الأول: ‎-n --stream‎ بلا ‎inputs‎ لا يخرج شيئًا إطلاقًا، بصمت. ثُبت على هذه الآلة: ‎jq -n --stream 'select(...)' file.json‎ ينتهي برمز ٠، بلا مخرجات ولا خطأ — في وضع ‎-n‎ لا يقرأ jq المدخل، ولا يتلقى ‎select‎ للمرشّح أي حدث. الصواب: اسقط ‎-n‎ واستخدم ‎--stream‎ مجردة، أو اقرن ‎-n --stream‎ مع ‎reduce inputs‎. هذه الفئة من الفشل «نجاح لكن فراغ» هي الأصعب تنقيحًا؛ تحقق على عينة صغيرة قبل توصيل خطّ.

الفخ الثاني: ‎--stream‎ يبثّ الأوراق العددية فقط؛ الكائنات والمصفوفات الفارغة لا حدث قيمي لها. ‎{"a":{}}‎ ينتج حدث إغلاق مسار فقط (من جنس ‎length == 1‎)، وسيلتقم مرشّح على ‎length == 2‎ الحاويات الفارغة بصمت — قرر صراحةً إن كانت تعدّ في إحصاءاتك.

الفخ الثالث: نتيجة جزئية بعد خطأ فك ترميز في منتصف الملف. قد يكون خطّ بثقي قد بثّ نصف مخرجاته قبل أن يتعثر بـ JSON معطوب قرب النهاية. يفشل jq 1.7 بصوت عالٍ افتراضيًا — أنتج ‎[1,]‎ في اختبارنا ‎parse error: Expected another array element at line 1, column 4‎ برمز ٥ — لكن إذا أعدّت صدفتك توجيه stdout إلى ملف الوجهة، فالنتيجة المبتورة على القرص سلفًا. الدرع الهندسي: staging مع rename — اكتب في ملف مؤقت وانقل فوق الوجهة بعد نجاح jq فقط. ولمزيد من الدقة، يحوّل ‎--stream-errors‎ أخطاء فك الترميز إلى أحداث يمكنك معالجتها وقطعها صراحةً عبر ‎error‎.

متى لا تستخدم jq: Miller والخطوط الهجينة

jq لغة وظيفية لتحويل الأشجار، قوية في إعادة الهيكلة العميقة. لكن ما إن تتحلل المهمة إلى «رشّح وعُدّ غيغابايتات سجلات مسطّحة» حتى توجد أدوات مقصوصة أفضل. قياس dratini.tech على ٢,٥ غيغابايت JSONL (ترشيح + اختيار أعمدة):

الأداة المدة ذروة RSS
خط jq عادي ٤٨٫٢ث ٨٤ ميغابايت
jq -s نفاد ذاكرة (قتل حتى مع ١٦ غيغابايت+) —
Miller (mlr --json) ١١٫٤ث ١٨ ميغابايت
ripgrep + jq هجين ٨٫١ث ٣٢ ميغابايت

القاعدة: تداخل عميق، إعادة هيكلة، حضور في كل مكان في CI — jq. إحصاءات مسطّحة بغيغابايتات، مئينات p95، JSONL إلى TSV — أمر واحد ‎mlr --json stats1‎ يستبدل سكربت jq بذاكرة ثابتة. وإذا استطاع ripgrep استبعاد ٩٠٪ من الأسطر عديمة الفائدة قبل jq، فالطريق الهجين الأسرع.

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

من أي حجم يصبح jq -s خطيرًا؟

حد عملي: ما إن يتجاوز الملف نصف الذاكرة المتاحة حتى يُشتبه فيه. الذاكرة بعد فك الترميز تساوي نمطًا ٣ إلى ١٠ أضعاف النص (٩٫٥ ضعفًا على ٢٢٠ ميغابايت عندنا؛ شهادات خارجية تُظهر ملف ٤ غيغابايت يقتل آلة ١٦ غيغابايت). قارن أولًا ‎ls -lh‎ مع ‎free -m‎، وقرب الحد استبدل ‎-s‎ بـ ‎reduce inputs‎.

لماذا ‎-n‎ قبل ‎reduce inputs‎؟

‎-n‎ تخبر jq ألا يستهلك المدخل الأول كقيمة ابتدائية للبرنامج، ليكون ‎inputs‎ هو من يبثّ كل سجل. بلا ‎-n‎ يصير السجل الأول الحالة الابتدائية للمُجمع ويختفي بصمت من النتيجة — فقدان بيانات دون أي خطأ.

كيف تختار بين ‎--stream‎ والوضع العادي؟

انظر أولًا إلى شكل الملف. الـ JSONL تيار سطرًا بسطر سلفًا؛ ‎--stream‎ لا نفع منه. لمستند كبير واحد تريد منه قيمًا ورقية قليلة، يبدّل ‎--stream‎ نحو ثلاثة أضعاف الوقت بذاكرة أقل مئات المرات. إن سع الملف في الذاكرة فjq العادي أسرع ببساطة.

ماذا نفعل بالأسطر التالفة أثناء البث؟

في JSONL يتجاوز ‎fromjson?‎ الأسطر غير القابلة للفك لئلا يقتل سطر وسِخ واحد الخطّ. في مستند كبير واحد يُسقط خطأ فك الترميز في المنتصف التشغيل كله — انشر ذريًا عبر ملف staging وrename، أو استخدم ‎--stream-errors‎ لتحكم صريح.