GraphQL mutations

Mutations modify project data. Use a disposable project, a write-capable subject, and a known target record when learning the API.

Build an operation

1. Open Explorer’s mutation root and locate the generated create, update, or delete operation for your entity.
2. Inspect its input type and required fields.
3. For update/delete, filter by a known _id; do not start with an unbounded mutation.
4. Supply values through variables and select the returned fields needed to verify the change.
5. Execute once, inspect errors and returned counts/data, then read the target record again.

Update a known tutorial product

After creating BAG-001 in the tutorial, use its unique SKU to bound this update:

mutation ReviewTutorialProduct($sku: String!, $status: String!) {
  updateProducts(where: { sku: { eq: $sku } }, update: { status: { set: $status } }) {
    products {
      _id
      sku
      status
    }
  }
}

{ "sku": "BAG-001", "status": "reviewed" }

This changes a global field for the matching record. It does not approve or publish data through an independent business workflow; reviewed is a tutorial value. Read the returned product and then query it again to verify persistence. Restore draft with the same bounded operation if you want to repeat the exercise.

Relationships and scopes

Connecting an existing related record, disconnecting a relationship, creating a related record, and deleting its target have different effects. Use the generated relationship input rather than assigning a display label as though it were a foreign-key ID.

Local values and relationship-scoped attributes follow their generated input shapes. Inspect those types alongside the schema modeling guide.

Failure and retries

A failed client request does not establish that no change occurred. Read the target before retrying, particularly after a timeout. Check role, spaces, schema validation, and project restrictions.

For recurring application workflows, put authorization and duplicate handling in the application design. An API response is not a transaction across unrelated external services.