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

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 لتحكم صريح.