JSON Toolkit

jq וקבצי JSON גדולים: מדוע ‎-s‎ מפוצץ זיכרון וכיצד לעבד בסטרימינג

שורה תחתונה: צבירת מאות מגהבייט של לוגים בפורמט JSON עם jq -s מסתיימת ב־OOM, בעוד ש־reduce inputs מייצר את אותה סטטיסטיקה בכמה מגהבייטים בלבד של זיכרון RAM. נמדד על דגימה של 220MB ושני מיליון שורות: slurp מגיע ל־2.08GB מול 3.5MB למפחית הסטרימינג. המאמר מסביר את מנגנון צריכת הזיכרון, את העיבוד שורה־שורה של JSONL, את אירועי הנתיב של ‎--stream‎ ושלוש מלכודות אמיתיות, כולל הפלט הריק השקט של ‎-n --stream.

מתקדםכ-6 דקות קריאהפורסם 2026-11-12עודכן 2026-11-12
השוואת זיכרון בין jq סטרימינג ל‎-s‎ על JSON גדולים

jq מפרסר מהר, אבל כמעט כל מוות מול קובץ של כמה מאות מגהבייט חוזר לאותו דגל: ‎-s‎ טוען את כל הקלט למערך ענק אחד, ו־RSS השיא מגיע בקלות לכמה כפולות של גודל הקובץ.

קובץ אחד, שתי שאילתות: 580 פעמים פחות זיכרון

נתחיל במדידה. הדגימה היא לוג JSONL של 220MB ו־2,000,000 שורות (רשומת בקשה אחת לשורה: 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 10.1s 2.08GB (~9.5 כפולות גודל הקובץ)
jq -n 'reduce inputs ...' אותה ספירה 4.7s 3.5MB
jq -r 'select(...) | .path' סינון שורה־שורה 2.6s 3.6MB

אותה סטטיסטיקה, 580 פעמים פחות זיכרון, וגם מהיר יותר. זה לא באג של jq — ‎-s‎ משמעותו לפי ההגדרה «קרא הכול למערך»; רוב האנשים פשוט לא מעריכים את העלות המובנית הזאת. מקורות חיצוניים מסכימים: תיאור ניסיון עם 2.3GB של JSONL בקהילת Huawei Cloud מספר בדיוק את אותו סיפור — OOM עם slurp, ואז המפחית הסטרימינג מסיים ב־47 שניות עם RSS מעט מעל 30MB. Dratini.tech מדדה על קלט של 2.5GB ‎jq -s‎ שנהרג על ידי OOM killer אפילו על מכונה עם 16GB ומעלה, בזמן שהצינור הרגיל השלים ב־48.2 שניות עם 84MB.

המסקנה קודם כול: אם הקובץ חוצה את מחצית הזיכרון הפנוי, ‎-s‎ בכלל אינו מועמד. מדדו שלושה דברים לפני שתכתבו משהו: ‎ls -lh‎ לגודל, ‎free -m‎ לשוליים בזיכרון, ‎wc -l‎ למספר השורות.

לאן הזיכרון באמת הולך

‎jq -s‎ (slurp) מתועד כ־«קרא את כל הקלטים למערך». העלות האמיתית חורגת בהרבה מהטקסט: אחרי הפרסור jq מחזיק עץ של מבני C, וכל אובייקט, מערך, מחרוזת ומספר נושאים צומת משלהם עם מטא־דאטה. 220MB של טקסט הפכו אצלנו למשהו מעל 2GB של מבנים — נפיחה של כ־9.5 כפולות. ‎group_by‎ בנוסף ממיין ומקבץ בזיכרון, ומגדיל את השיא עוד יותר.

מסמך JSON גדול יחיד מתנהג אותו הדבר. עיטוף אותו לוג במערך שורש של 300MB וחילוץ במסנן רגיל:

שאילתה משך שיא RSS
jq '.[] | select(.level=="ERROR") | .uid' (המסמך כולו) 4.7s 1.85GB
jq --stream 'select(...)' (אירועי נתיב) 13.4s 3.4MB

פרסור מלא עדיין מגיע לשיא סביב 1.8GB — jq בונה את כל העץ לפני שהמסנן רץ. ‎--stream‎ מחליף כ־3 כפולות של זמן ריצה בזיכרון קטן פי 540. את המודל המפורט של הנפיחה הזאת פיתחו במאין בא הזיכרון.

לוגים של 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‎ והרשומה הראשונה נבלעת כמצב ראשוני.
  • מצב המפחית חייב להיות בצורה קבועה — מונים ומצברים בלבד. כבר שתדחפו את השורות התואמות למערך בתוך המפחית, הזיכרון חוזר לגדול עם נפח הנתונים והסטרימינג מפסיק לשווה דבר.

מכאן ה־3.5MB בטבלה: שני גיגהבייט עברו, נשארה רק טבלת גיבוב.

מסמך ענק יחיד: אירועי הנתיב של ‎--stream

כשהקלט הוא מסמך שורש ענק אחד (ייצוא של כמה מאות MB בלי גבולות שורות), השתמשו ב‎--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‎ מסתיים בקוד 0, בלי פלט ובלי שגיאה — במצב ‎-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‎ עם קוד 5 — אבל אם המעטפת מפנה את stdout לקובץ היעד, התוצאה הקטועה כבר על הדיסק. המגן ההנדסי: staging ואז rename — כתבו לקובץ זמני והזיזו על היעד רק אחרי הצלחת jq. לשליטה עדינה יותר, ‎--stream-errors‎ הופך שגיאות פרסור לאירועים שאתם יכולים לעבד ולעצור במפורש דרך ‎error‎.

מתי לא להשתמש ב־jq: Miller וצינורות היברידיים

jq היא שפה פונקציונלית לטרנספורמציה של עצים, חזקה בשחזור מבנה עמוק. אבל ברגע שהמשימה מתדרדרת ל«סנן וספור גיגהבייטים של לוגים שטוחים», יש כלים שנחתכים טוב יותר. הבנצ'מרק של dratini.tech על 2.5GB JSONL (סינון + בחירת עמודות):

כלי משך שיא RSS
צינור jq רגיל 48.2s 84MB
jq -s OOM (נהרג גם עם 16GB+) —
Miller (mlr --json) 11.4s 18MB
ripgrep + jq היברידי 8.1s 32MB

הכלל: קינון עמוק, שחזור מבנה, נוכחות בכל מקום ב־CI — jq. סטטיסטיקות שטוחות בגיגהבייטים, אחוזונים p95, JSONL ל־TSV — ‎mlr --json stats1‎ אחד מחליף סקריפט jq בזיכרון קבוע. ואם ripgrep יכול להוציא 90% מהשורות המיותרות לפני jq, הדרך ההיברידית הכי מהירה.

שאלות נפוצות

מאיזה גודל jq -s מסוכן?

סף מעשי: ברגע שהקובץ חוצה את מחצית הזיכרון הפנוי, החשד מתעורר. הזיכרון אחרי פרסור שווה בדרך כלל 3–10 כפולות של הטקסט (9.5 כפולות על 220MB שלנו; דיווחים חיצוניים מציגים קובץ 4GB שהורג מכונת 16GB). השוו קודם ‎ls -lh‎ מול ‎free -m‎, וקרוב לגבול החליפו ‎-s‎ ב‎reduce inputs‎.

למה ‎-n‎ לפני ‎reduce inputs‎?

‎-n‎ אומר ל־jq לא לצרוך את הקלט הראשון כערך ראשוני של התוכנית, כדי ש‎inputs‎ עצמו יפיק כל רשומה. בלי ‎-n‎ הרשומה הראשונה הופכת למצב הראשוני של המפחית ונעלמת בשקט מהתוצאה — אובדן נתונים בלי שום שגיאה.

איך בוחרים בין ‎--stream‎ למצב הרגיל?

הסתכלו קודם על צורת הקובץ. JSONL כבר זרימה שורה־שורה; ‎--stream‎ לא נותן דבר. למסמך גדול יחיד שממנו רוצים רק כמה ערכי עלים, ‎--stream‎ מחליף כ־3 כפולות זמן בזיכרון קטן מאות כפולות. אם הקובץ נכנס לזיכרון, jq רגיל פשוט מהיר יותר.

מה עושים עם שורות שבורות בסטרימינג?

ב־JSONL, ‎fromjson?‎ מדלג על שורות שאי אפשר לפרסר כדי ששורה מלוכלכת אחת לא תהרוג את הצינור. במסמך גדול יחיד, שגיאת פרסור באמצע הקובץ מפילה את הריצה כולה — פרסמו אטומית דרך קובץ staging ו־rename, או השתמשו ב‎--stream-errors‎ לשליטה מפורשת.