jq is a tool for transforming JSON inputs and generating JSON outputs. As a
programming language, jq supports boolean and arithmetic expressions, object
and array indexing; it has conditionals, functions, and even exception
handling… etc. Knowing jq enables you to easily write small programs that
can perform complex queries on JSON documents to find answers, make reports, or
to produce another JSON document for further processing by other programs.
NOTE: This guide demonstrates the use of jq from the command line, specifically, under an environment running the Bash shell.
1# When running jq from the command line, jq program code can be specified as the
2# first argument after any options to `jq`. We often quote such jq program with
3# single quotes (`'`) to prevent any special interpretation from the command line
4# shell.
5#
6jq -n '# Comments start with # until the end of line.
7 # The -n option sets the input to the value, `null`, and prevents `jq`
8 # from reading inputs from external sources.
9'
10
11# Output:
12# null
13
14
15# By default jq reads from *STDIN* a stream of JSON inputs (values). It
16# processes each input with the jq program (filters) specified at the command
17# line, and prints the outputs of processing each input with the program to
18# *STDOUT*.
19#
20echo '
21 "hello" 123 [
22 "one",
23 "two",
24 "three"
25 ]
26 { "name": "jq" }
27' |
28 jq '. # <-- the jq program here is the single dot (.), called the identity
29 # operator, which stands for the current input.
30'
31
32# Output:
33# "hello"
34# 123
35# [
36# "one",
37# "two",
38# "three"
39# ]
40# {
41# "name": "jq"
42# }
43
44
45# Notice that jq pretty-prints the outputs by default, therefore, piping
46# to `jq` is a simple way to format a response from some REST API endpoint
47# that returns JSON. E.g., `curl -s https://freegeoip.app/json/ | jq`
48
49
50# Instead of processing each JSON input with a jq program, you can also
51# ask jq to slurp them up as an array.
52#
53echo '1 "two" 3' | jq -s .
54
55# Output:
56# [
57# 1,
58# "two",
59# 3
60# ]
61
62
63# Or, treat each line as a string.
64#
65(echo line 1; echo line 2) | jq -R .
66
67# Output:
68# "line 1"
69# "line 2"
70
71
72# Or, combine -s and -R to slurp the input lines into a single string.
73#
74(echo line 1; echo line 2) | jq -sR .
75
76# Output:
77# "line 1\nline2\n"
78
79
80# Inputs can also come from a JSON file specified at the command line:
81#
82echo '"hello"' > hello.json
83jq . hello.json
84
85# Output:
86# "hello"
87
88
89# Passing a value into a jq program can be done with the `--arg` option.
90# Below, `val` is the variable name to bind the value, `123`, to.
91# The variable is then referenced as `$val`.
92#
93jq -n --arg val 123 '$val' # $val is the string "123" here
94
95# Output:
96# "123"
97
98
99# If you need to pass a JSON value, use `--argjson`
100#
101jq -n --argjson val 123 '$val' # $val is a number
102
103# Output:
104# 123
105
106
107# Using `--arg` or `--argjson` is an useful way of building JSON output from
108# existing input.
109#
110jq --arg text "$(date; echo "Have a nice day!")" -n '{ "today": $text }'
111
112# Output:
113# {
114# "today": "Sun Apr 10 09:53:07 PM EDT 2022\nHave a nice day!"
115# }
116
117
118# Instead of outputting values as JSON, you can use the `-r` option to print
119# string values unquoted / unescaped. Non-string values are still printed as
120# JSON.
121#
122echo '"hello" 2 [1, "two", null] {}' | jq -r .
123
124# Output:
125# hello
126# 2
127# [
128# 1,
129# "two",
130# null
131# ]
132# {}
133
134
135# Inside a string in jq, `\(expr)` can be used to substitute the output of
136# `expr` into the surrounding string context.
137#
138jq -rn '"1 + 2 = \(1+2)"'
139
140# Output:
141# 1 + 2 = 3
142
143
144# The `-r` option is most useful for generating text outputs to be processed
145# down in a shell pipeline, especially when combined with an interpolated
146# string that is prefixed the `@sh` prefix operator.
147#
148# The `@sh` operator escapes the outputs of `\(...)` inside a string with
149# single quotes so that each resulting string of `\(...)` can be evaluated
150# by the shell as a single word / token / argument without special
151# interpretations.
152#
153env_vars=$(
154 echo '{"var1": "value one", "var2": "value\ntwo"}' \
155 |
156 jq -r '
157 "export " + @sh "var1=\(.var1) var2=\(.var2)"
158 # ^^^^^^^^ ^^^^^^^^
159 # "'value one'" "'value\ntwo'"
160 #
161 # NOTE: The + (plus) operator here concatenates strings.
162 '
163)
164echo "$env_vars"
165eval "$env_vars"
166declare -p var1 var2
167
168# Output:
169# export var1='value one' var2='value
170# two'
171# declare -- var1="value one"
172# declare -- var2="value
173# two"
174
175# There are other string `@prefix` operators (e.g., @base64, @uri, @csv, ...)
176# that might be useful to you. See `man jq` for details.
177
178
179# The comma (`,`) operator in jq evaluates each operand and generates multiple
180# outputs:
181#
182jq -n '"one", 2, ["three"], {"four": 4}'
183
184# Output:
185# "one"
186# 2
187# [
188# "three"
189# ]
190# {
191# "four": 4
192# }
193
194
195# Any JSON value is a valid jq expression that evaluates to the JSON value
196# itself.
197#
198jq -n '1, "one", [1, 2], {"one": 1}, null, true, false'
199
200# Output:
201# 1
202# "one"
203# [
204# 1,
205# 2
206# ]
207# {
208# "one": 1
209# }
210# null
211# true
212# false
213
214
215# Any jq expression can be used where a JSON value is expected, even as object
216# keys. (though parenthesis might be required for object keys or values)
217#
218jq -n '[2*3, 8-1, 16/2], {("tw" + "o"): (1 + 1)}'
219
220# Output:
221# [
222# 6,
223# 7,
224# 8
225# ]
226# {
227# "two": 2
228# }
229
230
231# As a shortcut, if a JSON object key looks like a valid identifier (matching
232# the regex `^[a-zA-Z_][a-zA-Z_0-9]*$`), quotes can be omitted.
233#
234jq -n '{ key_1: "value1" }'
235
236# If a JSON object's key's value is omitted, it is looked up in the current
237# input using the key: (see next example for the meaning of `... | ...`)
238#
239jq -n '{c: 3} | {a: 1, "b", c}'
240
241# Output:
242# {
243# "a": 1,
244# "b": null,
245# "c": 3
246# }
247
248
249# jq programs are more commonly written as a series of expressions (filters)
250# connected by the pipe (`|`) operator, which makes the output of its left
251# filter the input to its right filter.
252#
253jq -n '1 | . + 2 | . + 3' # first dot is 1; second dot is 3
254
255# Output:
256# 6
257
258# If an expression evaluates to multiple outputs, then jq will iterate through
259# them and propagate each output down the pipeline, and generate multiple
260# outputs in the end.
261#
262jq -n '1, 2, 3 | ., 4 | .'
263
264# Output:
265# 1
266# 4
267# 2
268# 4
269# 3
270# 4
271
272# The flows of the data in the last example can be visualized like this:
273# (number prefixed with `*` indicates the current output)
274#
275# *1, 2, 3 | *1, 4 | *1
276# 1, 2, 3 | 1, *4 | *4
277# 1, *2, 3 | *2, 4 | *2
278# 1, 2, 3 | 2, *4 | *4
279# 1, 2, *3 | *3, 4 | *3
280# 1, 2, 3 | 3, *4 | *4
281#
282#
283# To put it another way, the evaluation of the above example is very similar
284# to the following pieces of code in other programming languages:
285#
286# In Python:
287#
288# for first_dot in 1, 2, 3:
289# for second_dot in first_dot, 4:
290# print(second_dot)
291#
292# In Ruby:
293#
294# [1, 2, 3].each do |dot|
295# [dot, 4].each { |dot| puts dot }
296# end
297#
298# In JavaScript:
299#
300# [1, 2, 3].forEach(dot => {
301# [dot, 4].forEach(dot => console.log(dot))
302# })
303#
304
305
306# Below are some examples of array index and object attribute lookups using
307# the `[expr]` operator after an expression. If `expr` is a number then it's
308# an array index lookup; otherwise, it should be a string, in which case it's
309# an object attribute lookup:
310
311# Array index lookup
312#
313jq -n '[2, {"four": 4}, 6][1 - 1]' # => 2
314jq -n '[2, {"four": 4}, 6][0]' # => 2
315jq -n '[2, {"four": 4}, 6] | .[0]' # => 2
316
317# You can chain the lookups since they are just expressions.
318#
319jq -n '[2, {"four": 4}, 6][1]["fo" + "ur"]' # => 4
320
321# For object attributes, you can also use the `.key` shortcut.
322#
323jq -n '[2, {"four": 4}, 6][1].four' # => 4
324
325# Use `."key"` if the key is not a valid identifier.
326#
327jq -n '[2, {"f o u r": 4}, 6][1]."f o u r"' # => 4
328
329# Array index lookup returns null if the index is not found.
330#
331jq -n '[2, {"four": 4}, 6][99]' # => null
332
333# Object attribute lookup returns null if the key is not found.
334#
335jq -n '[2, {"four": 4}, 6][1].whatever' # => null
336
337# The alternative operator `//` can be used to provide a default
338# value when the result of the left operand is either `null` or `false`.
339#
340jq -n '.unknown_key // 7' # => 7
341
342# If the thing before the lookup operator (`[expr]`) is neither an array
343# or an object, then you will get an error:
344#
345jq -n '123 | .[0]' # => jq: error (at <unknown>): Cannot index number with number
346jq -n '"abc" | .name' # => jq: error (at <unknown>): Cannot index string with string "name"
347jq -n '{"a": 97} | .[0]' # => jq: error (at <unknown>): Cannot index object with number
348jq -n '[89, 64] | .["key"]' # => jq: error (at <unknown>): Cannot index array with string "key"
349
350# You can, however, append a `?` to a lookup to make jq return `empty`
351# instead when such error happens.
352#
353jq -n '123 | .[0]?' # no output since it's empty.
354jq -n '"abc" | .name?' # no output since it's empty.
355
356# The alternative operator (`//`) also works with `empty`:
357#
358jq -n '123 | .[0]? // 99' # => 99
359jq -n '"abc" | .name? // "unknown"' # => "unknown"
360
361# NOTE: `empty` is actually a built-in function in jq.
362# With the nested loop explanation we illustrated earlier before,
363# `empty` is like the `continue` or the `next` keyword that skips
364# the current iteration of the loop in some programming languages.
365
366
367# Strings and arrays can be sliced with the same syntax (`[i:j]`, but no
368# stepping) and semantic as found in the Python programming language:
369#
370# 0 1 2 3 4 5 ... infinite
371# array = ["a", "b", "c", "d"]
372# -infinite ... -4 -3 -2 -1
373#
374jq -n '["Peter", "Jerry"][1]' # => "Jerry"
375jq -n '["Peter", "Jerry"][-1]' # => "Jerry"
376jq -n '["Peter", "Jerry", "Tom"][1:]' # => ["Jerry", "Tom"]
377jq -n '["Peter", "Jerry", "Tom"][:1+1]' # => ["Peter", "Jerry"]
378jq -n '["Peter", "Jerry", "Tom"][1:99]' # => ["Jerry", "Tom"]
379
380
381# If the lookup index or key is omitted then jq iterates through
382# the collection, generating one output value from each iteration.
383#
384# These examples produce the same outputs.
385#
386echo 1 2 3 | jq .
387jq -n '1, 2, 3'
388jq -n '[1, 2, 3][]'
389jq -n '{a: 1, b: 2, c: 3}[]'
390
391# Output:
392# 1
393# 2
394# 3
395
396
397# You can build an array out of multiple outputs.
398#
399jq -n '{values: [{a: 1, b: 2, c: 3}[] | . * 2]}'
400
401# Output:
402# {
403# "values": [
404# 2,
405# 4,
406# 6
407# ]
408# }
409
410
411# If multiple outputs are not contained, then we'd get multiple outputs
412# in the end.
413#
414jq -n '{values: ({a: 1, b: 2, c: 3}[] | . * 2)}'
415
416# Output:
417# {
418# "values": 2
419# }
420# {
421# "values": 4
422# }
423# {
424# "values": 6
425# }
426
427
428# Conditional `if ... then ... else ... end` in jq is an expression, so
429# both the `then` part and the `else` part are required. In jq, only
430# two values, `null` and `false`, are false; all other values are true.
431#
432jq -n 'if 1 > 2 | not and 1 <= 2 then "Makes sense" else "WAT?!" end'
433
434# Output
435# "Makes sense"
436
437# Notice that `not` is a built-in function that takes zero arguments,
438# that's why it's used as a filter to negate its input value.
439# We'll talk about functions soon.
440
441# Another example using a conditional:
442#
443jq -n '1, 2, 3, 4, 5 | if . % 2 != 0 then . else empty end'
444
445# Output
446# 1
447# 3
448# 5
449
450# The `empty` above is a built-in function that takes 0 arguments and
451# generates no outputs. Let's see more examples of built-in functions.
452
453# The above conditional example can be written using the `select/1` built-in
454# function (`/1` indicates the number of arguments expected by the function).
455#
456jq -n '1, 2, 3, 4, 5 | select(. % 2 != 0)' # NOTE: % gives the remainder.
457
458# Output
459# 1
460# 3
461# 5
462
463
464# Function arguments in jq are passed with call-by-name semantic, which
465# means, an argument is not evaluated at call site, but instead, is
466# treated as a lambda expression with the calling context of the call
467# site as its scope for variable and function references used in the
468# expression.
469#
470# In the above example, the expression `. % 2 != 0` is what's passed to
471# `select/1` as the argument, not `true` or `false`, which is what would
472# have been the case had the (boolean) expression was evaluated before it's
473# passed to the function.
474
475
476# The `range/1`, `range/2`, and `range/3` built-in functions generate
477# integers within a given range.
478#
479jq -n '[range(3)]' # => [0, 1, 2]
480jq -n '[range(0; 4)]' # => [0, 1, 2, 3]
481jq -n '[range(2; 10; 2)]' # => [2, 4, 6, 8]
482
483# Notice that `;` (semicolon) is used to separate function arguments.
484
485
486# The `map/1` function applies a given expression to each element of
487# the current input (array) and outputs a new array.
488#
489jq -n '[range(1; 6) | select(. % 2 != 0)] | map(. * 2)'
490
491# Output:
492# [
493# 2,
494# 6,
495# 10
496# ]
497
498# Without using `select/1` and `map/1`, we could have also written the
499# above example like this:
500#
501jq -n '[range(1; 6) | if . % 2 != 0 then . else empty end | . * 2]'
502
503
504# `keys/0` returns an array of keys of the current input. For an object,
505# these are the object's attribute names; for an array, these are the
506# array indices.
507#
508jq -n '[range(2; 10; 2)] | keys' # => [0, 1, 2, 3]
509jq -n '{a: 1, b: 2, c: 3} | keys' # => ["a", "b", "c"]
510
511# `values/0` returns an array of values of the current input. For an object,
512# these are the object's attribute values; for an array, these are the
513# elements of the array.
514#
515jq -n '[range(2; 10; 2)] | values' # => [2, 4, 6, 8]
516jq -n '{a: 1, b: 2, c: 3} | values' # => [1, 2, 3]
517
518
519# `to_entries/0` returns an array of key-value objects of the current input
520# object.
521#
522jq -n '{a: 1, b: 2, c: 3} | to_entries'
523
524# Output:
525# [
526# {
527# "key": "a",
528# "value": 1
529# },
530# {
531# "key": "b",
532# "value": 2
533# },
534# {
535# "key": "c",
536# "value": 3
537# }
538# ]
539
540
541# Here's how you can turn an object's attribute into environment variables
542# using what we have learned so far.
543#
544env_vars=$(
545 jq -rn '{var1: "1 2 3 4", var2: "line1\nline2\n"}
546 | to_entries[]
547 | "export " + @sh "\(.key)=\(.value)"
548 '
549)
550eval "$env_vars"
551declare -p var1 var2
552
553# Output:
554# declare -x var1="1 2 3 4"
555# declare -x var2="line1
556# line2
557# "
558
559
560# `from_entries/0` is the opposite of `to_entries/0` in that it takes an
561# an array of key-value objects and turn that into an object with keys
562# and values from the `key` and `value` attributes of the objects.
563#
564# It's useful together with `to_entries/0` when you need to iterate and
565# do something to each attribute of an object.
566#
567jq -n '{a: 1, b: 2, c: 3} | to_entries | map(.value *= 2) | from_entries'
568
569# Output:
570# {
571# "a": 2,
572# "b": 4,
573# "c": 6
574# }
575
576
577# The example above can be further shortened with the `with_entries/1` built-in:
578#
579jq -n '{a: 1, b: 2, c: 3} | with_entries(.value *= 2)'
580
581
582# The `group_by/1` generates an array of groups (arrays) from the current
583# input (array). The classification is done by applying the expression argument
584# to each member of the input array.
585#
586# Let's look at a contrived example (Note that `tostring`, `tonumber`,
587# `length` and `max` are all built-in jq functions. Feel free to look
588# them up in the jq manual):
589#
590# Generate some random numbers.
591numbers=$(echo $RANDOM{,,,,,,,,,,,,,,,,,,,,})
592#
593# Feed the numbers to jq, classifying them into groups and calculating their
594# averages, and finally generate a report.
595#
596echo $numbers | jq -rs ' # Slurp the numbers into an array.
597[
598 [ map(tostring) # Turn it into an array of strings.
599 | group_by(.[0:1]) # Group the numbers by their first digits.
600 | .[] # Iterate through the array of arrays (groups).
601 | map(tonumber) # Turn each group back to an array of numbers.
602 ] # Finally, contain all groups in an array.
603
604 | sort_by([length, max]) # Sort the groups by their sizes.
605 # If two groups have the same size then the one with the largest
606 # number wins (is bigger).
607
608 | to_entries[] # Enumerate the array, generating key-value objects.
609 | # For each object, generate two lines:
610 "Group \(.key): \(.value | sort | join(" "))" + "\n" +
611 "Average: \( .value | (add / length) )"
612
613] # Contain the group+average lines in an array.
614 # Join the array elements by separator lines (dashes) to produce the report.
615| join("\n" + "-"*78 + "\n")
616'
617
618# Output:
619#
620# Group 0: 3267
621# Average: 3267
622# ------------------------------------------------------------------------------
623# Group 1: 7854
624# Average: 7854
625# ------------------------------------------------------------------------------
626# Group 2: 4415 4447
627# Average: 4431
628# ------------------------------------------------------------------------------
629# Group 3: 681 6426
630# Average: 3553.5
631# ------------------------------------------------------------------------------
632# Group 4: 21263 21361 21801 21832 22947 23523 29174
633# Average: 23128.714285714286
634# ------------------------------------------------------------------------------
635# Group 5: 10373 12698 13132 13924 17444 17963 18934 18979
636# Average: 15430.875
637
638
639# The `add/1` built-in "reduces" an array of values to a single value.
640# You can think of it as sticking the `+` operator in between each value of
641# the collection. Here are some examples:
642#
643jq -n '[1, 2, 3, 4, 5] | add' # => 15
644jq -n '["a", "b", "c"] | add' # => "abc"
645
646# `+` concatenates arrays
647jq -n '[["a"], ["b"], ["c"]] | add'
648
649# Output:
650# [
651# "a",
652# "b",
653# "c"
654# ]
655
656# `+` merges objects non-recursively.
657jq -n '[{a: 1, b: {c: 3}}, {b: 2, c: 4}] | add'
658
659# Output:
660# {
661# "a": 1,
662# "b": 2,
663# "c": 4
664# }
665
666
667# jq provides a special syntax for writing an expression that reduces
668# the outputs generated by a given expression to a single value.
669# It has this form:
670#
671# reduce outputs_expr as $var (initial_value; reduction_expr)
672#
673# Examples:
674#
675jq -n 'reduce range(1; 6) as $i (0; . + $i)' # => 15
676jq -n 'reduce (1, 2, 3, 4, 5) as $i (0; . + $i)' # => 15
677jq -n '[1, 2, 3, 4, 5] | reduce .[] as $i (0; . + $i)' # => 15
678jq -n '["a", "b", "c"] | reduce .[] as $i (""; . + $i)' # => "abc"
679
680# Notice the `.` in the `reduction_expr` is the `initial_value` at first,
681# and then it becomes the result of applying the `reduction_expr` as
682# we iterate through the values of `outputs_expr`. The expression:
683#
684# reduce (1, 2, 3, 4, 5) as $i (0; . + $i)
685#
686# can be thought of as doing:
687#
688# 0 + 1 | . + 2 | . + 3 | . + 4 | . + 5
689#
690
691
692# The `*` operator when used on two objects, merges both recursively.
693# Therefore, to merge JSON objects recursively, you can use `reduce`
694# with the `*` operator. For example:
695#
696echo '
697 {"a": 1, "b": {"c": 3}}
698 { "b": {"d": 4}}
699 {"a": 99, "e": 5 }
700' | jq -s 'reduce .[] as $m ({}; . * $m)'
701
702# Output:
703# {
704# "a": 99,
705# "b": {
706# "c": 3,
707# "d": 4
708# },
709# "e": 5
710# }
711
712
713# jq has variable assignment in the form of `expr as $var`, which binds
714# the value of `expr` to `$var`, and `$var` is immutable. Further more,
715# `... as ...` doesn't change the input of the next filter; its introduction
716# in a filter pipeline is only for establishing the binding of a value to a
717# variable, and its scope extends to the filters following its definition.
718# (i.e., to look up a variable's definition, scan to the left of the filter
719# chain from the expression using it until you find the definition)
720#
721jq -rn '[1, 2, 3, 4, 5]
722 | (.[0] + .[-1]) as $sum # Always put ( ) around the binding `expr` to avoid surprises.
723 | ($sum * length / 2) as $result # The current input at this step is still the initial array.
724 | "The result is: \($result)" # Same.
725'
726
727# Output:
728# The result is: 15
729
730
731# With the `expr as $var` form, if multiple values are generated by `expr`
732# then jq will iterate through them and bind each value to `$var` in turn
733# for the rest of the pipeline.
734#
735jq -rn 'range(2; 4) as $i
736 | range(1; 6) as $j
737 | "\($i) * \($j) = \($i * $j)"
738'
739
740# Output:
741# 2 * 1 = 2
742# 2 * 2 = 4
743# 2 * 3 = 6
744# 2 * 4 = 8
745# 2 * 5 = 10
746# 3 * 1 = 3
747# 3 * 2 = 6
748# 3 * 3 = 9
749# 3 * 4 = 12
750# 3 * 5 = 15
751
752
753# It's sometimes useful to bind the initial input to a variable at the
754# start of a program, so that you can refer to it later down the pipeline.
755#
756jq -rn "$(cat <<'EOF'
757 {lookup: {a: 1, b: 2, c: 3},
758 bonuses: {a: 5, b: 2, c: 9}
759 }
760 | . as $doc
761 | .bonuses
762 | to_entries[]
763 | "\(.key)'s total is \($doc.lookup[.key] + .value)"
764EOF
765)"
766
767# Output:
768# a's total is 6
769# b's total is 4
770# c's total is 12
771
772
773# jq supports destructing during variable binding. This lets you extract values
774# from an array or an object and bind them to variables.
775#
776jq -n '[range(5)] | . as [$first, $second] | $second'
777
778# Output:
779# 1
780
781jq -n '{ name: "Tom", numbers: [1, 2, 3], age: 32}
782 | . as {
783 name: $who, # bind .name to $who
784 $name, # shorthand for `name: $name`
785 numbers: [$first, $second],
786 }
787 | $name, $second, $first, $who
788'
789
790# Output:
791# "Tom"
792# 2
793# 1
794# "Tom"
795
796
797# In jq, values can be assigned to an array index or object key via the
798# assignment operator, `=`. The same current input is given to both sides
799# of the assignment operator, and the assignment itself evaluates to the
800# current input. In other words, the assignment expression is evaluated
801# for its side effect, and doesn't generate a new output.
802#
803jq -n '.a = 1 | .b = .a + 1' # => {"a": 1, "b": 2}
804
805# Note that input is `null` due to `jq -n`, so `.` is `null` in the first
806# filter, and assigning to a key under `null` turns it into an object with
807# the key. The same input (now an object) then gets piped to the next filter,
808# which then sets the `b` key to the value of the `a` key plus `1`, which is `2`.
809#
810
811# Another example:
812#
813jq -n '.a=1, .a.b=2' # => {"a": 1} {"a": {"b": 2}}
814
815# In the above example, two objects are generated because both assignments
816# received `null` as their inputs, and each operand of the comma operator
817# is evaluated independently. Notice also how you can easily generate
818# nested objects.
819
820
821# In addition to the assignment operator, jq also has operators like:
822# `+=`, `-=`, `*=`, and '/=', ... etc. Basically, `a op= b` is a shorthand
823# for `a = a op b`, and they are handy for updating an object attribute or
824# an item in an array based on its current value. Examples:
825#
826jq -n '.a.b.c = 3 | .a.b.c = .a.b.c + 1' # => {"a": {"b": {"c": 4}}}
827jq -n '.a.b.c = 3 | .a.b.c += 1' # => {"a": {"b": {"c": 4}}}
828
829
830# To delete a value, use `del/1`, which takes a path expression that specifies
831# the locations of the things to be deleted. Example:
832#
833jq -n '{a: 1, b: {c: 2}, d: [3, 4, 5]} | del(.b.c, .d[1]) | .b.x = 6'
834
835# Output:
836# {
837# "a": 1,
838# "b": {
839# "x": 6
840# },
841# "d": [
842# 3,
843# 5
844# ]
845# }
846
847
848# Other than using jq's built-in functions, you can define your own.
849# In fact, many built-in functions are defined using jq (see the link
850# to jq's built-in functions at the end of the doc).
851#
852jq -n '
853 def my_select(expr): if expr then . else empty end;
854 def my_map(expr): [.[] | expr];
855 def sum: reduce .[] as $x (0; . + $x);
856 def my_range($from; $to):
857 if $from >= $to then
858 empty
859 else
860 $from, my_range($from + 1; $to)
861 end
862 ;
863 [my_range(1; 6)] | my_map(my_select(. % 2 != 0)) | sum
864'
865
866# Output:
867# 9
868
869# Some notes about function definitions:
870#
871# - Functions are usually defined at the beginning, so that they are available
872# to the rest of the jq program.
873#
874# - Each function definition should end with a `;` (semicolon).
875#
876# - It's also possible to define a function within another, though it's not shown here.
877#
878# - Function parameters are separated by `;` (semicolon). This is consistent with
879# passing multiple arguments when calling a function.
880#
881# - A function can call itself; in fact, jq has TCO (Tail Call Optimization).
882#
883# - `def f($a; $b): ...;` is a shorthand for: `def f(a; b): a as $a | b as $b | ...`