syntaxjqabbreviation

jq, when to use the dot and when not


Consider the following json string:

{
  "data": {
    "search": {
      "repositoryCount": 24,
      "edges": [
        {
          "node": {
            "name": "leumi-leumicard-bank-data-scraper",
            "url": "https://github.com/Urigo/leumi-leumicard-bank-data-scraper",
            "description": "Open bank data for Leumi bank and Leumi card credit card",
            . . . 
        },
        {
          "node": {
            "name": "puppeteer-demo",
            "url": "https://github.com/xJkit/puppeteer-demo",
            "description": "A demo for website scrapping by my puppet :>",
            . . . 

If to use jq to select the data, then it needs a dot (.) before it. I.e.:

jq 'data' 
jq: error: data/0 is not defined at <top-level>, line 1:
data
jq: 1 compile error

However jq '.data' works fine, and the selected data becomes:

{
  "search": {
    "repositoryCount": 24,
    "edges": [
      {
      ...

If to use jq to select the search, after the pipe, then it does not need a dot (.) before it. I.e.:

$ jq '.data | {.search} ' 
jq: error: syntax error, unexpected FIELD (Unix shell quoting issues?) at <top-level>, line 1:
.data | {.search}          
jq: 1 compile error

However jq '.data.search' works fine.

Moreover, a more complicated example,

jq '.data.search.edges[] | {node} '

works fine, but

jq '.data.search.edges[] | {node.name} '

gives:

jq: error: syntax error, unexpected FIELD, expecting '}' (Unix shell quoting issues?) at <top-level>, line 1:
.data.search.edges[] | {node.name}                             
jq: 1 compile error

So, all in all, I'm rather confused when to use the dot (.) and when not to, when using jq. Please help. Thx.


Solution

  • Perhaps things will be clearer if you begin by thinking of the full data pipeline involved, and recognize when an expression is just an abbreviated form.

    In constructing an unabbreviated pipeline, the basic principles regarding "dots" are quite simple:

    There are many allowed abbreviations. The two that seem to have confused you the most are:

    Another important abbreviation is:

    With these principles and examples in mind, you should be able to master the details as explained in the jq documentation.