Skip to content

Instantly share code, notes, and snippets.

@olih

olih/jq-cheetsheet.md

Last active October 19, 2025 15:40
Show Gist options
  • Save olih/f7437fb6962fb3ee9fe95bda8d2c8fa4 to your computer and use it in GitHub Desktop.
Save olih/f7437fb6962fb3ee9fe95bda8d2c8fa4 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. olih revised this gist Oct 18, 2016. 1 changed file with 6 additions and 0 deletions.
    6 changes: 6 additions & 0 deletions jq-cheetsheet.md
    View file
    Original file line number Diff line number Diff line change
    @@ -48,6 +48,12 @@ The syntax for jq is pretty coherent:
    | Delete a key| `jq 'del(.foo)'` |
    | Convert an object to array | `to_entries | map([.key, .value])` |

    ## Dealing with fields

    | Description | Command |
    | ------------| :-----: |
    | Concatenate two fields| `fieldNew=.field1+' '+.field2` |


    ## Dealing with json arrays

  2. olih revised this gist Sep 30, 2016. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion jq-cheetsheet.md
    View file
    Original file line number Diff line number Diff line change
    @@ -46,7 +46,7 @@ The syntax for jq is pretty coherent:
    | Display all keys | `jq 'keys'` |
    | Adds + 1 to all items | `jq 'map_values(.+1)'` |
    | Delete a key| `jq 'del(.foo)'` |
    | Convert an object to array | `to_entries| map([.key, .value])` |
    | Convert an object to array | `to_entries | map([.key, .value])` |


    ## Dealing with json arrays
  3. olih revised this gist Sep 30, 2016. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions jq-cheetsheet.md
    View file
    Original file line number Diff line number Diff line change
    @@ -46,6 +46,7 @@ The syntax for jq is pretty coherent:
    | Display all keys | `jq 'keys'` |
    | Adds + 1 to all items | `jq 'map_values(.+1)'` |
    | Delete a key| `jq 'del(.foo)'` |
    | Convert an object to array | `to_entries| map([.key, .value])` |


    ## Dealing with json arrays
  4. olih revised this gist Apr 7, 2016. 1 changed file with 81 additions and 51 deletions.
    132 changes: 81 additions & 51 deletions jq-cheetsheet.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,52 +1,82 @@
    # Processing JSON with JQ:

    | Tables | Are | Cool |
    | ------------- |:-------------:| -----:|
    | col 3 is | right-aligned | $1600 |
    | col 2 is | centered | $12 |
    | zebra stripes | are neat | $1 |

    | Tables | Cool |
    | ------------- | :-----:|
    | --version| Output the jq version and exit with zero. |
    |--sort-keys | Output the fields of each object with the keys in sorted order.|

    | , | If two filters are separated by a comma, then the input will be fed into both and there will be multiple outputs |
    | ? | Ignores error if unexpected type |
    | [] | Arrya construction |
    # Processing JSON using jq

    jq is useful to slice, filter, map and transform structured json data.

    ## Installing jq

    ### On Mac OS

    `brew install jq`

    ### On AWS Linux

    Not available as yum install on our current AMI. It should be on the latest AMI though: https://aws.amazon.com/amazon-linux-ami/2015.09-release-notes/

    Installing from the source proved to be tricky.

    ## Useful arguments

    When running jq, the following arguments may become handy:

    | Argument | Description |
    | ----------------| :------------:|
    | `--version`| Output the jq version and exit with zero. |
    | `--sort-keys` | Output the fields of each object with the keys in sorted order.|

    ## Basic concepts

    The syntax for jq is pretty coherent:

    | Syntax | Description |
    | --------| :------------:|
    | , | Filters separated by a comma will produce multiple independent outputs|
    | ? | Will ignores error if the type is unexpected |
    | [] | Array construction |
    | {} | Object construction |
    | + | concatenate or add |
    | - | difference of set or substract |
    | length | size of selected element |

    # From Object

    | Keys | jq 'keys' |
    | Adds + 1 to all items | jq 'map_values(.+1)' |
    | Delete key| jq 'del(.foo)' |


    # From Array

    || Action || Command ||
    | All | jq .[] |
    | First | jq '.[0]' |
    | Range | jq '.[2:4]' |
    | First 3 | jq '.[:3]' |
    | Last 2 | jq '.[-2:]' |
    | Before Last | jq '.[-2]'|
    | Add + 1 to all items | jq 'map(.+1)' |
    | Delete 2 items| jq 'del(.[1, 2])' |
    | Select array of objects | jq '.[] | select(.id == "second")' |
    | Select array of int | jq 'map(select(. >= 2))' |
    | Select by type | jq '.[]|numbers' or arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars |
    | Concatenate array | jq 'add' |
    | Flatten an array | jq 'flatten' |
    | Create a range of number | jq '[range(2;4)]' |
    | Display type of each item| jq 'map(type)' |
    | Sort an array of basic type| jq 'sort' |
    | Sorts an array of objects | jq 'sort_by(.foo)' |
    | Group by a key - opposite to flatten | jq 'group_by(.foo)' |
    | Minimun of an array| jq 'min' .See also min, max, min_by(path_exp), max_by(path_exp) |
    | Removes duplicates| jq 'unique' ; jq 'unique_by(.foo)'; jq 'unique_by(length)' |
    | Reverse an array | jq 'reverse' |
    | + | Concatenate or Add |
    | - | Difference of sets or Substract |
    | length | Size of selected element |
    | | | Pipes are used to chain commands in a similar fashion than bash|


    ## Dealing with json objects

    | Description | Command |
    | ------------| :-----: |
    | Display all keys | `jq 'keys'` |
    | Adds + 1 to all items | `jq 'map_values(.+1)'` |
    | Delete a key| `jq 'del(.foo)'` |


    ## Dealing with json arrays

    ### Slicing and Filtering

    | Description | Command |
    | ------------| :-----: |
    | All | `jq .[]` |
    | First | `jq '.[0]'` |
    | Range | `jq '.[2:4]'` |
    | First 3 | `jq '.[:3]'` |
    | Last 2 | `jq '.[-2:]'` |
    | Before Last | `jq '.[-2]'`|
    | Select array of int by value | `jq 'map(select(. >= 2))'` |
    | Select array of objects by value| ** jq '.[] | select(.id == "second")'** |
    | Select by type | ** jq '.[] | numbers' ** with type been arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars |

    ### Mapping and Transforming

    | Description | Command |
    | ------------| :-----: |
    | Add + 1 to all items | `jq 'map(.+1)'` |
    | Delete 2 items| `jq 'del(.[1, 2])'` |
    | Concatenate arrays | `jq 'add'` |
    | Flatten an array | `jq 'flatten'` |
    | Create a range of numbers | `jq '[range(2;4)]'` |
    | Display the type of each item| `jq 'map(type)'` |
    | Sort an array of basic type| `jq 'sort'` |
    | Sort an array of objects | `jq 'sort_by(.foo)'` |
    | Group by a key - opposite to flatten | `jq 'group_by(.foo)'` |
    | Minimun value of an array| `jq 'min'` .See also min, max, min_by(path_exp), max_by(path_exp) |
    | Remove duplicates| `jq 'unique'` or `jq 'unique_by(.foo)'` or `jq 'unique_by(length)'` |
    | Reverse an array | `jq 'reverse'` |
  5. olih revised this gist Apr 7, 2016. 1 changed file with 2 additions and 0 deletions.
    2 changes: 2 additions & 0 deletions jq-cheetsheet.md
    View file
    Original file line number Diff line number Diff line change
    @@ -6,6 +6,8 @@
    | col 2 is | centered | $12 |
    | zebra stripes | are neat | $1 |

    | Tables | Cool |
    | ------------- | :-----:|
    | --version| Output the jq version and exit with zero. |
    |--sort-keys | Output the fields of each object with the keys in sorted order.|

  6. olih revised this gist Apr 6, 2016. No changes.
  7. olih revised this gist Apr 6, 2016. 1 changed file with 6 additions and 0 deletions.
    6 changes: 6 additions & 0 deletions jq-cheetsheet.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,11 @@
    # Processing JSON with JQ:

    | Tables | Are | Cool |
    | ------------- |:-------------:| -----:|
    | col 3 is | right-aligned | $1600 |
    | col 2 is | centered | $12 |
    | zebra stripes | are neat | $1 |

    | --version| Output the jq version and exit with zero. |
    |--sort-keys | Output the fields of each object with the keys in sorted order.|

  8. olih revised this gist Apr 6, 2016. 1 changed file with 32 additions and 31 deletions.
    63 changes: 32 additions & 31 deletions jq-cheetsheet.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,43 +1,44 @@
    # Processing JSON with JQ:

    | --version| Output the jq version and exit with zero. |
    |--sort-keys |Output the fields of each object with the keys in sorted order.|
    |--sort-keys | Output the fields of each object with the keys in sorted order.|

    , | If two filters are separated by a comma, then the input will be fed into both and there will be multiple outputs
    ? | Ignores error if unexpected type
    [] | Arrya construction
    {} | Object construction
    + | concatenate or add
    - | difference of set or substract
    length | size of selected element
    | , | If two filters are separated by a comma, then the input will be fed into both and there will be multiple outputs |
    | ? | Ignores error if unexpected type |
    | [] | Arrya construction |
    | {} | Object construction |
    | + | concatenate or add |
    | - | difference of set or substract |
    | length | size of selected element |

    # From Object

    Keys | jq 'keys'
    Adds + 1 to all items | jq 'map_values(.+1)'
    Delete key| jq 'del(.foo)'
    | Keys | jq 'keys' |
    | Adds + 1 to all items | jq 'map_values(.+1)' |
    | Delete key| jq 'del(.foo)' |


    # From Array

    || Action || Command ||
    | All | jq .[] |
    First | jq '.[0]'
    Range | jq '.[2:4]'
    First 3 | jq '.[:3]'
    Last 2 | jq '.[-2:]'
    Before Last | jq '.[-2]'
    Add + 1 to all items | jq 'map(.+1)'
    Delete 2 items| jq 'del(.[1, 2])'
    Select array of objects | jq '.[] | select(.id == "second")'
    Select array of int | jq 'map(select(. >= 2))'
    Select by type | jq '.[]|numbers' or arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars
    Concatenate array | jq 'add'
    Flatten an array | jq 'flatten'
    Create a range of number | jq '[range(2;4)]'
    Display type of each item| jq 'map(type)'
    Sort an array of basic type| jq 'sort'
    Sorts an array of objects | jq 'sort_by(.foo)'
    Group by a key - opposite to flatten | jq 'group_by(.foo)'
    Minimun of an array| jq 'min' .See also min, max, min_by(path_exp), max_by(path_exp)
    Removes duplicates| jq 'unique' ; jq 'unique_by(.foo)'; jq 'unique_by(length)'
    Reverse an array | jq 'reverse'
    | First | jq '.[0]' |
    | Range | jq '.[2:4]' |
    | First 3 | jq '.[:3]' |
    | Last 2 | jq '.[-2:]' |
    | Before Last | jq '.[-2]'|
    | Add + 1 to all items | jq 'map(.+1)' |
    | Delete 2 items| jq 'del(.[1, 2])' |
    | Select array of objects | jq '.[] | select(.id == "second")' |
    | Select array of int | jq 'map(select(. >= 2))' |
    | Select by type | jq '.[]|numbers' or arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars |
    | Concatenate array | jq 'add' |
    | Flatten an array | jq 'flatten' |
    | Create a range of number | jq '[range(2;4)]' |
    | Display type of each item| jq 'map(type)' |
    | Sort an array of basic type| jq 'sort' |
    | Sorts an array of objects | jq 'sort_by(.foo)' |
    | Group by a key - opposite to flatten | jq 'group_by(.foo)' |
    | Minimun of an array| jq 'min' .See also min, max, min_by(path_exp), max_by(path_exp) |
    | Removes duplicates| jq 'unique' ; jq 'unique_by(.foo)'; jq 'unique_by(length)' |
    | Reverse an array | jq 'reverse' |
  9. olih created this gist Apr 6, 2016.
    43 changes: 43 additions & 0 deletions jq-cheetsheet.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,43 @@
    # Processing JSON with JQ:

    | --version| Output the jq version and exit with zero. |
    |--sort-keys |Output the fields of each object with the keys in sorted order.|

    , | If two filters are separated by a comma, then the input will be fed into both and there will be multiple outputs
    ? | Ignores error if unexpected type
    [] | Arrya construction
    {} | Object construction
    + | concatenate or add
    - | difference of set or substract
    length | size of selected element

    # From Object

    Keys | jq 'keys'
    Adds + 1 to all items | jq 'map_values(.+1)'
    Delete key| jq 'del(.foo)'


    # From Array
    || Action || Command ||
    | All | jq .[] |
    First | jq '.[0]'
    Range | jq '.[2:4]'
    First 3 | jq '.[:3]'
    Last 2 | jq '.[-2:]'
    Before Last | jq '.[-2]'
    Add + 1 to all items | jq 'map(.+1)'
    Delete 2 items| jq 'del(.[1, 2])'
    Select array of objects | jq '.[] | select(.id == "second")'
    Select array of int | jq 'map(select(. >= 2))'
    Select by type | jq '.[]|numbers' or arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars
    Concatenate array | jq 'add'
    Flatten an array | jq 'flatten'
    Create a range of number | jq '[range(2;4)]'
    Display type of each item| jq 'map(type)'
    Sort an array of basic type| jq 'sort'
    Sorts an array of objects | jq 'sort_by(.foo)'
    Group by a key - opposite to flatten | jq 'group_by(.foo)'
    Minimun of an array| jq 'min' .See also min, max, min_by(path_exp), max_by(path_exp)
    Removes duplicates| jq 'unique' ; jq 'unique_by(.foo)'; jq 'unique_by(length)'
    Reverse an array | jq 'reverse'