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"],
..
}