jq is a command-line program that can transform JSON in several ways. Takes a JSON object as input and produces an output.

jq '<filter>' < db.json

Table of Contents

Parameters

  • -c: By default, jq pretty-prints JSON output. Using this option will result in a more compact output.

Selecting fields

You can select fields by typing a dot (.) and the field name.

# db.json
{"name":"john", "id":3}
$ jq '.name' < db.json
"john"

You can also select several fields.

$ jq '.name, .id' < db.json

Arrays

You can select one or several items of an array by appending [] to the field name. If you add an index inside the brackets, it will output that item (arrays are zero-based, first item has index 0). If you do not add any number, it will return all items. [0:5] will return an array with items from index 0 to 4.

# db.json
{"Items":[{"name":"john"},{"name":"tom"}]}
$ jq '.Items[0]' < db.json
{"name":"john"}

Pipes

Pipes works as in UNIX/Linux: parses the output of one filter as input to another filter. For example:

# db.json
{"Items":[{"id":1, "model":"Samsung S10"}, {"id":2, "model":"Apple iPhone 10"}]
$ jq '.Items[] | .id, .model' < db.json
1
"Samsung S10"
2
"Apple iPhone 10"

Built-in functions

  • length: return the number of items.
    jq '.Items | length' < db.json
    
  • map(<filter>): it will run <filter> for each element of an array.
    # db.json
    {"Items":[{"id":1, "model":"Samsung S10"}, {"id":2, "model":"Apple iPhone 10"}]
    
    $ jq '.Items | map(.model)' < db.json
    "Samsung S10","Apple iPhone 10"
    
    • This is almost the same as: jq '.Items[] | .model' but map returns an array.
  • has("<key>"): returns if the object has the given key.
    # db.json
    {"Items":[{"id":1, "phone":"+01234567"}, {"id":2}]
    
    $ jq 'Items[] | .id, has("phone")' < db.json
    1
    true
    2
    false
    
  • tonumber: parses its input as a number.
    # db.json
    {"id":"1"}
    
    $ jq '.id | tonumber' < db.json
    1
    
  • tostring: parses its input as a string.
  • add: takes an array and outputs the elements of the array together. If the elements are numbers, it will make a sum, if they are strings, it will concatenate them in one string.
    # db.json
    {"values": [1,2,3]}
    
    $ jq '.values | add' < db.json
    6
    
  • sort and sort_by(<filter>): sort sorts its input (must be an array). sort_by(<filter>) sorts by comparing the result of <filter>.
    # db.json
    [{"id": 3, "name":"john"}{"id":1, "name":"tom"}]
    
    $ jq 'sort_by(.id)' < db.json
    [{"id":1, "name":"tom"},{"id":3, "name":"john"}]
    
  • select(<function>): select returns the input unchanged if <function> returns true for that input.
    jq '.Items[] | select(.brand["S"] == "Nokia")' < db.json
    
  • test(<regex>): when using inside select(), returns true or false for whether or not the regex matches the input.
    jq '.Items[] | select(.model["S"] | test("Nokia*"))' < db.json
    

More info

I have shown you only the basics about jq because this awesome program has a lot of features. You can learn more on its man page (man jq).

Test with this online terminal:

If you have any suggestion, feel free to contact me via social media or email.