There are two types of operations that can be performed in GraphQL: queries and mutations. Mutations are used to create, update and delete data.
See About Connect and GraphQL for more information on how Connect leverages GraphQL APIs.
For a deep technical dive into mutations, refer to https://graphql.org/learn/queries/.
Why are mutations useful?
A complete data platform needs a way to modify data as well as to fetch data. Queries support fetching, however, they don’t modify data. This is where mutations come in to play. In short, if you want to do anything with a GraphQL API other than read data, you need to use a mutation.
Mutations have a wide range of uses, including data onboarding, command and control of HVAC equipment and performing digital service work.
For information on the mutations available in Connect, see the Connect API documentation, which is available directly in the Altair GraphQL client as shown below.
For more information on Altair see Getting Started with the Connect API.
Using Mutations in Onboarding
Creating data with a mutation
Data objects are created using mutations in the onboarding process. An example of a mutation used to create a piece of HVAC equipment is shown below.
One the first line, highlighted in blue, you see the action we are attempting to create with the mutation: createHVACEquipment.
In green you see the input fields: name, buildingId, hvacId, and oapVariantCode.
In orange are the values you would like to add to the system.
While the use cases and mutations themselves change, the syntax of the mutation – the way in which you write the code to push the mutation – doesn’t change.
To execute the mutation, click “Run Mutation”, which will appear in green above the mutation once you’ve successfully written it. Once the mutation shown below is executed, VAV0101 has been successfully created and it will show up in Noda Energy. The response confirms that the mutation successfully executed as shown in the “result” tab in Altair. If there is an error in creating the equipment, this is where it will show up.
If you are working within GraphQL in this way, you are working directly in Connect. Connect also has a user interface within which it is possible to execute mutations without having to write a single line of code. As this feature becomes widely available, we will link to Help Center articles.
Updating data with a mutation
Just like creating new equipment in Connect, mutations are also used to edit existing data objects. For example, a service technician got word from their facility manager that a VAV box is incorrectly named in their Noda Energy system. The equip is named VAV0101 in the system but everyone in the building refers to it as VAV-A. This is causing confusion for the people using the system and they would like the name changed to reflect what people are actually calling the equipment.
The mutation for this action is updateEquipment and the syntax is written below.
Modify Occupancy Commands using mutations
Sometimes it is necessary to power down equipment in a building. But what happens if the occupancy schedule is ‘Unoccupied’ when equipment is powered off and then ‘Occupied’ when power is turned back on? This would leave the equipment in an Unoccupied state during hours where it should be Occupied since the equipment was unable to receive the global command while without power. With the ability to set points through the Connect API, the Occupancy points in a building across various types of equipment can be set to ‘Occupied’ using mutations.
Modifying setpoints in Connect-enabled building systems is done through haystack mutations like haystackSet. Modifying the occupancy command for a given piece of equipment is done via a haystackSet mutation which takes inputs including the connector and point ids, as well as the value of the command, as shown below. The query response will indicate the success of the command.
It is important to note that in the power example, the haystackSet mutation would have to be executed repeatedly for each of the occupancy points. When you need to make bulk changes to occupancy points across multiple equips, it is more efficient to write a script for this action or make the changes directly in the Noda Energy user interface. Writing scripts for bulk actions will be covered in a separate Help Center article. Changing setpoints via the Noda Energy UI is covered in the Noda UI Quick Reference Guide.
How does Noda Energy use mutations?
Noda Energy is API-first, meaning that all data available through the UI and all actions taken by the user in Noda Energy go through the Connect API. All mutations described above are available for users directly in the UI, no code necessary. When the change is made in Noda Energy, the mutation is run through the Connect API. For advanced programmers, the Connect API is available for any and all mutations and can be used to develop other front-end systems outside of the Noda Energy application.