Onit's Liquid GraphQL Queries feature allows users to execute different types of queries across applications; adopted from the industry standard, this feature gives users a powerful tool for querying data.
Here, we'll take you through some of the basics of using Onit's Liquid GraphQL Query function.
Using Liquid GraphQL Queries
1. Navigate to Liquid Functions under the Global Configuration group in the Application wizard.
2. Click on the Add icon and then click on Liquid Graphql Query to create your query.
3. The Liquid Graphql Query screen will appear.
4. Fill out the Name of your query.
5. Fill out the Parameters of your desired query. These could be things like a date range, business unit, etc. that you would like to input into the query; you can use those parameters as the constants or functions within a filter. You'll see these reflected in the Variables field.
Note that you can also fill in multiple parameters within the Parameters box. Just type them out separated by a comma (no space after the comma).
6. Check or uncheck the Always run as system admin box. Running the query as a system admin allows you full access to all data within the system; unchecking the box and running the query as a standard user will only allow access to that data open to that user.
NOTE: This box can ONLY be checked by a system administrator. Additionally, be cautious when running queries as an administrator; these queries may provide wider access to sensitive data.
7. Fill in your Query. You can either cut / paste the language in the box or use the GraphiQL Query Editor to build your query. Open the Editor by clicking on the pencil button to the right of the Query field.
NOTE: This takes a while to load, so it's recommended that you keep this application running in a separate background as you work.
The GraphiQL Query editor is made up of a few different sections: the Toolbar, the Query Pane, the Query Variables Pane, the Results Pane, and the Documentation Explorer.
Let's break down those sections:
The Toolbar contains five buttons: Play, Prettify, Merge, Copy, and History.
- Click on the Play button to test the query. Results will appear in the Results Pane.
- Click on the Prettify button to "clean up" the text in the main Query Pane. This button will also help alert you to errors and remove extraneous text.
- Click on the Merge button to condense the defined fragments in a query.
- Click on the Copy button to copy all the Query Pane text to your clipboard.
- Click on the History button to open the History Pane to the left-hand side of your screen. There, you can see and add all of the prior queries you've worked on.
Use the Query Pane to construct your queries. A few notes on the Query Pane:
- GraphiQL includes command line completion in order to help create better queries.
- Error checking and validation (in this pane and in the Results pane) helps proof the query.
Use the Variables Pane to modify the filters / detail the variables in your query. Note that you'll need to replace the hard-coded test lines (in this example, {parent_id}) with the actual Liquid language in the Variables section.
The Results Pane will show the Query results once you hit the Play button to test.
NOTE: GraphQL will automatically highlight errors in the query. Additionally, this is a read-only field. All edits should be made in the Query Pane.
Once you're finished working on the Query, click Save.
8. On the Liquid Graphql Query page, you'll now see the Query and Variable text boxes filled in.
9. Add in a Comment (if necessary) and click Save to save your query.
You can view, edit, or delete your Liquid GraphQL queries by clicking the drop-down menu next to Liquid Graphql Queries on the Liquid Functions group.
You can now deploy your Query in the Liquid editor or in any Actions that support Liquid. If you defined parameters on your Liquid Graphql function then they will appear as param liquid blocks:
Liquid GraphQL Query Notes
- Beware of adding too much data to the query; keep it at around 1,000 records or below.
- Note that Onit allows more special characters in application names than GraphQL, so it might not always match up perfectly; be sure to double-check your query.
- This CAN be used in UI actions, but be careful of performance; again, that volume may overwhelm the system.
- You can see the posts to a query by going into the Network tab of Development Tools. From there, you can copy and paste the query text and variables.
