Start Here: Writing Inline Expressions

Hello, jq

The simplest jq command merely echoes its input. It looks like this:

cat input.json | jq '.'

Note

Yes, yes, “Useless use of cat”. I’m not interested and I’m not impressed. You can write your command any way you like; I’ll write it like this, because it makes the flow of input to output explicit and obvious. This form makes it easier to replace cat input.json with echo '{"a": 1, "b": 2}' or any other method of sending input through the stdin stream to jq.

You do you.

I read the jq program '.' as “print this”, but what’s “this”? By default, jq labels the content it receives from the stdin stream as “this”.

Tip

The meaning of . in jq reminds me of the meaning of this in JavaScript: it takes a lot of getting used to and, in the meantime, it seems mysterious, capricious, and annoying. I’ve chosen to find it charming; I encourage you to make peace with it until you understand it better.

When you run this command, jq prints a nicely-formatted version of the JSON object it receives from stdin to stdout.

echo '{"a": 1, "b": 2, "c": {"d": 4, "e": 5}}' | jq '.'

{
  "a": 1,
  "b": 2,
  "c": {
    "d": 4,
    "e": 5
  }
}

Excellent!

Filters

Now you can learn about some elementary filters, such as how to select objects within objects, values with objects, and items within arrays. Maybe you can guess what an expression like .c.e does…

echo '{"a": 1, "b": 2, "c": {"d": 4, "e": 5}}' | jq '.c.e'

5

…or maybe you prefer to know that .c.e is shorthand for .c | .e, which illustrates how . (“this”) behaves. The output of the preceding filter becomes . (“this”) in the following filter. Moreover, jq uses | to connect filters together, just like piping works in bash and its cousins.

echo '{"a": 1, "b": 2, "c": {"d": 4, "e": 5}}' | jq '.c | .d'

4

And you can select objects as well as atomic values.

echo '{"a": 1, "b": 2, "c": {"d": 4, "e": 5}}' | jq '.c'

{
  "d": 4,
  "e": 5
}

That’s Enough!

You have literally all you need to write jq code to transform JSON values into other JSON values. You can go very far with just this bit of knowledge and some haphazard reading of the jq manual.

You’re ready for the next step when you start to struggle to understand complicated expressions or you want to remove duplication from those expressions.

Tip

I find the edit-and-execute command invaluable in general, but I find it particularly helpful when poking around in jq. If you know of this command, but don’t use it fluently, then working in jq gives you a compelling reason to practise. If you don’t know of this command, then this guide is about to change your life for the better. This is not hyperbole, I assure you.