Querying JSON data at the command line with ‘jq’

Image of Mattias Geniar

Mattias Geniar, November 17, 2015

Follow me on Twitter as @mattiasgeniar

If you’re not familiar with the tool yet, I’d like to introduce you to jq: a lightweight and flexible command-line JSON processor.

The jq tool us super useful to query JSON data at the command line of a Linux (or Mac OSX) machine as a sysadmin.

Installation

Depending on your OS, it’s going to be:

# CentOS, Red Hat
$ yum install jq

# Debian, Ubuntu
$ apt-get install jq

# Mac with Homebrew
$ brew install jq

Usage

I’ll be showing you a quick usage with ElasticSearch. It’s a service that has, for this demo, a very simple HTTP call you can make that returns a JSON response.

Here’s the raw data:

$ curl -s -XGET 'http://localhost:9200/_cluster/health?pretty=true'
{
  "cluster_name" : "your_cluster_name",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 10,
  "active_shards" : 10,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 10
}

We get a nicely formatted JSON reply. Sure, you can grep, sed and awk this output and get the values you want, but there’s a cleaner solution out there, called jq. Whether it’s simpeler depends entirely on you and what you’re more comfortable with.

If I want the output of the “status” key and want to see its value, I can do this with jq:

$ curl -s -XGET 'http://localhost:9200/_cluster/health?pretty=true' | jq -s .[0].status
"yellow"

Let’s break it down a bit:

  • jq: the binary you just installed
  • -s: read the input stream (the curl before the pipe) and process it as a whole
  • .[0].status: process the entire response (.), take the first element from the JSON array (.0) and give me the status key (.status)

This example just touches the basics of jq, if you want to parse more complex JSON values and do some calculations or output manipulations, check out the `jq` manual and documentations.



Want to subscribe to the cron.weekly newsletter?

I write a weekly-ish newsletter on Linux, open source & webdevelopment called cron.weekly.

It features the latest news, guides & tutorials and new open source projects. You can sign up via email below.

No spam. Just some good, practical Linux & open source content.