Hello WebApp! In Tutorial 1, we'll use Siteglide CLI to open the GraphQL sandbox. There, you'll write your first query.
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!
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.
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:
The command for running the sandbox is (replace the my_env placeholder with the name you chose in the previous step):
siteglide-cli gui 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. Short Method: If you want to save time and skip the step of opening the link, add the flag -o to automatically open the link after you run the command: siteglide-cli gui my_env -o
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. Click the "Toggle Explorer" button to open the Explorer wizard. This is a new tool which will make writing (non-deprecated) queries even easier.
You've now set up your GraphiQL sandbox!
The Central Panel
This is where you write your Query The Results Panel This is where the data will be displayed in JSON format after your query fetches it.
Query Variables Panel This is where you'll be able to simulate dynamic variable inputs when testing variables in your Query.
We'll cover this in a later Article. Explorer Panel *NEW* This displays the GraphQL schema in the form of a "wizard". Tick the options you want to include and they will automatically be added to your query. This is the most user-friendly way to write queries for beginners (and possibly for the experienced GraphQL developers as well!).
The only main limitation is that it doesn't currently support older deprecated queries, if you have a need to use those. Documentation Explorer Panel This displays the available GraphQL schema. It works with nested levels, so each time you choose an option you can "click through" to the next level of options you can include.
This is less user-friendly than the new "Explorer" panel above, but can still be useful:
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. In these tutorials, we'll break the process of building a query into steps. For each step we'll show you:
We'll sometimes also include a screenshot of the Documentation Explorer Panel to illustrate it's use, but this depends on whether it seems useful or not!
Explorer: The "Explorer" wizard will add this for you if you type out a name here:
The documentation panel on the right shows you the full range of query types available. Click RootQuery to see the options on this level.
You can also see a list of non-deprecated query types in the Explorer panel:
We'll be choosing models for our first query. This will get us a list of models in the database. Code:
Explorer: Quickly implement this level in the Explorer Panel by selecting the "models" query type. This will also open the next level of options in the explorer:
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).
Next, we'll ask the query to return results and total_entries. Code:
You can press the "play" button to test your query:
Ours is not quite ready, and the error message in the middle-right Results Panel will tell us why:
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. Code:
Explorer: You can set a value for per_page in Explorer.
Notice that the asterisk by the option in Explorer lets you know the property is mandatory.
In Explorer, there is a subtle colour scheme to help you differentiate between setting arguments and returning 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 Pagination in the next Article.
In the next Article we'll look at how GraphQL organises results into pages. We'll look at how to: