jq 1.3 is in Debian (a request to update to 1.4 has been filed)
+jq 1.4 is in Debian
Instead of running the filter for each JSON object in the input, read the entire input stream into a large array and run the filter just once.
---online-input/-I:
When the top-level input value is an array produce its elements instead of the array. This allows on-line processing of potentially very large top-level arrays’ elements.
---raw-input/-R:
With this option, if the filter’s result is a string then it will be written directly to standard output rather than being formatted as a JSON string with quotes. This can be useful for making jq filters talk to non-JSON-based systems.
--join-output / -j:
Like -r but jq won’t print a newline after each output.
-f filename / --from-file filename:
has
has(key)
The builtin function has returns whether the input object has the given key, or the input array has an element at the given index.
del
del(path_expression)
The builtin function del removes a key and its corresponding value from an object.
select
select(boolean_expression)
The function select(foo) produces its input unchanged if foo returns true for that input, and produces no output otherwise.
paths
paths, paths(node_filter), leaf_paths
Outputs the paths to all the elements in its input (except it does not output the empty list, representing . itself).
+paths outputs the paths to all the elements in its input (except it does not output the empty list, representing . itself).
paths is equivalent to
paths(f) outputs the paths to any values for which f is true. That is, paths(numbers) outputs the paths to all numeric values.
def paths: path(recurse(if (type|. == "array" or . == "object") then .[] else empty end))|select(length > 0);leaf_paths is an alias of paths(scalars); leaf_paths is deprecated and will be removed in the next major release.
leaf_paths
Outputs the paths to all the leaves (non-array, non-object elements) in its input.
- - -| jq '[leaf_paths]' | |
| jq '[paths(scalars)]' | |
| Input | [1,[[],{"a":2}]] |
| jq 'flatten' | |
| Input | [1, [2], [[3]]] |
| Output | + +[1, 2, 3] | +
| jq 'flatten(1)' | |
| Input | [1, [2], [[3]]] |
| Output | + +[1, 2, [3]] | +
| jq 'flatten' | |
| Input | [[]] |
| Output | + +[] | +
| jq 'flatten' | |
| Input | [{"foo": "bar"}, [{"foo": "baz"}]] |
| Output | + +[{"foo": "bar"}, {"foo": "baz"}] | +
range(upto), range(from;upto)
The range function produces a range of numbers. range(4;10) produces 6 numbers, from 4 (inclusive) to 10 (exclusive). The numbers are produced as separate outputs. Use [range(4;10)] to get a range as an array.
Its first argument can be omitted; it defaults to zero.
+| jq '[range(4)]' | |
| Input | null |
| Output | + +[0,1,2,3] | +
sort, sort_by
sort, sort(path_expression), sort_by(path_expression)
The sort functions sorts its input, which must be an array. Values are sorted in the following order:
The ordering for objects is a little complex: first they’re compared by comparing their sets of keys (as arrays in sorted order), and if their keys are equal then the values are compared key by key.
-sort_by may be used to sort by a particular field of an object, or by applying any jq filter. sort_by(foo) compares two elements by comparing the result of foo on each element.
sort may be used to sort by a particular field of an object, or by applying any jq filter.
sort(foo) compares two elements by comparing the result of foo on each element.
sort_by(foo) is an alias of sort(foo); sort_by() is deprecated and will be removed in the next major release.
| jq 'sort_by(.foo)' | |
| jq 'sort(.foo)' | |
| Input | [{"foo":4, "bar":10}, {"foo":3, "bar":100}, {"foo":2, "bar":1}] |
| jq 'group_by(.foo)' | |
| jq 'group(.foo)' | |
| Input | [{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}] |
| jq 'max_by(.foo)' | |
| jq 'max(.foo)' | |
| Input | [{"foo":1, "bar":14}, {"foo":2, "bar":3}] |
unique_by
The unique_by(.foo) function takes as input an array and produces an array of the same elements, in sorted order, with elqements with a duplicate .foo field removed. Think of it as making an array by taking one element out of every group produced by group_by.
| jq 'unique_by(.foo)' | |
| jq 'unique(.foo)' | |
| Input | [{"foo": 1, "bar": 2}, {"foo": 1, "bar": 3}, {"foo": 4, "bar": 5}] |
| jq 'unique_by(length)' | |
| jq 'unique(length)' | |
| Input | ["chunky", "bacon", "kitten", "cicada", "asparagus"] |
| jq 'match("(abc)+"; "g")' | |
| Input | "abc abc" |
| Output | + +{"offset": 0, "length": 3, "string": "abc", "captures": [{"offset": 0, "length": 3, "string": "abc", "name": null}]} | +
| + + | {"offset": 4, "length": 3, "string": "abc", "captures": [{"offset": 4, "length": 3, "string": "abc", "name": null}]} | +
| jq 'match("foo")' | |
| Input | "foo bar foo" |
| Output | + +{"offset": 0, "length": 3, "string": "foo", "captures": []} | +
| jq 'match(["foo", "ig"])' | |
| Input | "foo bar FOO" |
| Output | + +{"offset": 0, "length": 3, "string": "foo", "captures": []} | +
| + + | {"offset": 8, "length": 3, "string": "FOO", "captures": []} | +
| jq 'match("foo (? | |
| Input | "foo bar foo foo foo" |
| Output | + +{"offset": 0, "length": 11, "string": "foo bar foo", "captures": [{"offset": 4, "length": 3, "string": "bar", "name": "bar123"}]} | +
| + + | {"offset": 12, "length": 8, "string": "foo foo", "captures": [{"offset": -1, "length": 0, "string": null, "name": "bar123"}]} | +
test(val), test(regex), test(regex; modifiers)
Like match, but does not return match objects, only true or false for whether or not the regex matches the input.
| jq 'test("foo")' | |
| Input | "foo" |
| Output | + +true | +
| jq 'test("foo"; "i")' | |
| Input | "Foo" |
| Output | + +true | +
| jq 'test("foo")' | |
| Input | "bar" |
| Output | + +false | +
sub(re; sub), gsub(re; sub)
sub(re; sub) replaces with sub the first match of the given regexp re in its input. gsub(re; sub) replaces all matches.
scan(re), split2(re)
scan(re) outputs the substrings of its input that match the given regexp re.
split2(re) outputs the substrings of its input that don’t match the given regexp re. (Compare to split(sep), which outputs an array of substrings that don’t exactly match sep.)
ltrimstr(str)
Outputs its input with the given prefix string removed, if it starts with it.
@@ -2949,11 +3258,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and| jq 'recurse' | |
| Input | {"a":0,"b":[1]} |
| Output | + +0 | +
| + + | [1] | +
| + + | 1 | +
recurse_down
A quieter version of recurse(.[]), equivalent to:
def recurse_down: recurse(.[]?);..
Short-hand for recurse_down. This is intended to resemble the XPath // operator. Note that ..a does not work; use ..|a instead.
Short-hand for recurse without arguments. This is intended to resemble the XPath // operator. Note that ..a does not work; use ..|a instead. In the example below we use ..|.a? to find all the values of object keys “a” in any object found “below” ..
| jq 'env.PAGER' | |
| Input | null |
| Output | + +"less" | +
String interpolation - \(foo)
| jq '. as $i|[(.*2|. as $i| $i), $i]' | |
| Input | 5 |
| Output | + +[10,5] | +
def map(f): [.[] | f];Arguments are passed as filters, not as values. The same argument may be referenced multiple times with different inputs (here f is run for each element of the input array). Arguments to a function work more like callbacks than like value arguments.
Arguments are passed as filters, not as values. The same argument may be referenced multiple times with different inputs (here f is run for each element of the input array). Arguments to a function work more like callbacks than like value arguments. This is important to understand. Consider:
def foo(f): f|f;
+5|foo(.*2)The result will be 20 because f is .*2, and during the first invocation of f . will be 5, and the second time it will be 10 (5 * 2), so the result will be 20. Function arguments are filters, and filters expect an input when invoked.
If you want the value-argument behaviour for defining simple functions, you can just use a variable:
@@ -3922,14 +4311,16 @@ not.With that definition, addvalue(.foo) will add the current input’s .foo field to each element of the array.
Multiple definitions using the same function name are allowed. Each re-definition replaces the previous one for the same number of function arguments, but only for references from functions (or main program) subsequent to the re-definition.
+