Mutations

This tutorial will show you how to mutate (create/update/delete) objects in our API

GraphQL provides the concept of mutations, which allow users to update data on the server. Note that unlike REST, there are no distinctions between a create, update, or delete mutation. Rather GraphQL relies on the mutation name and documentation to understand what a particular mutation does.

In this example, we will loosely build off of the previous example of querying for monitors, by updating a monitor.

We highly recommend that you type out these examples (with your own ID's) in the API explorer directly.

The explorer helps with autocompletion and will help you understand the context of your queries. In addition, the Documentation Explorer on the right side will be your guide to the exact fields for each object.

First - query for a monitor

Here I'm using a monitor that is triggered from the previous example. You can find a monitor by following the example or by using the UI and grabbing the monitor id from the URL. (.../monitors/:monitor_id).

Request

query {
  node(id: "monitor_id"){
    ... on Monitor {
      name
      monitorCategory
      threshold
      currentMetricValue
      operator
      status
    }
  }
}

Response

{
  "data": {
    "node": {
      "name": "Model Drift for delinq_2yrs",
      "monitorCategory": "drift",
      "threshold": 0.000164044030786001,
      "currentMetricValue": "0.00049",
      "operator": "greaterThan",
      "status": "triggered"
    }
  }
}

Patch mutation

Let's say we want to update the threshold to be higher than the current value, which will clear the monitor.

Because our 3 types of monitors (Drift, Performance, and Data Quality) are all different, we have different mutations for each. This is a drift monitor, so we want the patchDriftMonitor mutation:

Request

mutation(
  $monitorId: ID!,
  $threshold: Float!,
) {
  patchDriftMonitor(
    input:{
      monitorId: $monitorId
      set:{
        threshold: $threshold
        autoThresholdEnabled: false
      }
    }
  ) {
    monitor {
      threshold
    }
  }
}

Query arguments:

{
  "monitorId": "monitor_id",
  "threshold": 0.0005
}

Response

{
  "data": {
    "patchDriftMonitor": {
      "monitor": {
        "threshold": 0.0005
      }
    }
  }
}

Here we split the query into two parts, a templatized mutation, and its arguments. Templates are useful for reusing queries or mutations and is a much cleaner and more type-safe than string interpolation.

The template:

mutation(
  $monitorId: ID!,
  $threshold: Float!
)

First, we establish the template for reusing this mutation. This template only takes the arguments monitorId, and threshold. Each field needs a type, and ! denotes that the field is required. Even though monitorId looks like a string, it is a special type in GraphQL which allows further validations.

The actual mutation

  patchDriftMonitor(
    input:{
      monitorId: $monitorId
      set:{
        threshold: $threshold
        autoThresholdEnabled: false
      }
    }
  )

Then we call the actual mutation, using () . From looking at the Documentation Explorer, we can tell the shape of the input, which can be nested. Here, we only set a few of the possible fields for this input. monitorId: $monitorId and threshold: $threshold use the input variables defined above, while autoThresholdEnabled: false is hardcoded.

Return the updated value

{
  monitor {
    threshold
  }
}

GraphQL allows you to specify a response query at the end of a mutation. This conveniently allows you to verify your mutation in the same call.

What's next?

While we only showed how to make a single change to a monitor, mutations allow you to update or create monitors in bulk.

For much more detailed and advanced examples for your use case, please consult our various Colabs.

Having trouble? Reach out to us via email [e-mail] or Slack us in the #arize-support channel for more support.