Basic query tutorial

Queries in GraphQL are created by opening curly brackets.

{

}

If we have more than one query, we need to name them and specify that this is the query, we do it as follows.

query queryName {

}

An example of a simple query that will return the value of "pageInfo" from the "productStream" branch, and from there provide the value of "endCursor". Additionally, from the "productStream" branch, it will return the value "totalCount". Think of it as a tree, a branch, and a leaf. To get information from a leaf, you must first reach it by going through all the steps one by one. Each subsequent indentation must be called using the next curly bracket. Until it's closed, we are constantly working within the same space.

For better understanding, I've stretched the code below to reflect these indents.

query queryName {
                productStream {
                                pageInfo {
                                                endCursor
                                }
                                totalCount
                }
}

The query can also use arguments. The list of available parameters can be found in the API schema(documentation). Here, we will use the "first" argument.

Without using this argument, the system would return all the data it finds, here we want to limit ourselves to the first 2 results.

query queryName {
  productStream (first: 2) {
    pageInfo {
      endCursor
    }
    totalCount
  }
}

It is also possible, to refer to the same place with several arguments, in this example we wanted to get the first 2 results and the then results after something.

query queryName {
  productStream(first: 2) {
    pageInfo {
      endCursor
    }
    totalCount
  }
  productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    totalCount
  }
}

However, the above query will not work without a slight modification. If to a given object we refer more than once, we must use aliases. Below I used two aliases: "firstTwo" and "dataAfter". Remember to use a colon after the alias.

query queryName {
  firstTwo: productStream(first: 2) {
    pageInfo {
      endCursor
    }
    totalCount
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    totalCount
  }
}

query x {
  productStream {
    pageInfo {
      endCursor
    }
  }
}

Note that in the query (the previous one, not the one about available cursors) we call the same "totalCount" data 2 times unnecessarily. We can simplify this by using fragments.

The following query will return us exactly the same data as the previous one.

Of course, if I'm querying only one thing, there's no point in throwing it into a fragment.

However, if there were more objects or the query was more complicated, fragments allow us to optimize it.

query queryName {
  firstTwo: productStream(first: 2) {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
}

fragment fragmentName on ProductConnection {
  totalCount
}

In GraphQL it is also possible to use variables, variables are usually passed on by programming languages, but for the sake of completeness, I will show you how to use them.

Before the first curly bracket, I open a round bracket and define ( with the $ sign ) a variable named x in it, then I make a colon and a space and define the type of the variable, in this example, it will be Int (Integer). I could be done here, but I still would like to define a default value, so I put an equals sign followed by "2".

Then in the place where the variable should be passed I simply call it bt $x:

query queryName ($x: Int = 2) {
  firstTwo: productStream(first: $x) {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
}

fragment fragmentName on ProductConnection {
  totalCount
}

Queries can also use directives. In other words, conditional statements.

I'm going to add a second variable to my query named condition and set its type to Boolean, with the default value true.

Then after pageInfo I placed @include(if: $condition) directive.

query queryName ($x: Int = 2, $condition: Boolean = true) {
  firstTwo: productStream(first: $x) {
    pageInfo @include(if: $condition) {
      endCursor
    }
    ...fragmentName
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
}

fragment fragmentName on ProductConnection {
  totalCount
}

Since I have previously set the default value of the $condition variable to true, the condition will be met and the data will show up, but if I change it to false, the data will not.

query queryName ($x: Int = 2, $condition: Boolean = true) {
  firstTwo: productStream(first: $x) {
    pageInfo @include(if: $condition) {
      endCursor
    }
    ...fragmentName
  }
  dataAfter: productStream(after: "YXJyYXljb25uZWN0aW9uOjM0Mw==") {
    pageInfo {
      endCursor
    }
    ...fragmentName
  }
}

fragment fragmentName on ProductConnection {
  totalCount
}