Skip to content

API -- Relationship Editing

Relations are edited through nested mutation inputs.

Relation Actions

Each related item uses the _action field:

  • ADD → creates a relation and optional target row
  • EDIT → edits an existing related row
  • REMOVE → removes the relation only
  • DELETE → removes both relation and target row

Semantics

  • Relation mutations participate in the parent mutation transaction
  • All relation actions are validated by write rules

Examples

Assume:

  • person has a 1:n relation addresses
  • Target table is address

Creates a new address row and links it to the person.

mutation {
  edit_person(id: 123, input: {
    addresses: [
      {
        _action: ADD
        street: "Main Street 1"
        city: "Stockholm"
      }
    ]
  }) {
    id
  }
}

Result:

  • New address row is created
  • Relation between person and address is created

Links an existing address row without creating a new one.

mutation {
  edit_person(id: 123, input: {
    addresses: [
      {
        _action: ADD
        id: 987
      }
    ]
  })
}

Result:

  • No new row is created
  • Only the relation edge is created

Edits the related address row through the relation.

mutation {
  edit_person(id: 123, input: {
    addresses: [
      {
        _action: EDIT
        id: 987
        city: "Gothenburg"
      }
    ]
  })
}

Result:

  • The address row is updated
  • The relation remains unchanged

REMOVE — Remove Relation Only

Removes the relation but keeps the related row.

mutation {
  edit_person(id: 123, input: {
    addresses: [
      {
        _action: REMOVE
        id: 987
      }
    ]
  })
}

Result:

  • The relation is removed
  • The address row still exists

DELETE — Remove Relation and Target Row

Removes both the relation and the related row.

mutation {
  edit_person(id: 123, input: {
    addresses: [
      {
        _action: DELETE
        id: 987
      }
    ]
  })
}

Result:

  • The relation is removed
  • The address row is deleted