JQ Cheatsheet


Input JSON used for the examples:

# The 5 latest commits of the jqlang repository on GitHub
jqlang_commits=$(curl 'https://api.github.com/repos/jqlang/jq/commits?per_page=5')

Interactive Testing

Using a tool like ijq you can interactively work on JQ expressions.

ijq demo

Building New Objects

The output of one filter can be passed to another, which can commonly be used to build a new json object from an existing one.

echo $jqlang_commits | jq '.[0] | {message: .commit.message, name: .commit.committer.name}'

If you want to do this for a whole list of objects it works almost the same. The resulting objects are by default white space separated, which is best for processing in bash.

echo $jqlang_commits | jq '.[] | {message: .commit.message, name: .commit.committer.name}'

To expression can also be wrapped in [] , which will create a proper json list as the output.

echo $jqlang_commits | jq '[.[] | {message: .commit.message, name: .commit.committer.name}]'

Wrapping As List

Wrapping multiple json objects into a list is quite easy, just pass them to jq -s.

cat my-files/*.json | jq -s

Output Configuration

  • --raw-output / -r: If the output is a string, don’t wrap it in "". Useful for further processing in non json tools like shell loops.
  • --sort-keys / -S: Output the fields of each object with the keys in sorted order.

Read Expression From File

Read the jq expression from a file instead of specifying in the command (Works similar to awk -f).

jq -f my-expression.jq
jq --from-file my-expression.jq

Array Slicing

jq can slice arrays, similar to how Python , using [n:m], where n is the inclusive start of the slice and m is the non-inclusive end of the slice.

So to grab the first 4 elements we can:

echo '["a","b","c","d","e","f"]' | jq -e '.[:4]'

Or the last 2

echo '["a","b","c","d","e","f"]' | jq -e '.[-2:]'

Turning stdout Into a List

Many command line tools provide one output item per line. If we want to process these further it can be useful to turn them into a JSON list.

find /var/www/html \
  | grep "e.html" \
  | jq -R -s 'split("\n")[:-1]'

This works by telling jq to accept raw input -R, slurp everything before processing -s, and then split it by newlines split("\n"). The final [:-1] is needed since the last element would otherwise be an empty string for the trailing newline of the output.

See also