Pre-Requisites

  • Know how to create a Site, with Starter Site Enabled. Learn more here: https://siteglide.support/en/articles/3508489-creating-sites We'll be using a Starter Site as the basis for these tutorials, so that you'll instantly have familiar website data available to fetch via GraphQL.
  • Siteglide-CLI - You'll need to understand how to open terminal on your machine and navigate to your Project's root folder. You'll need to have installed Siteglide-CLI and its dependency Node.js. You can't use GraphQL without Siteglide-CLI.
  • About GraphQL- optional- Read more about GraphQL and when it might be best used.

Introduction


In this first of the GraphQL Tutorials, you'll need to either create a new Starter Site, or open up a Starter Site you've created previously. 

We'll use Siteglide CLI to open the GraphQL sandbox. There, you'll write your first query- which will ask for all the data on the entire Starter Site!

Running the GraphQL sandbox


The GraphQl sandbox is a place for testing Graph Queries. It has the additional benefits of giving you suggestions and documentation alongside your code. 

When you open the sandbox- you'll be opening it with your chosen environment. This means you're picking a Siteglide Site to give the sandbox access to- it will be able to find database items from this Site.

For these tutorials, we strongly suggest you use a Starter Site- because then you'll have exactly the same data and it will be ready to go.

Choose an Environment (Site) to Connect to

Change directory into your project folder (create a folder first if you don't have one).

Then add your Site as an environment (add your siteglide email, the URL for your site, and choose an environment name where you see placeholders). Add your Siteglide Admin password when prompted:

Run the Sandbox


The command for running the sandbox is (replace the my_env placeholder with the name you chose in the previous step):

siteglide-cli graphql my_env 

Success should look like this: 

Click, Ctrl+click (if your machine allows), or copy the "GraphQL Browser" link into a browser. This will open the sandbox. 

To start with a few important features are hidden. Click and drag up the QUERY VARIABLES panel from the bottom left and click the < Docs button in the top right. We'll come back to these later.

You've now set up your GraphiQL sandbox.

Your First Query


For your first query, we'll fetch every model on the Site. A model is a catch-all term for WebApp and Module items that we'll use in these tutorials.

Step 1) Name your query

query get_everything {
 
}

Notes:

  • The word query tells Graph we want to GET data, as opposed to modifying data. 
  • get_all_models is simply a name we have given the query. It is optional and has no functionality. 
  • Curly braces { } have been added - these will contain an object containing the next level of instructions we will give the query. The next level from here is also known as RootQuery as it is the most fundamental level at which we choose which type of query we'll use.

Step 2) Choose a Query type

The documentation panel on the right shows you the full range of query types available. Click RootQuery to see the options on this level.


We'll be choosing models for our first query. This will get us a list of models in the database.

query get_everything {
  models {
   
  }
}


Notes:

  • The new code goes within the first level of curly braces we opened in the previous step. Notice how our instructions are "nested" inside each other- like a "Russian doll", just as the documentation on the right has options nested inside each other. 
  • We open another pair of curly braces inside models . We'll add further options here.

Step 3) Ask for results


A GraphQL query doesn't give you results unless you ask for them. This helps it to stay as efficient as possible. We'll ask the query to pass back some key information about the models it finds, such as their schema_name (this will help us identify which WebApp or Module the item belongs to) and then all of its properties (fields). 


If you're following the documentation in the right-hand panel, you'll find that each query type is displayed like this:

We can access the options for what the query will return by clicking ModelCollection! Think- "results are at the end" if you find this hard to remember.

Next, we'll ask the query to return results and total_entries.

query get_all_models {
  models {
    total_entries
    results {
      model_schema_name
      properties
    }
  }
}


Notes:

  • total entries returns an integer, so we don't need to give it any more information.
  • results requires us to specify which fields we want to return with those results. We open a new pair of curly braces and choose fields from the docs. Siteglide doesn't use all of these fields, so some will return null . You can use properties to return all fields which have a value. 

Step 4) Add Arguments


You can press the "play" button to test your query:


 Ours is not quite ready, and the error message in the middle-right panel will tell us why:

{
  "errors": [
    {
      "message": "Field 'models' is missing required arguments: per_page",


Arguments are passed into a query to modify its behaviour. They always use round brackets ( ) syntax, just like JavaScript. Different types of queries will require some arguments, while allowing others as optional arguments.

This query requires that we specify how many records we would like to retrieve on each page of the results. This is to make sure the query isn't slowed down by retrieving too many records at once. We'll learn how to navigate multiple pages later, for now we'll ask for the first 20 records. 

query get_all_models {
  models(
    per_page: 20
  ) {
    total_entries
    results {
      model_schema_name
      properties
    }
  }
}

Step 5: Press play to fetch all results


If successful, you should see an object named "data" containing a tree of your results. Well done, you've written your first query! You've returned all "models", in other words: WebApp and Module items.

You'll see there are actually more total_entries than the 20 results shown. That's because we're only viewing the first Page of the Results. We'll look at this in the next Article. 

Next Time


In the next Article we'll look at how  GraphQL organises results into pages. We'll look at how to change Page and the number of items per Page. We'll also show you how to output some useful pagination metadata.

Let's go: http://siteglide.support/en/articles/3721932-learning-graphql-tutorial-2-pagination

Did this answer your question?