Tutorial 1- Your First Query

hello webapp! in tutorial 1, we'll use siteglide cli to open the graphql sandbox there, you'll write your first query prerequisites know how to create a site, with starter site enabled learn more here https //help siteglide com/en/article/portal all sites creating editing sites uwv7in/ 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 update 2024 the original starter site mentioned here is being phased out you can now install a new site from a greater choice of site templates here https //admin siteglide com/#/portal/community/marketplace https //admin siteglide com/#/portal/community/marketplace 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 the quickest way to do this is to copy the cli command from your site in the portal or you can replace the url and email flags with your own add your siteglide admin password when prompted finding the cli add command in portal run the sandbox the command for running the sandbox is (replace the staging placeholder with the name you chose in the previous step) siteglide cli gui staging 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 your first look at the graphiql 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 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! what does each panel in the graphiql sandbox do? 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!) note the explorer user interface can't handle arrays of query language very well e g when filtering by multiple properties, even though it's valid graphql; when you hit a limitation like this, it's time to leave the explorer behind and write the code manually the other limitation is that it doesn't currently support older deprecated query and mutation types, if you have a need to use those documentation explorer panel this displays the available graphql schema as documentation 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 especially if you want to use a deprecated query like "customisations" (the only reason for using deprecated queries is that some support features like keyword search that are not supported on the more modern queries yet) if you want to search the schema for features and understand which types are allowed a note on naming conventions platformos sometimes changes the names of elements of their schema for the sake of better communication or as part of a functionality update for example, models have been now renamed to records we are in the process of upgrading these docs to refer to records instead of models but in the meantime there may be some screenshots which continue to show the older terminology your first query for your first query, we'll fetch every record on the site a record is a catch all term for webapp and module items that we'll use in these tutorials the term records does not refer to users , as these contain more core fields like email which set them apart and therefore they use a different query type users in these tutorials, we'll break the process of building a query into steps for each step we'll show you the code you need notes explaining the syntax of the code example in detail a screenshot from the explorer panel, showing the checkbox needed to quickly insert this code new 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! step 1) name your query code query geteverything { } notes the word query tells graph we want to get data, as opposed to modifying data geteverything 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 explorer the "explorer" wizard will add this for you if you type out a name here 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 you can also see a list of non deprecated query types in the explorer panel we'll be choosing records for our first query this will get us a list of records in the database code query geteverything { records{ } } 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 both the explorer panels show options nested inside each other we open another pair of curly braces inside records we'll add further options here explorer quickly implement this level in the explorer panel by selecting the records query type this will also open the next level of options in the explorer 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 records it finds, such as their table (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 query geteverything { records { total entries results { table 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 table will return the name of the table the record belongs to (this was previously called model schema name ) explorer 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 results panel will tell us why { "errors" \[ { "message" "field 'records' 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 code query get all records { records( per page 20 ) { total entries results { table properties } } } notes per page expects an integer, not a string, so we don't need quotes around 20 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 arguments are in purple results, and other returned properties are in dark blue 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 records , or, 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 crm users if you want to get information on siteglide crm users instead of webapp or module records, you can use the users query instead of the records query the main difference is that users can return first name , last name , email etc inside the results curly braces see the explorer panel or the documentation panel to learn more next time in the next article we'll look at how graphql organises results into pages we'll look at how to change page change the number of items per page output useful pagination metadata let's go!