Intro

  jq is a lightweight and flexible command-line JSON processor akin to sed,awk,grep, and friends for JSON data. It’s written in portable C and has zero runtime dependencies, allowing you to easily slice, filter, map, and transform structured data. knitr::tufte::quote_footer(“From The jq [github page](jq is a lightweight and flexible command-line JSON processor akin to sed,awk,grep, and friends for JSON data. It’s written in portable C and has zero runtime dependencies, allowing you to easily slice, filter, map, and transform structured data.)”)

  Learned about from a ThePrimeTime video

Basic Commands

  Learning basic commands from this video by Navek on YouTube

jq '.' your_file.json - Pretty print your JSON to the terminal - The period is representative of the object that is passed into jq

jq '.TARGET-KEY' your_file.json - Will return only the value associated with the key you’re looking for - e.g. ... '.apiVersion' ... will go to the "apiVersion": "v2" lines, and returns just “v2” - the -r option, placed at the end of the command, will removed the double quotes around the returned values

You can specify embeded keys by building onto the TARGET-KEY specifications - e.g. “Name” is embedded within “User”, and that’s the one I want: ... '.user.name' ...

... '..' ... - Double period will print the whole JSON, the next level of keys, then their values

jq '.[]' json.json - Will unpack your objects from any array they’re embedded in, and return them individually - Further, you can place an index, or range of indexes, within the brackets, e.g. [0], to return only the objects at those indexes - This can be paired with continuing to specify the desired keys as well, e.g. .[2:4].title

jq '.[]' | .title .id - You can pipe the jq output into the key-specifications to return each item as a pair rather than all of the titles, then all of the id’s

jq. '.[]' | .NEW-KEY = <input> - Add another key to your JSON

jq. '.[]' | {NEW-KEY-NAME: .OLD-KEY-NAME, SECOND-NEW-KEY-NAME: .SECOND-OLD-KEY-NAME} - Rename an existing key(s) and assign values associated with an old key(s) to those new keys

jq. '.[] | "Our title is \(.title)" ' - Will print lines reading “Our title is” followed by the values in each of the title keys for the whole JSON

Built-In jq Functions

jq '.[] | keys' - Will return the keys for every object in your JSON

jq '.[] | length' - Will return the length of each object in your JSON

jq '. | length' - Will return the length of the whole JSON

jq '. | map(.id += 1) - Will add 1 to each instance of the id key in the whole JSON

jq '. | map(.title += new_title) - Will append “new_title” to every title (use = rather than += to replace the titles with the new input)

jq '.[] | select(.id > 19) - Will select only the objects with id values that are greater than 19 jq '.[] | select(.completed = "true") - Will select only the objects with a completed key equal to “true”

You can run even further complexities, using if-then logic within your command

Additional Commands with Prime

jq -c - Will display your JSON in compact mode

jq '{id: .id, logs: .logs}' - Creates a smaller object from the large one, with the new one only including teh id and logs values

jq 'select(has("logs"))' - Will only return the objects that do have a “logs” key

jq 'select(.values.a + .values.b > 0)' - An example of adding logic to the select command

jq 'select(.errors | length > 0 and any(.[]; contains("target")))' -c - Selects only errors with length greater than 0, AND has any of the keys within the errors key equal to “target”

Utilizing jq Within Neo Vim using :!

Inside Neo Vim… :!jq - Will unpack the compacted line of JSON you were on inside of Neo Vim - -c to re-compact it

%!jq - Will unpack the entire file

Any of the commands we ran previously, you can run in Neo Vim as long as you put :%! in front of it