مرجع jq السريع: 30 نمطاً عملياً لمعالجة JSON من سطر الأوامر

تُمرِّر kubectl get pods -o json إلى less، فيتجمد الطرفية أمام جدار JSON بحجم ميغابايتين. كل ما تريده هو اسم كل pod في الحالة Running. يُنجز jq ذلك بثلاثة أحرف من صياغة المُرشِّح — بشرط أن تعرف المفردات.

هذا ليس مرجعاً لغوياً للصياغة. إنه 30 نمطاً ستكتبها فعلاً، مُجمَّعة حسب المهمة التي تحاول إنجازها: الوصول، التصفية، التحويل، التجميع، التنسيق، ثم الدمج مع أدوات حقيقية مثل kubectl وaws وdocker.

متى تستخدم jq ومتى منسق المتصفح ومتى الكود

jq ليس دائماً الإجابة الصحيحة. الخيارات الصادقة ثلاثة:

الموقف	الأداة الأنسب	السبب
استجابة API واحدة، مع إبراز للصياغة وأرقام أسطر	منسق JSON في المتصفح	فرق بصري، بدون إعداد، خصوصية داخل المتصفح
خط أنابيب shell، معالجة سجلات، سكربت CI، خادم بعيد	jq	قابل للتركيب والأتمتة، بلا اعتماد على واجهة رسومية
منطق أعمال، اختبارات وحدة، تفرعات معقدة	كود (JS / Python)	مُصحِّح حقيقي، أنواع، مكتبات

اختر jq عندما تعيش المهمة داخل خط أنابيب shell — كل شيء آخر غالباً يكون أسهل في مكان آخر.

التثبيت وخط الأنابيب الأول

يأتي jq كملف ثنائي واحد على كل منصة رئيسية:

# macOS
brew install jq

# Debian / Ubuntu
sudo apt install jq

# Windows (winget)
winget install jqlang.jq

أول خط أنابيب بمرشح الهوية:

curl -s https://api.github.com/users/octocat | jq .

يأخذ المرشح . مدخله ويُخرجه كما هو مع تنسيق جميل. هذا وحده يغني عن أغلب لحظات “دعني أفتح هذا JSON في محرر”.

خمس علامات تغطي 90% من الاستخدام الفعلي:

العلامة	الدور
-r	إخراج خام — يزيل علامات الاقتباس المحيطة بنتائج السلاسل
-c	مدمج — قيمة JSON واحدة في كل سطر (NDJSON)
-s	slurp — يقرأ كل المدخلات في مصفوفة واحدة
-R	مدخل خام — يقرأ الأسطر كسلاسل بدلاً من JSON
-n	مدخل فارغ — لا يقرأ stdin، يستخدم null كمدخل

النموذج العقلي الأساسي: مرشحات وأنابيب

يأخذ المُرشِّح قيمة JSON واحدة كمدخل وينتج صفراً أو أكثر من قيم JSON. تتركب المرشحات بالأنبوب |، الذي يرسل كل مخرج من المرشح الأيسر كمدخل للمرشح الأيمن. النموذج ذاته كأنابيب shell، لكن تتدفق قيم JSON بدلاً من البايتات.

# . — الهوية
echo '{"name":"Alice"}' | jq '.'

# .key — وصول لحقل
echo '{"name":"Alice"}' | jq '.name'

# .key.sub — مسار عميق
echo '{"user":{"email":"a@x.com"}}' | jq '.user.email'

# .[] — تكرار عناصر المصفوفة (ينتج مخرجات متعددة)
echo '[{"id":1},{"id":2}]' | jq '.[] | .id'

# تركيب بالأنبوب: كل مخرج من .items[] يتدفق إلى .name
echo '{"items":[{"name":"a"},{"name":"b"}]}' | jq '.items[] | .name'

هذه كل القواعد اللغوية. الأنماط الـ30 أدناه ليست سوى تركيبات من هذه البدائيات.

30 نمطاً ستستخدمها فعلاً

يُظهر كل نمط مدخل JSON والأمر والمخرج. انسخ أياً منها مباشرة إلى طرفيتك.

الوصول والاستخراج (الأنماط 1–5)

النمط 1 — الوصول الآمن بـ ?

الوصول إلى حقل قد لا يكون موجوداً دون انهيار:

echo '{"name":"Alice"}' | jq '.address?.city?'
# المخرج: null

يكتم ? الأخطاء الناتجة عن المفاتيح المفقودة. بدونه سيرمي .address.city خطأ نوع إذا غاب .address.

النمط 2 — الوصول عبر مسار عميق

echo '{"user":{"profile":{"email":"a@x.com"}}}' | jq '.user.profile.email'
# المخرج: "a@x.com"

النمط 3 — تقطيع المصفوفة

echo '[10,20,30,40,50]' | jq '.[1:3]'
# المخرج: [20, 30]

echo '[10,20,30,40,50]' | jq '.[-1]'
# المخرج: 50

تُحسب الفهارس السالبة من النهاية. تستخدم الشرائح فترات نصف مفتوحة كما في Python.

النمط 4 — النزول التكراري لاستخراج كل مفتاح مطابق

echo '{"a":{"name":"x"},"b":[{"name":"y"},{"id":1}]}' | jq '.. | .name? | select(. != null)'
# المخرج: "x"
#         "y"

يتجول .. في كل قيمة داخل الشجرة. بدمجه مع .name? وselect يستخرج كل حقل name على أي عمق — أداة لا غنى عنها لاستكشاف مخططات JSON المجهولة.

النمط 5 — سرد كل مفاتيح كائن

echo '{"zebra":1,"apple":2,"mango":3}' | jq 'keys'
# المخرج: ["apple", "mango", "zebra"]

echo '{"zebra":1,"apple":2,"mango":3}' | jq 'keys_unsorted'
# المخرج: ["zebra", "apple", "mango"]

يُرتب keys أبجدياً؛ وkeys_unsorted يحافظ على ترتيب الإدخال.

التصفية (الأنماط 6–10)

النمط 6 — تصفية مصفوفة بشرط

echo '[{"age":20},{"age":30},{"age":40}]' | jq 'map(select(.age > 25))'
# المخرج: [{"age":30},{"age":40}]

يطبق map(f) الدالة f على كل عنصر؛ ويبقي select(cond) فقط العناصر التي يتحقق فيها الشرط.

النمط 7 — مطابقة بادئة السلسلة

echo '[{"name":"api-gateway"},{"name":"web-ui"},{"name":"api-auth"}]' \
  | jq '.[] | select(.name | startswith("api"))'
# المخرج: {"name":"api-gateway"}
#         {"name":"api-auth"}

مفيدة أيضاً: endswith("...")، contains("...")، test("^regex$").

النمط 8 — شروط مدمجة

echo '[{"type":"A","count":5},{"type":"A","count":15},{"type":"B","count":20}]' \
  | jq '.[] | select(.type == "A" and .count > 10)'
# المخرج: {"type":"A","count":15}

تتصرف and وor وnot كما تتوقع.

النمط 9 — حذف الحقول الحساسة

echo '{"user":"alice","password":"s3cret","token":"abc"}' | jq 'del(.password, .token)'
# المخرج: {"user":"alice"}

تقبل del() مسارات متعددة ولا تفشل إذا كان أحدها مفقوداً.

النمط 10 — إزالة التكرار حسب حقل

echo '[{"id":1,"v":"a"},{"id":2,"v":"b"},{"id":1,"v":"a2"}]' | jq 'unique_by(.id)'
# المخرج: [{"id":1,"v":"a"},{"id":2,"v":"b"}]

unique يزيل تكرار القيم الكاملة؛ وunique_by(f) يزيل التكرار حسب نتيجة مرشح.

التحويل (الأنماط 11–15)

النمط 11 — إعادة تسمية الحقول

echo '[{"first_name":"Alice","age":30}]' | jq 'map({name: .first_name, age})'
# المخرج: [{"name":"Alice","age":30}]

الصيغة المختصرة {age} تعادل {age: .age}.

النمط 12 — إضافة حقل محسوب بواسطة استيفاء السلسلة

echo '[{"first":"Alice","last":"Chen"}]' \
  | jq 'map(. + {fullName: "\(.first) \(.last)"})'
# المخرج: [{"first":"Alice","last":"Chen","fullName":"Alice Chen"}]

تُقيّم \(expr) التعبير expr وتستوفي قيمته داخل السلسلة.

النمط 13 — تسطيح مصفوفات متداخلة

echo '[{"tags":["a","b"]},{"tags":["c"]}]' | jq '[.[] | .tags[]]'
# المخرج: ["a","b","c"]

echo '[[1,2],[3,[4,5]]]' | jq 'flatten'
# المخرج: [1,2,3,4,5]

تقبل flatten معامل عمق اختيارياً: flatten(1) تقشر طبقة واحدة فقط.

النمط 14 — من كائن إلى مصفوفة والعكس

echo '{"a":1,"b":2}' | jq 'to_entries'
# المخرج: [{"key":"a","value":1},{"key":"b","value":2}]

echo '[{"key":"a","value":1},{"key":"b","value":2}]' | jq 'from_entries'
# المخرج: {"a":1,"b":2}

يُتيح هذا الثنائي تحويلات تتطلب التكرار على مفاتيح الكائن — وهو ما لا تستطيعه صياغة النقطة مباشرة.

النمط 15 — دمج عميق لكائنين

echo '{"a":{"x":1},"b":2}' | jq '. * {a:{y:9}, c:3}'
# المخرج: {"a":{"x":1,"y":9},"b":2,"c":3}

يُجري المعامل * دمجاً عميقاً. للدمج السطحي استخدم + (الجانب الأيمن يفوز).

التجميع (الأنماط 16–20)

النمط 16 — طول المصفوفات والكائنات والسلاسل

echo '[1,2,3,4]' | jq 'length'      # 4
echo '{"a":1,"b":2}' | jq 'length'  # 2
echo '"hello"' | jq 'length'        # 5

النمط 17 — جمع حقل

echo '[{"price":10},{"price":25},{"price":5}]' | jq '[.[].price] | add'
# المخرج: 40

تجمع add الأرقام، وتلحق السلاسل، وتدمج المصفوفات — حسب نوع المدخل.

النمط 18 — تجميع حسب حقل

echo '[{"cat":"A","n":1},{"cat":"B","n":2},{"cat":"A","n":3}]' | jq 'group_by(.cat)'
# المخرج: [[{"cat":"A","n":1},{"cat":"A","n":3}],[{"cat":"B","n":2}]]

تصبح كل مجموعة مصفوفة داخلية. اجمع مع map للتجميع داخل كل مجموعة.

النمط 19 — الفرز تنازلياً

echo '[{"date":"2026-01-03"},{"date":"2026-01-01"},{"date":"2026-01-02"}]' \
  | jq 'sort_by(.date) | reverse'
# المخرج: [{"date":"2026-01-03"},{"date":"2026-01-02"},{"date":"2026-01-01"}]

تاريخ ISO 8601 يُفرز كسلسلة بشكل صحيح. الصيغ الأخرى تحتاج تحليلاً أولاً — دليل طابع Unix الزمني يغطي بالتفصيل ثواني epoch والميلي ثانية والتحويل بين المناطق الزمنية.

النمط 20 — أعلى أو أقل حسب حقل

echo '[{"name":"a","rating":4.1},{"name":"b","rating":4.8},{"name":"c","rating":3.9}]' \
  | jq 'max_by(.rating)'
# المخرج: {"name":"b","rating":4.8}

تعيد min_by وmax_by عنصراً واحداً. للأعلى N استخدم sort_by(.rating) | reverse | .[:N].

تنسيق المخرجات (الأنماط 21–25)

النمط 21 — مخرج CSV

echo '[{"name":"Alice","age":30},{"name":"Bob","age":25}]' \
  | jq -r '.[] | [.name, .age] | @csv'
# المخرج: "Alice",30
#         "Bob",25

يضع @csv علامات الاقتباس حول السلاسل ويهرّب العلامات الداخلية. يحذف -r علامات الاقتباس الخارجية لـJSON لتمرير CSV مباشرة. لدورة التحويل الكاملة بين CSV وJSON داخل الأنابيب، راجع دليل تحويل CSV إلى JSON.

النمط 22 — مخرج TSV

echo '[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]' \
  | jq -r '.[] | [.id, .name] | @tsv'
# المخرج: 1	Alice
#         2	Bob

المخرج المفصول بتاب ينسجم جيداً مع cut وawk وcolumn -t.

النمط 23 — مخرج سلسلة خام

echo '["alpha","beta"]' | jq -r '.[]'
# المخرج: alpha
#         beta

بدون -r سيحاط كل سطر بعلامات اقتباس. المخرج الخام هو ما تُغذي به xargs وwhile read أو أمر shell آخر.

النمط 24 — NDJSON / JSON Lines

echo '[{"a":1},{"a":2}]' | jq -c '.[]'
# المخرج: {"a":1}
#         {"a":2}

كل سطر قيمة JSON مستقلة — التنسيق الذي يستخدمه Kafka وElasticsearch ومعظم مُسجِّلات البيانات المُهيكلة. يحذف -c أيضاً كل المسافات البيضاء الداخلية.

النمط 25 — استيفاء سلسلة لمخرج منسق

echo '[{"name":"server-1","cpu":0.73},{"name":"server-2","cpu":0.21}]' \
  | jq -r '.[] | "\(.name): \(.cpu * 100)% CPU"'
# المخرج: server-1: 73% CPU
#         server-2: 21% CPU

مثالي للملخصات وأسطر السجلات حيث يكون JSON الخام ضوضاء.

DevOps على أرض الواقع (الأنماط 26–30)

النمط 26 — kubectl: أسماء كل pod في حالة التشغيل

kubectl get pods -o json \
  | jq -r '.items[] | select(.status.phase=="Running") | .metadata.name'

خط الأنابيب: كرِّر على الـpods، احتفظ فقط بحالة Running، أصدر الاسم كسلسلة خام.

النمط 27 — AWS EC2: معرِّفات المثيلات مع عناوين IP عامة

aws ec2 describe-instances \
  | jq -r '.Reservations[].Instances[] | [.InstanceId, .PublicIpAddress // "none"] | @tsv'

يُوفِّر المعامل البديل // قيمة احتياطية حين يكون الحقل null — لتجنب ظهور null حرفياً في عمود المخرج.

النمط 28 — واجهة GitHub API: دمج نتائج مقسمة إلى صفحات

for p in 1 2 3; do
  curl -s "https://api.github.com/orgs/myorg/repos?per_page=100&page=$p"
done | jq -s 'add | map(.name)'

يجمع -s كل الاستجابات في مصفوفة من المصفوفات، ويلحقها add، ثم يستخرج map(.name) الأسماء. نمط شائع لأي واجهة API ذات ترقيم صفحات.

النمط 29 — تصفية ملفات السجلات المهيكلة

cat app.log | jq -c 'select(.level=="error")'

يفترض أن ملف السجل بتنسيق NDJSON (كائن JSON واحد لكل سطر). ادمجه مع tail -f للمراقبة الحية:

tail -f app.log | jq -c 'select(.level=="error") | {ts: .timestamp, msg: .message}'

النمط 30 — Docker: كل أسماء الصور قيد الاستخدام

docker inspect $(docker ps -q) | jq -r '.[].Config.Image' | sort -u

مفيد للتحقق سريعاً من إصدارات الصور التي تعمل على مضيف.

الأخطاء الشائعة وكيفية إصلاحها

يصطدم كل مستخدم لـjq بهذه. معرفة الحل مسبقاً توفر ساعات.

Cannot iterate over null (null)

الحقل الذي حاولت التكرار عليه كان null أو مفقوداً. إصلاحان:

# الخيار أ: المعامل الاختياري
echo '{}' | jq '.items[]?'
# المخرج: (لا شيء، بدون خطأ)

# الخيار ب: المعامل البديل مع قيمة افتراضية
echo '{}' | jq '(.items // [])[]'
# المخرج: (لا شيء، بدون خطأ)

استخدم ? للتخطي الصامت. استخدم // [] لفرض مصفوفة فارغة ملموسة حتى تواصل المرشحات التالية عملها.

Cannot index array with "key"

كتبت .foo لكن القيمة الحالية مصفوفة. أضف [] للتكرار:

# خطأ
echo '{"users":[{"name":"Alice"}]}' | jq '.users.name'
# Error: Cannot index array with "name"

# صحيح
echo '{"users":[{"name":"Alice"}]}' | jq '.users[].name'
# المخرج: "Alice"

مشاكل علامات الاقتباس في shell

أحط برنامج jq كله بعلامات اقتباس مفردة، واستخدم العلامات المزدوجة داخلياً للسلاسل الحرفية:

# يعمل في كل مكان
jq '.users[] | select(.role == "admin")'

# ينكسر — يُفسر الـshell العلامات المزدوجة أولاً
jq ".users[] | select(.role == \"admin\")"

حالات PowerShell على Windows

لا يعامل PowerShell العلامات المفردة بنفس الطريقة. يفضل استخدام العلامات المزدوجة حول البرنامج مع تهريب العلامات الداخلية، أو استخدام here-string:

jq "@'
.users[] | select(.role == \"admin\")
'@"

لأي شيء غير تافه، احفظ المرشح في ملف .jq ونفذ jq -f filter.jq.

سوء استخدام -r

يؤثر -r فقط على نتائج السلاسل. تطبيقه على كائن ينتج كائن JSON عادياً:

echo '{"a":1}' | jq -r '.'
# المخرج: {"a":1}     ← دون تغيير؛ لم يكن هناك ما يزيله -r

إن أردت حقلاً محدداً بلا علامات اقتباس، اختره أولاً: jq -r '.a'.

jq يرفض JSON بتعليقات أو فواصل نهائية

echo '{"a": 1, /* ملاحظة */ "b": 2,}' | jq .
# parse error: Invalid numeric literal

يتبع jq بدقة معيار RFC 8259 لـJSON — بلا تعليقات، بلا فواصل نهائية، بلا مفاتيح بدون علامات اقتباس. إن كان الملف JSON5 أو JSONC (شائع في ملفات التكوين)، أزل هذه الامتدادات قبل تمريره إلى jq. دليل تنسيق JSON5 وJSONC يشرح أي المحللات تدعمها وكيفية التحويل إلى JSON صارم.

jq مقابل البدائل: gron، fx، jj، yq

jq ليس الخيار الوحيد، وأحياناً تكون أداة أخرى أسرع:

الأداة	نقطة القوة	متى تلجأ إليها
gron	يسطح JSON إلى مسارات قابلة للبحث بـgrep	استكشاف مخططات مجهولة — لا تعرف أين المفتاح
fx	مستكشف TUI تفاعلي مع إبراز	تصفح JSON كبيرة يدوياً
jj	أسرع بكثير من jq، لكن صياغته محدودة	حلقات ساخنة تعالج ملايين السجلات
yq	نفس لغة المرشحات لكن لـYAML	ملفات Kubernetes وتكوينات CI
منسق JSON في المتصفح	إبراز للصياغة، رسائل خطأ دقيقة، بدون تثبيت	تصحيح استجابة واحدة أثناء التطوير

لعمل shell اليومي، يفوز jq بالتركيبية. لاستكشاف عابر، gron أسرع غالباً. لـYAML استخدم yq — لا تحاول خط yq-ثم-jq.

نصائح محترفة للاستخدام اليومي

عادات تجعل jq طبيعياً تحت يديك:

1. احتفظ بـ .jqrc في $HOME. ضع فيه دوال مساعدة، وستكون متاحة في كل استدعاء لـjq:

   def running: select(.status.phase == "Running");
   def table(f): [f] | @tsv;

2. استخدم jqplay.org للمرشحات المعقدة. الصق JSON على اليسار، كرر المرشح على اليمين، انقل النسخة العاملة إلى سكربتك.

3. ابنِ مرجعك السريع من history. الأمر history | grep 'jq ' | sort -u > ~/jq-patterns.txt يلتقط كل نمط استخدمته فعلاً.

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

5. راقب القيم الحية: watch -n 5 "curl -s api.example.com/health | jq '.uptime'" يُحدِّث كل 5 ثوانٍ — لوحة مراقبة صغيرة بلا اعتماديات.

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

ما هو jq ولماذا يستخدمه المطورون؟

jq معالج JSON من سطر الأوامر. يستخرج البيانات ويصفيها ويحوّلها داخل خطوط أنابيب shell دون سكربت Python أو Node — أقصر طريق من استجابات API أو ملفات السجلات أو مخرجات kubectl إلى الحقل المطلوب.

هل jq متاح على Windows؟

نعم. ثبّت عبر winget install jqlang.jq أو Chocolatey بأمر choco install jq، أو نزِّل الملف الثنائي من jqlang.org. قواعد الاقتباس في PowerShell تختلف عن bash — عند الشك، احفظ المرشحات في ملف .jq ونفذ jq -f filter.jq.

ما الفرق بين jq ومنسق JSON في المتصفح؟

منسق JSON في المتصفح تفاعلي — تلصق JSON، ترى الإبراز والأخطاء، تنسخ النتيجة. jq غير تفاعلي — تصف التحويل مرة، يعمل داخل خط أنابيب shell. استخدم المتصفح لتصحيح استجابة واحدة؛ وjq لأتمتة نفس العملية على مئات المدخلات.

لماذا يقول jq “Cannot iterate over null”؟

حاولت التكرار (.[]) على قيمة null — عادة لأن الحقل كان مفقوداً من المدخل. أصلح بالمعامل الاختياري .items[]? أو بإعطاء قيمة افتراضية عبر .items // [] | .[].

هل يستطيع jq تعديل الملفات في مكانها؟

ليس مباشرة — يكتب jq إلى stdout. استخدم ملفاً مؤقتاً أو sponge من moreutils: jq '.version = "2.0"' config.json | sponge config.json. انسخ الأصل احتياطياً أولاً دائماً؛ مرشح مكتوب خطأً سيكتب فوق الملف.

كيف أستخدم jq مع استجابات curl؟

مرر curl -s إلى jq. تُسكت العلامة -s شريط تقدم curl ليصل جسم JSON فقط إلى jq:

curl -s https://api.github.com/users/octocat | jq '.name, .blog'

ما الفرق بين | في jq و| في shell؟

أنبوب shell ينقل البايتات بين العمليات. أنبوب jq ينقل قيم JSON بين المرشحات داخل استدعاء jq واحد. أمر بأنابيب داخلية متعددة يعمل في عملية واحدة — أرخص من سلسلة jq | jq | jq.

هل يتعامل jq مع JSON Lines (NDJSON)؟

نعم، بشكل أصلي. يقرأ jq كل سطر كقيمة JSON مستقلة عندما تفصلها مسافات بيضاء. استخدم -c لإصدار NDJSON و-s لجمعه في مصفوفة واحدة.

كيف أنسق JSON دون تصفية؟

استخدم مرشح الهوية: cat data.json | jq . أو jq . < data.json. يُحلل ويُتحقق ويُنسق بمسافتين — دون أي مرشح.

هل هناك بديل لـjq بواجهة رسومية؟

نعم. يوفر fx واجهة TUI تفاعلية. لواجهة بلا تثبيت، يغطي منسق JSON في المتصفح معظم احتياجات الاستكشاف والتحقق. الأدوات الشبكية مثل jqplay.org توفر jq ذاته مع معاينة حية.

متى أستخدم jq بدلاً من كتابة سكربت Python؟

اختر jq حين تكون المهمة لمرة واحدة، وتناسب خط أنابيب shell، وتبقى ضمن دلالات التصفية والتحويل والاستخراج. انتقل إلى Python إذا احتجت اختبارات وحدة، أو حالة معقدة، أو مكتبات خارجية، أو منطق تفرّع يتجاوز قابلية القراءة لملف .jq.

كيف أستخدم التعبيرات المنتظمة في jq؟

يوفر jq التعبيرات المنتظمة عبر test("pattern") وmatch("pattern") وcapture("pattern") وscan("pattern")، جميعها بصياغة PCRE. مرّر أعلام المعالجة كمعامل ثانٍ: test("abc"; "i") لتجاهل حالة الأحرف. يعيد match الإزاحات والتقاطات، ويعدّد scan كل تطابق غير متداخل.

كيف أحافظ على الأحرف العربية في مخرجات jq دون هروب Unicode؟

يُصدر jq UTF-8 افتراضياً ويحافظ على الأحرف العربية، ما لم تستخدم -a / --ascii-output. إن رأيت \u0645\u0631\u062d\u0628\u0627 بدل النص العربي، فالسبب عادة locale الطرفية: تأكد أن $LANG يساوي ar_SA.UTF-8 أو en_US.UTF-8، وتجنب العلامة -a.

النقاط الرئيسية

1. النموذج العقلي أولاً: مرشح يدخل، صفر أو أكثر من قيم JSON تخرج، تركيب بـ|. كل ما عداه صياغة.
2. تعلَّم بالمهمة لا بالمعامل: الأنماط الـ30 أعلاه تغطي نحو 95% من الاستخدام اليومي لـjq.
3. تعامل مع null صراحة: ? للتخطي الصامت، و// default للرجوع الملموس. معظم إصلاحات Cannot iterate over null تمر بأحدهما.
4. اعرف متى يكون jq الأداة الخاطئة: الاستجابات المفردة تنتمي إلى منسق JSON في المتصفح؛ وYAML ينتمي إلى yq؛ والمنطق المعقد ينتمي إلى كود حقيقي.
5. اربطه بحُزمك الحالية: يلمع jq داخل curl وkubectl وaws وdocker وخطوط السجلات. استخدمه كلاصق، لا كطبقة منطق.

لسير عمل JSON ذات صلة، راجع دليل تنسيق JSON5 وJSONC لامتدادات صياغة ملفات التكوين، ودليل تحويل CSV إلى JSON لهجرات تنسيقات البيانات حيث يتموضع jq داخل خط الأنابيب. عندما يحتوي JSON على طوابع زمنية، يغطي دليل طابع Unix الزمني الفخاخ التي ستصادفها أثناء تحويل حقول التاريخ.