Tutorial 9 - Using Mutations to Create New Records
PreviousTutorial 8 - Building a Liquid API GET Endpoint Page powered by GraphQL queriesNextTutorial 10 - Using Mutations to Edit a Record
Last updated
Was this helpful?
Last updated
Was this helpful?
So far, these tutorials have used GraphQL queries; in this article we're going to start looking at mutations.
The difference between queries and mutations is that:
Queries "read" data from the database
Mutations "create", "update" or "delete" data.
Keeping these types of operations separate is helpful, as it means you can be confident that running a query will not endanger the database on a live site.
When learning and testing GraphQL mutations, we strongly recommend you do so on a staging site.
If you need to test with real data, we recommend using the Siteglide Portal's Site Copy feature to create a staging site clone of a production site with a copy of the database.
Siteglide may not be able to recover the exact state of data as it was before running a mutation which modifies that data.
See for more tips on what to do if you accidentally delete data you didn't mean to. (This won't help if you accidentally change the properties!)
All queries started with the query keyword; mutations start with the mutation keyword.
If using explorer, click the dropdown to select mutation instead of query, to unlock different options:
This will create a new record (or user_create to create a new CRM user.)
The required record object allows you to define both the properties of the new record and which table it should belong to.
Setting the table allows you to define which module or webapp it will belong to:
As with queries, the explorer UI cannot handle multiple properties in a mutation. You can use the explorer to figure out which individual property types are possible and then add the code manually. properties itself can be written as an array with each object inside the array defining a property to set.
Data Types
Each property must have a name which matches the ID of the field or custom field in Siteglide. When setting a value, you need to select a property value, value_array, value_boolean etc. depending on the platformOS type of data the field expects.
To find out which Siteglide types your table uses for each field, go to the corresponding WebApp or Module in the Siteglide Admin, or you can use this query to see each field's ID and Siteglide types together (you can also change the filter and properties to see which other tables are available):
When using boolean, float or integer, you don't need to use quotes.
While results are generally less useful in a mutation than in a query, having at least one result is generally required and your mutation won't work properly without it. The idea is simply to give you information about the record in the database after the mutation to confirm that the mutation was successful - even if this is simply an ID.
Mutations which affect multiple records at once often have a count result which only returns the number of records created.
You can add the results you need in the curly braces after the round brackets which follow record_create
If successful, your results should return like this:
If you have an error, the error information will display instead of the results. In this case, value_int was used instead of value for the Blog Item's title:
In the following example, variables are added to pass in data programatically to create the new Blog post:
This is an advanced technique and you can skip it if you want to continue learning the basics of mutations.
If you like, you can use a variable to represent the entire properties object and pass in JSON which defines all the properties at once. Why? It might save time (or not), depending on the kind of data you have available. It may also make the mutation more re-usable. Learning advanced skills like this may give you more options as a developer and you may come across a situation where it's useful.
Note how the parse_json tag is used with literal square brackets to create a JSON array with nested objects defined by curly braces. The category_array property is an example of how you can pull in Liquid from different sources into these properies, though this.id would only contain a category ID in for example a category detail layout.
Note, the structure of the JSON we are passing in the previous example is similar to the structure of properties in the mutation, but it is necessary in JSON to use double quotes around the keys like name:, while the GraphQL syntax needs no quotes.
Using explorer to turn properties into a variable is a quick way to reference the required type for the complex variable [PropertyInputType]:
That's it! You should now be able to create Siteglide WebApp and Module items programatically using mutations.
You could experiment with the user_create mutation to create users. Instead of a record object this will have a user object which accepts a required email property.
In the next tutorial, we'll look at more examples of mutations, including mutations to update and delete records.
To figure out the correct one, you can reference this page which will show which platformOS types are used by each Siteglide type.
We covered variables in more detail in but they are just as useful in mutations!
- combining what you've learned in Tutorial 8 and 9, you should be able to create an API where the Liquid endpoint runs a mutation to create items. You could use this alongside a custom form to allow the user to enter properties which are then passed to the endpoint in the URL and then finally into the mutation via variables.
