liminfo

jq Reference

Free reference guide: jq Reference

32 results

About jq Reference

The jq Reference is a comprehensive, searchable cheat sheet for the jq command-line JSON processor. jq is a lightweight and flexible tool that lets you slice, filter, map, and transform JSON data from the command line or in shell scripts, and it is commonly used with APIs, log analysis, Kubernetes and cloud CLI output, and CI/CD pipelines. This reference is organized into six categories: Basic Filters (identity ., field access .key and .key1.key2, optional access .key?, array iterator .[], index access .[n], slicing .[n:m], pipe |, and comma ,), Types (type, length, keys, values, to_entries/from_entries), Conditions (select(), if-then-else, alternative operator //, logical operators not/and/or), Strings (test() regex, split/join, ascii_downcase/ascii_upcase, ltrimstr/rtrimstr), Arrays (map(), sort/sort_by(), group_by(), unique/unique_by, flatten), and Advanced (reduce, variable binding $var, function definition def, @base64/@base64d, env).

This reference is aimed at DevOps engineers, backend developers, data engineers, and system administrators who regularly process JSON data at the command line. The shell command format of every example (using echo and pipe) means you can paste each example directly into your terminal and see the output immediately. This is especially useful when you need to quickly remember the exact syntax for operators like to_entries, group_by, or reduce that are powerful but easy to forget.

The six-category structure follows a progression from basic to advanced. Most daily jq usage involves the Basic Filters and Conditions categories — selecting fields from API responses, filtering arrays with select(), and branching on values with if-then-else. The Arrays and Advanced categories cover power-user features: sorting and grouping JSON data, accumulating values with reduce, defining reusable functions, and encoding to/from Base64.

Key Features

  • Identity filter ., field access .key/.key1.key2, and safe optional access .key? with null fallback
  • Array and object iteration with .[] and index/slice access .[n] and .[n:m]
  • Pipe | and comma , operators for chaining and producing multiple outputs
  • select(expr) for filtering with conditions, and the alternative operator // for null fallbacks
  • if-then-else and logical operators not, and, or for complex conditional logic
  • map(), sort_by(), group_by(), unique_by(), and flatten for array transformation
  • reduce with accumulator pattern and variable binding with $var for stateful filters
  • @base64 and @base64d format strings for encoding and decoding data inline

Frequently Asked Questions

What does the jq identity filter . do?

The identity filter . takes the input and outputs it unchanged. It is most useful for pretty-printing JSON (echo '{"a":1}' | jq '.') which formats minified JSON with indentation and color. It is also used as a placeholder in pipelines where a step is expected but no transformation is needed.

How do I access nested fields in jq?

Chain field access operators: .a.b accesses the b field inside the a object. You can also use .["key"] for keys containing special characters. If a field might not exist, use .key? to return null instead of throwing an error. For deeply nested structures, each level is separated by a dot.

How does the select() function work?

select(expr) passes through values for which the expression evaluates to true and suppresses values for which it evaluates to false. Typically used after .[] to filter elements: .[] | select(. > 3) iterates an array and outputs only elements greater than 3. The expression can include comparisons, type checks, and string tests.

What is the difference between map() and .[] | in jq?

.[] | expr evaluates expr on each element and produces separate output values. map(expr) does the same but wraps the results back in an array, making it easier to pass to further array operations. Use map() when you want to transform an array and keep it as an array.

How do I use reduce in jq?

reduce .[] as $x (initial; accumulator_expr) iterates over the input array. $x is each element, the second argument is the initial accumulator value, and the expression after the semicolon updates the accumulator. For example, reduce .[] as $x (0; . + $x) sums all numbers in an array.

What does to_entries do and when is it useful?

to_entries converts an object to an array of {key, value} pairs. This is useful when you need to iterate over object entries (since .[] only gives values, not keys), transform key names, or filter entries by key. from_entries reverses the transformation, converting the array back to an object.

How do I define a reusable function in jq?

Use def functionname: expression; before your main filter. For example, def double: . * 2; [1,2,3] | map(double) defines a function and then uses it. Functions are local to the filter expression. For complex scripts, you can define multiple functions and pass arguments using def funcname(arg): expression;.

How do I encode and decode Base64 in jq?

@base64 converts a string to its Base64 encoding. @base64d decodes a Base64 string back to a plain string. These format strings work in string interpolation too: @base64 | @json produces a JSON-encoded Base64 string. They are useful for working with APIs that send binary data as Base64.