jq JSON के लिए sed है — एक lightweight, flexible command-line processor जो messy API responses और config files को बिलकुल उस data में बदल देता है जो आपको चाहिए। अगर आपने कभी minified JSON की दीवार में घूरते हुए एक nested field ढूंढने की कोशिश की है, तो jq वह tool है जो आपको सोचने पर मजबूर करेगा कि इसके बिना कैसे काम चलता था।
Mental model सीधा है: jq एक pipeline है। Data बाएँ से आता है, filters से transform होता है, और दाईं तरफ निकलता है। . आपका starting point है — इसका मतलब है "पूरा input।" वहाँ से .field से drill down करें, .[] से iterate करें, और | से filters chain करें। यह functional programming है जो command-line tool जैसी दिखती है, और एक बार pipe-thinking click हो जाए, तो आप jq के लिए वैसे ही हाथ बढ़ाएंगे जैसे grep के लिए बढ़ाते हैं।
हमने इसे jq की internal taxonomy के बजाय उस तरह की problem के अनुसार organize किया है जो आप solve कर रहे हैं। JSON से values निकालने के लिए Basic Filters से शुरू करें, फिर जब data reshape करना हो तो Array और Object Operations पर जाएँ। आखिर में One-Liners section में असली magic है — battle-tested patterns जो आप अभी अपने terminal में copy-paste कर सकते हैं।
एक बात जल्दी internalize करें: jq expressions composable हैं। हर filter input लेता है और output produce करता है, इसलिए आप इन्हें | से अंतहीन chain कर सकते हैं। वह select(...) जो आपने लिखा? इसे map(...) में pipe करें। उसे sort_by(...) में pipe करें। Filters ही filters हैं, बस।
Basic Filters
.
Identity — पूरा input unchanged output करें.field
नाम से top-level field extract करें.field.nested
Dot notation से nested objects में drill करें.["hyphenated-key"]
नाम में special characters वाले fields access करें.[]
Array के सभी elements या object की सभी values पर iterate करें.[0]
Array का पहला element लें.[-1]
Array का आखिरी element लें.[2:5]
Array slice करें — index 2, 3, और 4 के elements.field?
Field access try करें — exist नहीं करने पर errors suppress करें.[] | .name
Array iterate करें और हर element से field extract करेंTypes और Values
length
String length, array count, या object keys की संख्याkeys
Object के सभी keys sorted array के रूप में लेंkeys_unsorted
Object के सभी keys original order में लेंvalues
Object की सभी values array के रूप में लेंtype
Type string के रूप में return करें: "object", "array", "string", "number", "boolean", या "null"has("field")
Check करें कि object में specific key है या नहीं (true/false return करता है)in({"a":1})
Check करें कि key दिए गए object में exist करती हैempty
कोई output produce न करें — conditional suppression के लिए उपयोगीenv.VAR
Environment variable VAR access करेंString Operations
split(",")
Delimiter से string split करके array बनाएँjoin(",")
Strings के array को delimiter से join करेंtest("regex")
Test करें कि string regex से match करती है (true/false return करता है)match("regex")
Offset, length, और captures के साथ match object return करेंcapture("(?<name>\\w+)")
Named capture groups object के रूप में return होंgsub("old"; "new")
Regex pattern की सभी occurrences replace करेंsub("old"; "new")
Regex pattern की पहली occurrence replace करेंascii_downcase
String lowercase में convert करेंascii_upcase
String uppercase में convert करेंltrimstr("prefix")
String से prefix हटाएँ अगर मौजूद होrtrimstr("suffix")
String से suffix हटाएँ अगर मौजूद हो@base64
String को base64 में encode करें@base64d
Base64 string decode करें@uri
URLs के लिए string percent-encode करें@html
HTML special characters escape करेंtostring
किसी भी value को string representation में convert करेंtonumber
String को number के रूप में parse करेंArray Operations
map(f)
हर element पर filter f apply करें और results collect करेंmap_values(f)
हर value पर filter f apply करें (objects पर भी काम करता है)select(condition)
सिर्फ वे elements रखें जहाँ condition true होsort
Comparable values का array sort करेंsort_by(.field)
Objects के array को specific field से sort करेंreverse
Array का order reverse करेंgroup_by(.field)
Array elements को field से sub-arrays में group करेंunique
Sorted array से duplicate values हटाएँunique_by(.field)
Specific field से duplicates हटाएँflatten
Nested arrays को single level में flatten करेंflatten(1)
एक level की nesting flatten करेंfirst
Generator से पहला output लेंlast
Generator से आखिरी output लेंlimit(n; expr)
Expression से सिर्फ पहले n outputs लेंadd
Numbers जोड़ें, strings concatenate करें, या arrays/objects merge करेंany(condition)
True अगर कोई भी element condition satisfy करेall(condition)
True अगर सभी elements condition satisfy करेंmin_by(.field)
सबसे छोटी field value वाला element लेंmax_by(.field)
सबसे बड़ी field value वाला element लेंindices(value)
Array में जहाँ value appear होती है वे सभी indices लेंcontains([values])
Check करें कि array में सभी specified values हैंinside([values])
Check करें कि input दिए गए value में contained हैObject Operations
to_entries
{"a":1} को [{"key":"a","value":1}] में convert करेंfrom_entries
[{"key":"a","value":1}] को वापस {"a":1} में convert करेंwith_entries(f)
to_entries | map(f) | from_entries का shorthand+ (objects)
दो objects merge करें — key conflicts में right side जीतता है* (objects)
दो objects recursively merge करें{name, age}
Object से specific fields select करें{newname: .oldname}
Extract करते समय field rename करेंdel(.field)
Object से field हटाएँpaths
Leaf values तक सभी paths arrays के रूप में list करेंgetpath(["a","b"])
Specific path पर value लें — .a.b जैसाsetpath(["a","b"]; val)
Specific path पर value set करेंdelpaths([path])
Specified paths पर values delete करेंConditionals और Comparisons
if . then A else B end
Conditional expression — else clause optional है// (alternative)
Left null या false हो तो right value इस्तेमाल करेंa == b
Equality comparison (objects/arrays के लिए deep equality)a != b
Inequality comparisonand, or, not
Boolean operatorstry f
Filter f चलाएँ, errors चुपचाप suppress करेंtry f catch msg
Filter f चलाएँ, error पर msg expression इस्तेमाल करेंf as $var | expr
Pipeline में इस्तेमाल के लिए value को variable में bind करेंreduce .[] as $x (init; update)
Array को single value में fold करेंlabel $out | foreach ...
Break support के साथ streaming loopOutput Formatting
-r (--raw-output)
JSON quotes के बिना raw strings output करें-c (--compact-output)
Minify — JSON single line पर print करें-S (--sort-keys)
Output में object keys alphabetically sort करें-e (--exit-status)
Output के आधार पर exit code set करें: true/non-null के लिए 0, false/null के लिए 1-n (--null-input)
Input न पढ़ें — --argjson या --slurpfile के साथ उपयोगी-s (--slurp)
सभी inputs एक single array में पढ़ें--arg name val
String value को $name variable के रूप में pass करें--argjson name val
JSON value को $name variable के रूप में pass करें--slurpfile name file
JSON file को $name variable (array) के रूप में load करें@csv
Arrays के array को CSV format में बदलें@tsv
Arrays के array को TSV format में बदलें@json
Value को JSON string के रूप में serialize करें (embedding के लिए)@text
Text output में convert करेंOne-Liners
Real-world patterns जो आप वाकई इस्तेमाल करेंगे। Copy करें, paste करें, adapt करें।
One-Liners
jq . file.json
JSON file pretty-print करेंjq -r ".[] | .name" file.json
Array में हर object से field extract करेंjq "[.[] | select(.active == true)]"
Array को सिर्फ matching elements तक filter करेंjq -r ".[] | [.name, .email] | @csv"
JSON array को CSV में convert करेंjq -s "." file1.json file2.json
Multiple JSON files को एक array में merge करेंjq -r "keys[]" file.json
सभी top-level keys list करेंjq ".[] | select(.price > 100) | .name"
वे names ढूंढें जहाँ price threshold से ज़्यादा होjq "group_by(.status) | map({(.[0].status): length}) | add"
हर group में items count करेंjq --arg q "$QUERY" '.[] | select(.name | test($q; "i"))'
Shell variable इस्तेमाल करके case-insensitive searchjq -r "to_entries[] | \"\(.key)=\(.value)\""
JSON object को key=value lines में convert करेंjq "[.[] | {id, name}]"
Objects reshape करें — सिर्फ specific fields रखेंjq -r ".results | sort_by(.date) | reverse | .[0]"
Sorted array से सबसे recent entry लेंcurl -s api.example.com | jq .
API response inline pretty-print करेंjq -s "map(.items) | flatten | unique_by(.id)"
Paginated API responses merge और deduplicate करेंjq 'walk(if type == "string" then gsub("\\n"; " ") else . end)'
सभी string values में recursively newlines clean up करेंजब भी आप jq को दूसरे command में pipe करें, -r (raw output) इस्तेमाल करें। इसके बिना, strings quotes में wrapped आती हैं, और वे quotes आपकी shell scripts में problems create करेंगे। jq -r '.name' आपको Alice देता है, "Alice" नहीं।
// operator jq का null coalescing है — left null या false हो तो right side return करता है। Defaults के लिए perfect: .config.timeout // 30। यह दो-character combo है जो 90 प्रतिशत बार आपको पूरा if-then-else लिखने से बचाता है।
जब आपको multiple files या API responses से data combine करना हो, --slurp (-s) इस्तेमाल करें। यह सभी inputs एक single array में पढ़ता है, ताकि आप objects add कर सकें, arrays flatten कर सकें, या files में data zip कर सकें।
Shell variables को jq में safely pass करने के लिए --arg और --argjson इस्तेमाल करें। Shell variables सीधे jq expressions में कभी interpolate न करें — special characters पर break होता है और injection का खतरा होता है। jq --arg name "$USER" '.[] | select(.name == $name)' सही तरीका है।
Kubernetes secrets या JWTs के साथ काम करते समय @base64d filter lifesaver है। Base64-encoded value को jq -r '.data.password | @base64d' से pipe करें और pipeline छोड़े बिना plaintext पाएँ।
Object keys और values को एक ही pass में transform करने के लिए to_entries, map, और from_entries (या shorthand with_entries) chain करें। हर key में prefix चाहिए? with_entries(.key = "prefix_" + .key)। यह arrays के लिए map का object equivalent है।
अगर jq के error messages cryptic लगें, तो अपनी pipeline में कहीं भी debug जोड़ दें ताकि देख सकें कि उस point पर क्या flow हो रहा है। यह output disturb किए बिना stderr पर print करता है। इसे jq का console.log समझें: .[] | debug | select(.active)।