Skip to main content
Version: v2.x

API Reference - Mutation

insert (upsert) syntax

mutation [<mutation-name>] {
<mutation-field-name> (
[<input-object>!]
[conflict-clause]
)
[mutation-response!]
}
KeyRequiredSchemaDescription
mutation-namefalseValueName of mutation for observability
mutation-field-nametrueValueName of the auto-generated mutation field, e.g. insert_author
input-objecttrueInputObjectsName of the auto-generated mutation field
mutation-responsetrueMutationResponseObject to be returned after mutation succeeds
on-conflictfalseConflictClauseConverts 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!]
}
KeyRequiredSchemaDescription
mutation-namefalseValueName of mutation for observability
mutation-field-nametrueValueName of the auto-generated mutation field, e.g. insert_author_one
input-objecttrueInputObjectName of the auto-generated mutation field
mutation-responsetrueSimpleObjectObject to be returned after mutation succeeds
on-conflictfalseConflictClauseConverts 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>
}
KeyRequiredSchemaDescription
mutation-namefalseValueName of mutation for observability
mutation-field-nametrueValueName of the auto-generated update mutation field, e.g. update_author_by_pk
pk-columns-argumenttruepkColumnsArgExpPrimary key(s) for row(s) to be updated
set-argumentfalsesetArgExpData to be updated in the table
inc-argumentfalseincArgExpInteger value to be incremented to Int columns in the table (Negative integers can be used to decrement)
append-argumentfalseappendArgExpJSON value to be appended to JSONB columns in the table
prepend-argumentfalseprependArgExpJSON value to be prepended to JSONB columns in the table
delete-key-argumentfalsedeleteKeyArgExpKey to be deleted in the value of JSONB columns in the table
delete-elem-argumentfalsedeleteElemArgExpArray element to be deleted in the value of JSONB columns in the table
delete-at-path-argumentfalsedeleteAtPathArgExpElement 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!]
}
KeyRequiredSchemaDescription
mutation-namefalseValueName of mutation for observability
mutation-field-nametrueValueName of the auto-generated update mutation field, e.g. update_author
where-argumenttruewhereArgExpSelection criteria for rows to be updated
set-argumentfalsesetArgExpData to be updated in the table
inc-argumentfalseincArgExpInteger value to be incremented to Int columns in the table
append-argumentfalseappendArgExpJSON value to be appended to JSONB columns in the table
prepend-argumentfalseprependArgExpJSON value to be prepended to JSONB columns in the table
delete-key-argumentfalsedeleteKeyArgExpKey to be deleted in the value of JSONB columns in the table
delete-elem-argumentfalsedeleteElemArgExpArray element to be deleted in the value of JSONB columns in the table
delete-at-path-argumentfalsedeleteAtPathArgExpElement at path to be deleted in the value of JSONB columns in the table
mutation-responsetrueMutationResponseObject 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>
}
KeyRequiredSchemaDescription
mutation-namefalseValueName of mutation for observability
mutation-field-nametrueValueName 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!]
}
KeyRequiredSchemaDescription
mutation-namefalseValueName of mutation for observability
mutation-field-nametrueValueName of the auto-generated delete mutation field, e.g. delete_author
where-argumenttruewhereArgExpSelection criteria for rows to delete
mutation-responsetrueMutationResponseObject 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
{
  _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"],
..
}