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:

. refers to the input
.foo is for accessing the value of the key "foo"
.[] is for expanding an array or object

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

.foo.bar for .foo | .bar
{foo} for {"foo": .foo}

Another important abbreviation is:

E[] for E | .[] where E is a suitably compact expression

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