API Reference - Mutation

insert (upsert) syntax

mutation [<mutation-name>] {
  <mutation-field-name> (
    [<input-object>!]
    [conflict-clause]
  )
  [mutation-response!]
}
Key Required Schema Description
mutation-name false Value Name of mutation for observability
mutation-field-name true Value Name of the auto-generated mutation field, e.g. insert_author
input-object true InputObjects Name of the auto-generated mutation field
mutation-response true MutationResponse Object to be returned after mutation succeeds
on-conflict false ConflictClause Converts insert to upsert by handling conflict

Example: Insert

mutation insert_article {
  insert_article(
    objects: [
      {
        title: "Software is gluttonous",
        content: "Something happened in HP",
        author_id: 3
      }
    ]
  ) {
    returning {
      id
      title
    }
  }
}

Example: Upsert

mutation upsert_author {
  insert_author (
    objects: [
      {
        name: "John",
        id:12
      }
    ],
    on_conflict: {
      constraint: author_name_key,
      update_columns: [name, id]
    }
  ) {
    affected_rows
  }
}

insert_one syntax

mutation [<mutation-name>] {
  <mutation-field-name> (
    [<input-object>!]
    [conflict-clause]
  )
  [mutation-response!]
}
Key Required Schema Description
mutation-name false Value Name of mutation for observability
mutation-field-name true Value Name of the auto-generated mutation field, e.g. insert_author_one
input-object true InputObject Name of the auto-generated mutation field
mutation-response true Simple object Object to be returned after mutation succeeds
on-conflict false ConflictClause Converts insert to upsert by handling conflict

Example: Insert One

mutation insert_article_one {
  insert_article_one(
    object: {
      title: "Software is gluttonous",
      content: "Something happened in HP",
      author_id: 3
    }
  ) {
    id
    title
  }
}

update_by_pk syntax

mutation [<mutation-name>] {
  <mutation-field-name> (
    [pk-columns-argument!],
    [set-argument!]
  )
  <object-fields>
}
Key Required Schema Description
mutation-name false Value Name of mutation for observability
mutation-field-name true Value Name of the auto-generated update mutation field, e.g. update_author_by_pk
pk-columns-argument true pkColumnsArgExp Primary key(s) for row(s) to be updated
set-argument false setArgExp Data to be updated in the table
inc-argument false incArgExp Integer value to be incremented to Int columns in the table (Negative integers can be used to decrement)
append-argument false appendArgExp JSON value to be appended to JSONB columns in the table
prepend-argument false prependArgExp JSON value to be prepended to JSONB columns in the table
delete-key-argument false deleteKeyArgExp Key to be deleted in the value of JSONB columns in the table
delete-elem-argument false deleteElemArgExp Array element to be deleted in the value of JSONB columns in the table
delete-at-path-argument false deleteAtPathArgExp Element at path to be deleted in the value of JSONB columns in the table

Example: Update by PK

mutation update_articles {
  update_article_by_pk (
    pk_columns: {
      id: 1
    }
    _set: { is_published: true }
  ) {
    id
    title
  }
}

update syntax

mutation [<mutation-name>] {
  <mutation-field-name> (
    [where-argument!],
    [set-argument!]
  )
  [mutation-response!]
}
Key Required Schema Description
mutation-name false Value Name of mutation for observability
mutation-field-name true Value Name of the auto-generated update mutation field, e.g. update_author
where-argument true whereArgExp Selection criteria for rows to be updated
set-argument false setArgExp Data to be updated in the table
inc-argument false incArgExp Integer value to be incremented to Int columns in the table
append-argument false appendArgExp JSON value to be appended to JSONB columns in the table
prepend-argument false prependArgExp JSON value to be prepended to JSONB columns in the table
delete-key-argument false deleteKeyArgExp Key to be deleted in the value of JSONB columns in the table
delete-elem-argument false deleteElemArgExp Array element to be deleted in the value of JSONB columns in the table
delete-at-path-argument false deleteAtPathArgExp Element at path to be deleted in the value of JSONB columns in the table
mutation-response true MutationResponse Object to be returned after mutation succeeds

Example: Update

mutation update_author{
  update_author(
    where: {id: {_eq: 3}},
    _set: {name: "Jane"}
  ) {
    affected_rows
  }
}

delete_by_pk syntax

mutation [<mutation-name>] {
  <mutation-field-name> (
    column1: value1
    column2: value2
  )
  <object-fields>
}
Key Required Schema Description
mutation-name false Value Name of mutation for observability
mutation-field-name true Value Name of the auto-generated delete mutation field, e.g. delete_author_by_pk

Example: Delete by PK

mutation delete_articles {
  delete_article_by_pk (
    id: 1
  ) {
    id
    title
  }
}

delete syntax

mutation [<mutation-name>] {
  <mutation-field-name> (
    [where-argument!]
  )
  [mutation-response!]
}
Key Required Schema Description
mutation-name false Value Name of mutation for observability
mutation-field-name true Value Name of the auto-generated delete mutation field, e.g. delete_author
where-argument true whereArgExp Selection criteria for rows to delete
mutation-response true MutationResponse Object to be returned after mutation succeeds

Example: Delete

mutation delete_articles {
  delete_article(
    where: {author: {id: {_eq: 7}}}
  ) {
    affected_rows
    returning {
      id
    }
  }
}

Note

For more examples and details of usage, please see this.

Syntax definitions

Mutation response

{
  affected_rows
  returning {
    response-field1
    response-field2
    ..
  }
}

Example

{
  affected_rows
  returning {
    id
    author_id
  }
}

objects argument

objects: [
  {
    field1: value,
    field2: value,
    <object-rel-name>: {
      data: <Input-Object>!,
      on_conflict: <Conflict-Clause>
    },
    <array-rel-name>: {
      data: [<Input-Object>!]!,
      on_conflict: <Conflict-Clause>
    }
    ..
  },
  ..
]
# no nested objects

Example

objects: [
  {
    title: "Software is eating the world",
    content: "This week, Hewlett-Packard...",
    author: {
      data: {
        id: 1,
        name: "Sydney"
      }
    }
  }
]

object argument

object: {
  field1: value,
  field2: value,
  <object-rel-name>: {
    data: <Input-Object>!,
    on_conflict: <Conflict-Clause>
  },
  <array-rel-name>: {
    data: [<Input-Object>!]!,
    on_conflict: <Conflict-Clause>
  }
  ..
}

Example

object: {
  title: "Software is eating the world",
  content: "This week, Hewlett-Packard...",
  author: {
    data: {
      id: 1,
      name: "Sydney"
    }
  }
}

on_conflict argument

The conflict clause is used to convert an insert mutation to an upsert mutation. Upsert respects the table’s update permissions before editing an existing row in case of a conflict. Hence the conflict clause is permitted only if a table has update permissions defined.

on_conflict: {
  constraint: table_constraint!
  update_columns: [table_update_column!]!
  where: table_bool_exp
}

Example

on_conflict: {
  constraint: author_name_key
  update_columns: [name]
  where: {id: {_lt: 1}}
}

pk_columns argument

The pk_columns argument is used to identify an object by its primary key columns in update mutations.

pk_columns: {
  column-1: value-1
  column-2: value-2
}

Example

pk_columns: {
  id: 1
  name: "Harry"
}

where argument

where: BoolExp

Example

where: {
  rating: {_eq: 5}
}

BoolExp

AndExp | OrExp | NotExp | TrueExp | ColumnExp
AndExp
{
  _and: [BoolExp]
}

Example

_and: [
  {rating: {_gt: 5}},
  {updated_at: {_gt: "2019-01-01"}}
]
OrExp
{
  _or: [BoolExp]
}

Example

_or: [
  {rating: {_is_null: true}},
  {rating: {_lt: 4}}
]
NotExp
{
  _not: BoolExp
}

Example

_not: {
  title: {_eq: ""}
}
TrueExp
{}

Example

author(where: {articles: {}})

Note

{} evaluates to true whenever an object exists (even if it’s null).

ColumnExp
{
  field-name: {Operator: Value }
}

Example

{rating: {_eq: 5}}
Operator

Generic operators (all column types except json, jsonb):

  • _eq
  • _ne
  • _in
  • _nin
  • _gt
  • _lt
  • _gte
  • _lte

Text related operators:

  • _like
  • _nlike
  • _ilike
  • _nilike
  • _similar
  • _nsimilar
  • _iregex
  • _niregex
  • _regex
  • _nregex

Checking for NULL values:

  • _is_null (takes true/false as values)

_set argument

_set: {
  field-name-1 : value,
  field-name-2 : value,
  ..
}

_inc argument

_inc: {
  field-name-1 : int-value,
  field-name-2 : int-value,
  ..
}

_append argument

_append: {
  field-name-1 : $json-variable-1,
  field-name-2 : $json-variable-1,
  ..
}

Example

{
  "json-variable-1": "value",
  "json-variable-2": "value"
}

_prepend argument

_prepend: {
  field-name-1 : $json-variable-1,
  field-name-2 : $json-variable-1,
  ..
}

Example

{
  "json-variable-1": "value",
  "json-variable-2": "value"
}

_delete_key argument

_delete_key: {
  field-name-1 : "key",
  field-name-2 : "key",
  ..
}

_delete_elem argument

_delete_elem: {
  field-name-1 : int-index,
  field-name-2 : int-index,
  ..
}

_delete_at_path argument

_delete_at_path: {
  field-name-1 : ["path-array"],
  field-name-2 : ["path-array"],
  ..
}
« previous | next »
Want to contribute or report missing content?

Powered by Sphinx. | Copyright © 2021 Hasura.