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 | OnConflictClause | In Postgres, converts insert to upsert by handling conflict |
if-matched | false | IfMatchedClause | In MS SQL Server, converts insert to upsert using a match |
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 | SimpleObject | Object to be returned after mutation succeeds |
on-conflict | false | OnConflictClause | In Postgres, converts insert to upsert by handling conflict |
if-matched | false | IfMatchedClause | In MS SQL Server, converts insert to upsert using a match |
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
}
}
}
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 for Postgres
The on_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 on_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}}
}
if_matched argument for MS SQL Server
The if_matched
clause is used to convert an insert mutation to an upsert mutation. Upsert respects the table's
update permissions before editing a matched row. Hence the if_matched
clause is permitted only if a table has
update permissions defined.
if_matched: {
match_columns: table_match_column! | [table_match_column!]!
update_columns: table_update_column! | [table_update_column!]!
where: table_bool_exp
}
Example
if_matched: {
match_columns: id
update_columns: [name]
where: {id: {_eq: 7}}
}
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: {}})
{}
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"],
..
}