Rillence
Login

← All bricks

jq · Beginner

jq: Slice and Shape JSON

Get fluent in jq — pull fields out of JSON, filter and reshape arrays, build new objects, aggregate with group_by and reduce, and turn messy JSON into clean CSV, TSV or plain text from the shell.

JSON is everywhere — API responses, config files, log lines, cloud output — and jq is the tool that lets you reach into it from the command line without writing a script. It is a small language built around one idea: a filter that takes JSON in and gives JSON out, with pipes between filters just like the shell. We start from the identity filter and build up real fluency one small thing at a time: reading fields, iterating arrays, selecting and mapping, constructing new objects, aggregating with add, group_by and reduce, and finally formatting the result as raw text, CSV or TSV. Everything runs against a couple of small sample files you can keep on hand, so each idea lands on its own and you can try it immediately.

What you'll build

  • Read fields out of objects and arrays with jq paths
  • Iterate, filter with select, and reshape with map
  • Construct new objects and pull out keys
  • Aggregate with add, group_by, sort_by and reduce
  • Pass shell values in and slurp a stream of inputs
  • Emit raw text, CSV and TSV for the rest of the pipeline

Contents

  1. Check your jq
  2. A file to play with
  3. The identity filter
  4. Reach into the array
  5. Pull out a field
  6. Go a level deeper
  7. Slice a range
  8. Iterate the array
  9. Pipe filters together
  10. Iterate a field that isn't always there
  11. Make it optional
  12. Keep only what matches
  13. Filter, then narrow
  14. Transform every element
  15. Build a slimmer object
  16. Rename as you build
  17. List an object's keys
  18. Measure with length
  19. Check for a field
  20. Supply a default
  21. Turn an object into pairs
  22. Drop the quotes with -r
  23. Build a sentence
  24. Emit CSV
  25. Or tab-separated
  26. A second file with numbers
  27. Sum with add
  28. Order by a field
  29. Drop duplicates
  30. Group and total
  31. Find the extreme
  32. Fold it yourself with reduce
  33. Pass in a value with --arg
  34. Pass a number with --argjson
  35. Read the environment
  36. Write a stream of JSON
  37. Slurp the stream into an array
  38. Search everywhere with ..
  39. List the paths
  40. Delete a field
  41. Compact output with -c
  42. Put it all together