Mutations

A GraphQL mutation is used for modifying data. Separate mutations are available for create, update, and delete and these can be individually enabled per object class. In addition, the mutation persist is enabled (allowing batch create) whenever the object class has create enabled for GraphQL. Read more about enabling GraphQL settings here. Mutations can return the modified object(s), so you can immediately access the updated object without having to make a separate request.

Good to know

Mutations can be built by using the GraphiQL Explorer. Simply select what to mutate, and the IDE will handle the syntax!

Create

Create a single object in the database. The built-in Created Date property (and Created By, if enabled) is automatically set server-side.

// Create a new project and return the ID
mutation {
    createproject(title:"Analyze office layout", projectNumber:1124) {
  _id
}}

Persist (create many / batch create)

For GraphQL enabled Object Classes with Enable Create , you may create multiple objects at once though the persist endpoint.

For example, an Object Class Car with GraphQL Endpoint Name car will have the mutation persistCar available. See example usage below.

// Creating 3 cars with persistCar
// Note that default values defined on the Object Class Properties will be used, 
// and the _id will be auto generated, unless any of these are overridden below
mutation{
	persistCar(
		objects: [
			{
				brand: "Skoda",
				model: "Enyaq"
            		},
			{
				brand: "Honda",
				model: "Civic"
            		},
			{
				brand: "Ferrari",
				model: "F40"
            		}
		]
    )
}

Note that you may also override the default _id in the above persistCar mutation, simply by adding a valid (and unique) objectid to each record:

			{
				_id: "5b71631743501ec10595a144",
				brand: "Skoda",
				model: "Enyaq"
           		}

Update

Update one or more objects in the database. The built-in Updated Date property (and Updated By, if enabled) is automatically set server-side.

The first parameter is a filter object used to determine which object to update. Find more about filters under Queries.

The second parameter is an input object containing the properties you wish to update.

A count of the number of updated objects is returned.

// For the project with the ID "5ef212569decde19f8650de8", update the title to "Reconfigure office layout"
mutation {
    updateproject(
        filter: {
            _id: { eq: "5ef212569decde19f8650de8" }
        },
        input: {
		        title: "Reconfigure office layout"
        }
    ) {
      updatedCount
    }
}

// For any task in the project "619cbc23b9db097574d42c8c", set complete to true
mutation {
  updatetask(
    filter: {
      project: {eq: "619cbc23b9db097574d42c8c"}
    },
    input: {
      complete: true
    }
  ) {
    updatedCount
  }
}

Delete

Permanently delete one or more objects. A count of the number of updated objects is returned.

// Delete the project with the id "61813d19839f82002b44f8a0"
mutation {
    deleteproject(filter: {_id: {eq: "61813d19839f82002b44f8a0"}}) {
      deletedCount
    }
}

// Delete all projects that are completed
mutation {
    deleteproject(filter: {complete: {eq: true}}) {
      deletedCount
    }
}

Generate Random Identifiers

Generate random identifiers for objects created prior to enabling Random identifier on an Object Class in the Global data model. This operation is performed in batches.

For this mutation to work, GraphQL needs to be enabled, and the Update operation selected. In addition, the Enable GraphQL Auxiliary Endpoints setting you find under Environment needs to be switched on.

The first parameter references the node name of the built-in property random identifier.

The second parameter determines how large the batches will be. The maximum number is 1000.

Both parameters are required.

// Generate random identifiers for existing projects that don't have it
mutation {
    populateBuiltinPropertyProject(propertyId: af_randomId, maxUpdates: 2) {
        updatedCount
    }
}