Mutate

Mutations change the database in someway by creating, updating, or deleting a resource. You might use a mutation to update a personnel class, or in to a BPMN workflow that automatically creates records of incoming material lots.

Rhize supports the following ways to change the API.

add

Mutations that start with add create a resource on the server.

For example, this mutation adds one more items of equipment. To add multiple, send the variable as an array of objects, rather than a single object. The numUids property reports how many new objects were created.

mutation AddEquipment($input: [AddEquipmentInput!]!) {
  addEquipment(input: $input) {
    equipment {
      id
      label
    }
    numUids
  }
}

{

  "input": {
    "id": "Kitchen_mixer_a_20",
    "label": "Kitchen mixer A11"
  }
}

{

  "input": [{
    "id": "Kitchen_mixer_b_01",
    "label": "Kitchen mixer A11"
  },{
    "id": "Kitchen_mixer_b_02",
    "label": "Kitchen mixer A12"
  },
  ]
}

upsert

Many add operations support upserting, which update or insert (create). That is, if the object already exists, the operation will update it with the additional fields. If the object doesn’t exist, the operation will create it.

Besides general UX convenience, upsert is useful when data comes from multiple sources and in no guaranteed order, like from multiple streams from the message broker.

To enable upsert, set the upsert: argument to true:

addEquipment(input: $input, upsert: true)

update

Mutations that start with update change something in an object that already exists. The update operations can use filters.

For example, this operation updates the description for a specific version of an equipment item.

mutation updateMixerVersion( $updateEquipmentVersionInput2: UpdateEquipmentVersionInput!){
  updateEquipmentVersion(input: $updateEquipmentVersionInput2) {
    equipmentVersion {
      description
      id
    }
  }
}

{
  "updateEquipmentVersionInput2": {
    "filter": {"iid":"0xcc701"},
    "set": {
      "description": "Second generation of the mixer 9000"
    }
  }
}

delete

Mutations that start with delete remove a resource from the database. The delete operations can use filters.

For example, this operation deletes a unit of measure:

mutation deleteUoM($filter: UnitOfMeasureFilter!){
  deleteUnitOfMeasure(filter: $filter) {
    numUids
  }
}

{
  "filter": {
    "id": {
      "eq": "example unit of measure"
    }
  }
}

Deep mutations

You can perform deep mutations at multiple levels. Deep mutations don’t alter linked objects but can add nested new objects or link to existing objects.

For example, this mutation creates a new version of equipment, and associates a new item of equipment with it. Both the equipmentVersion and the equipment did not exist in the database.

  mutation AddEquipmentVersion($addEquipmentVersionInput2: [AddEquipmentVersionInput!]!) {
  addEquipmentVersion(input: $addEquipmentVersionInput2) {
    equipmentVersion {
      id
      equipment {
        id
      }
    }
  }
}

Variables:

  "addEquipmentVersionInput2": {
    "id": "widget_machine_version_1",
    "version": "1",
    "versionStatus": "DRAFT",
    "equipment": {
      "id": "widget_maker_1",
      "label": "Widget maker 1"

    }
  }
}

You can confirm that the record and its nested property exists with a get query. If the preceding operation succeeded, this query returns both the new Widget Maker and its corresponding version:

query{
  getEquipment(id: "widget_maker_1") {
    id
    versions{
      id
      version
    }
  }
}

{
  "addEquipmentVersionInput2": {
    "id": "widget_machine_version_1",
    "version": "1",
    "versionStatus": "DRAFT",
    "equipment": {
      "id": "widget_maker_1",
      "label": "Widget maker 1"

    }
  }
}

To update an existing nested object, use the update mutation for its type.