JSON Toolkit

jq و فایل‌های JSON بزرگ: چرا -s حافظه را منفجر می‌کند و چگونه به‌صورت استریمی پردازش کنیم

جمع‌بندی: تجمیع چند صد مگابایت لاگ JSON با jq -s به OOM ختم می‌شود، در حالی که reduce inputs همان آمار را تنها با چند مگابایت RAM تولید می‌کند. اندازه‌گیری روی نمونه ۲۲۰ مگابایت و ۲ میلیون خط: slurp به ۲,۰۸ گیگابایت می‌رسد در برابر ۳,۵ مگابایت برای reducer استریمی. این مقاله سازوکار مصرف حافظه، پردازش خط‌به‌خط 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 دقیقاً همین قصه را می‌گوید — OOM با slurp، سپس reducer استریمی که در ۴۷ ثانیه با 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 و اولین رکورد به‌عنوان وضعیت اولیه بلعیده می‌شود.
  • وضعیت reducer باید شکل ثابت داشته باشد — فقط شمارنده‌ها و انباشتگرها. به‌محض آنکه خطوط منطبق را داخل آرایه‌ای در reducer بریزید، حافظه دوباره با حجم داده بالا می‌رود و استریم دیگر هیچ سودی ندارد.

از این‌جا ۳,۵ مگابایت جدول است: دو گیگابایت رد شد، فقط یک جدول هش باقی ماند.

یک سند بزرگ تنها: رویدادهای مسیرِ --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 ورودی را نمی‌خواند و 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 با mv روی مقصد بیندازید. برای کنترل دقیق‌تر، --stream-errors خطاهای پارس را به رویدادهایی تبدیل می‌کند که می‌توانید پردازششان کنید و با error صریحاً متوقف سازید.

کِی از jq استفاده نکنیم: Miller و پایپ‌لاین‌های ترکیبی

jq زبانی کارکردی برای تبدیل درخت‌هاست، قوی در بازآرایی‌های عمیق. اما به‌محض آنکه کار تنزل کند به «فیلتر و شمارشِ گیگابایت‌ها لاگ تخت»، ابزارهای به‌دوریده‌تری هست. بنچمارک dratini.tech روی ۲,۵ گیگابایت JSONL (فیلتر + انتخاب ستون):

ابزار زمان RSS اوج
پایپ‌لاین jq معمولی ۴۸٫۲ث ۸۴ مگابایت
jq -s OOM (کشته‌شده حتی با ۱۶ گیگابایت+) —
Miller (mlr --json) ۱۱٫۴ث ۱۸ مگابایت
ripgrep + jq ترکیبی ۸٫۱ث ۳۲ مگابایت

قاعده: تودرتویی عمیق، بازآرایی، حضور همه‌جا در CI — jq. آمار تختِ چند گیگابایتی، صدک‌های p95، JSONL به TSV — یک mlr --json stats1 با حافظهٔ ثابت جایگزین اسکریپت jq می‌شود. و اگر ripgrep بتواند ۹۰٪ خطوط بی‌فایده را پیش از jq کنار بگذارد، راه ترکیبی سریع‌ترین است.

FAQ

از چه حجمی jq -s خطرناک می‌شود؟

مرز عملی: به‌محض آنکه فایل از نیمی از حافظهٔ در دسترس بگذرد، مشکوک فرض کنید. حافظهٔ پس از پارس معمولاً ۳ تا ۱۰ برابر متن است (۹٫۵ برابر روی ۲۲۰ مگابایت ما؛ گزارش‌های ثالث فایل ۴ گیگابایتی‌ای را نشان می‌دهند که ماشین ۱۶ گیگابایتی را می‌کشد). اول ls -lh را با free -m بسنجید و نزدیک مرز، -s را با reduce inputs جایگزین کنید.

چرا -n پیش از reduce inputs؟

-n به jq می‌گوید اولین ورودی را به‌عنوان مقدار اولیهٔ برنامه مصرف نکند، تا inputs خودش هر رکورد را ساطع کند. بدون -n، رکورد اول وضعیت اولیهٔ reduce می‌شود و بی‌صدا از نتیجه محو می‌گردد — گم‌شدن داده بدون هیچ خطایی.

بین --stream و حالت معمولی چگونه انتخاب کنیم؟

اول شکل فایل را ببینید. JSONL خودش استریم خط‌به‌خط است؛ --stream کاری نمی‌کند. برای یک سند بزرگ تنها که فقط چند مقدار برگ می‌خواهید، --stream حدود ۳ برابر زمان را با حافظهٔ صدها برابر کمتر معامله می‌کند. اگر فایل در حافظه جا شود، jq معمولی صرفاً سریع‌تر است.

با خطوط خراب حین استریم چه کنیم؟

در JSONL، fromjson? خطوط غیرقابل‌پارس را رد می‌کند تا یک خط کافی نباشد که پایپ‌لاین را بکشد. در سند بزرگ تنها، خطای پارس وسط فایل کل اجرا را می‌اندازد — به‌صورت اتمی از طریق فایل staging و rename منتشر کنید، یا برای کنترل صریح از --stream-errors استفاده کنید.