• GraphQL is a query language for APIs and a runtime for fulfilling those queries. GraphQL provides a complete and understandable description of the data in our API and gives you the power to ask for exactly what you need and nothing more. If you want to learn more about GraphQL, then check out graphql.org.
• GraphiQL is an interactive, in-browser GraphQL integrated development environment. You can use it to read or change your site's data with the GraphQL language.  

Part of learning any new tool is learning the terminology.

In GraphQL you write queries to read the database. A GraphQL query is essentially a tree that declares the data you are looking for, such as all users created after a specific date. When you submit a query with GraphiQL, the output is the data matching the specifications of your query. The input is in the GraphQL language and the output is in JSON (JavaScript Object Notation).

Mutations are GraphQL expressions to change the database.

So, queries are for extracting data and mutations are for adding, updating, and deleting data.

Please note queries are still in beta and mutations are in early alpha - so let your Project Manager know if you encounter issues. 

See an example of a query below. The query is entered on the left hand GraphiQL pane. After the query is created, clicking the arrow runs the query and outputs the data on the right hand pane as JSON.

# The JSON output is paginated. Most sites have a maximum 100 records

# per type, per query. To see pages other than the first one specify

# the page argument in the list field. This example below specifies

# page 3 of the list of all users.

query SampleQuery {

 users(page: 3) {

   id

   email

   oid

   live

 }

}

See an example of a mutation below. In GraphiQL the mutation is entered in the left hand pane, as with a query. After the mutation is created, click the arrow to post the mutation and change your site's database.

# This mutation example creates a new article. The data for the

# article is in the $input variable, which can be added in the lower

# left "Query Variables" pane of GraphiQL or provided in the post

# request parameters as a variables hash. This mutation returns the

# id of the newly created article, plus a boolean success flag and a

# list of any errors.

mutation ($input: ArticleCreateInput!) {  

 articleCreate(input: $input)            

 {                                                      

   article { id }                                                    

   success                                              

   errors                                              

 }                                                      

}

You can access GraphiQL on both your staging and production sites.

• To see the documentation defining the fields and specifying which fields you can use to sort and filter for each content type, add /query/docs to either your staging or production URL.
  • For example: https://www.yourdomain.com/query/docs
• To see example queries and mutations, add /query/docs/examples to your staging or production URL.
  • For example: https://www.yourdomain.com/query/docs/examples
• If you just want to do a query or mutation, add /query/graphiql to either your staging or production URL.
  • For example: https://www.yourdomain.com/query/graphiql

Adding a filter to your query with filterString helps you refine your query to narrow down the results. For example if you want to output only users created after a date you could query for

users(filterString: "createdAt > 2019-03-01") { email }

To see which fields the main content types, such as users, articles, and events, can be filtered by, see the documentation at /query/docs/operation/query. In GraphiQL documentation is also available in the Docs drop down on the top right.

Tips for Learning GraphQL

• Relax and take your time. 
• Focus on one content type at a time such as articles or users. 
• Start with the example queries. 
  • When first learning queries, starting a query from scratch can be more challenging then tweaking an example query. You can find example queries at /query/docs/examples. 
• Start with queries and then take on mutations.
• Take advantage of GraphiQL auto suggestions.
• Learn the syntax of GraphQL. This will become second nature as you increase your skills. Here are some handy tips to get you started. 
  • You need the same number of closing curly braces as you have opening curly braces.
  • Field names are mixed case with the pattern of lowercaseUppercase. For example, updatedAt 
  • The syntax for an argument is parenthesis, argument name, colon, space, argument value, and closing parenthesis. 
    • For example: articles(page: 2) { title }
  • The syntax for a filter with only a single criteria is parenthesis, filterString, colon, space, quotation mark, field, space, qualifier, quotation mark,  and closing parenthesis. 
    • For example:  users(filterString: "createdAt > 2019-02-01"){ email }
  • The syntax for a filter with more than one criteria is parenthesis, filterString, colon, bracket, quotation mark, field, space, qualifier, quotation mark, comma, quotation mark, field, space, qualifier, quotation mark, bracket, parenthesis. 
    • For example: articles(filterString: ["postAt < 1 year ago", "active isNotNull"]) { title }