Insert mutation¶
Table of contents
- Auto-generated insert mutation schema
- Insert a single object
- Insert multiple objects of the same type in the same mutation
- Insert an object and get a nested object in response
- Insert an object along with its related objects through relationships
- Insert an object with a JSONB field
- Insert an object with an ARRAY field
- Set a field to its default value during insert
- Set a field to NULL during insert
Auto-generated insert mutation schema¶
For example, the auto-generated schema for the insert mutation field for a table article
looks like the following:
insert_article (
objects: [article_insert_input!]!
on_conflict: article_on_conflict
): article_mutation_response
# response of any mutation on the table "article"
type article_mutation_response {
# number of affected rows by the mutation
affected_rows: Int!
# data of the affected rows by the mutation
returning: [article!]!
}
# single object insert (supported from v1.2.0)
insert_article_one (
object: article_insert_input!
on_conflict: article_on_conflict
): article
As you can see from the schema:
objects
argument is necessary and you can pass multipleobjects
to the mutation.- You can pass an
on_conflict
argument to convert the mutation to an upsert mutation. - You can return the number of affected rows and the affected objects (with nested objects) in the response.
- You can use the single object insert to get the inserted object directly as the mutation response.
See the insert mutation API reference for the full specifications.
Note
If a table is not in the public
Postgres schema, the insert mutation field will be of the format
insert_<schema_name>_<table_name>
.
Insert a single object¶
Example: Insert a new article
object and return the inserted article object in the response:
mutation insert_single_article {
insert_article_one(
object: {
title: "Article 1",
content: "Sample article content",
author_id: 3
}
) {
id
title
}
}
Using variables:
mutation insert_single_article($object: article_insert_input! ) {
insert_article_one(object: $object) {
id
title
}
}
with variables:
{
"object": {
"title": "Article 1",
"content": "Sample article content",
"author_id": 3
}
}
Note
insert_<object>_one
will only be available if you have select permissions on the table, as it returns the inserted row.
Supported from
The insert_<object>_one
mutation is supported in versions v1.2.0
and above.
Insert multiple objects of the same type in the same mutation¶
Example: Insert 2 new article
objects and return both the article objects in the response:
mutation insert_multiple_articles {
insert_article(
objects: [
{
title: "Article 2",
content: "Sample article content",
author_id: 4
},
{
title: "Article 3",
content: "Sample article content",
author_id: 5
}
]
) {
returning {
id
title
}
}
}
Using variables:
mutation insert_multiple_articles($objects: [article_insert_input!]! ) {
insert_article(objects: $objects) {
returning {
id
title
}
}
}
with variables:
{
"objects": [
{
"title": "Article 2",
"content": "Sample article content",
"author_id": 4
},
{
"title": "Article 3",
"content": "Sample article content",
"author_id": 5
}
]
}
Insert an object and get a nested object in response¶
Example: Insert a new article
object and return the inserted article object with its author in the response:
mutation insert_article {
insert_article(
objects: [
{
title: "Article 1",
content: "Sample article content",
author_id: 3
}
]
) {
returning {
id
title
author {
id
name
}
}
}
}
Insert an object with a JSONB field¶
Example: Insert a new author
object with a JSONB address
field:
mutation insert_author($address: jsonb) {
insert_author (
objects: [
{
name: "Ash",
address: $address
}
]
) {
affected_rows
returning {
id
name
address
}
}
}
with variables:
{
"address": {
"street_address": "161, 19th Main Road, Koramangala 6th Block",
"city": "Bengaluru",
"phone": "9090909090",
"state": "Karnataka",
"pincode": 560095
}
}
Insert an object with an ARRAY field¶
To insert fields of array types, you currently have to pass them as a Postgres array literal.
Example: Insert a new author
with a text array emails
field:
mutation insert_author {
insert_author (
objects: [
{
name: "Ash",
emails: "{[email protected], [email protected]}"
}
]
) {
affected_rows
returning {
id
name
emails
}
}
}
Using variables:
mutation insert_author($emails: _text) {
insert_author (
objects: [
{
name: "Ash",
emails: $emails
}
]
) {
affected_rows
returning {
id
name
emails
}
}
}
with variables:
{
"emails": "{[email protected], [email protected]}"
}
Set a field to its default value during insert¶
To set a field to its default
value, just omit it from the input object, irrespective of the
default value configuration i.e. via Postgres defaults or using column presets.
Example: If the default value of id
is set to auto-incrementing integer, there’s no need to pass the id
field to the input object:
mutation insert_article_with_def_id {
insert_article(
objects: [
{
title: "Article 1",
content: "Sample article content",
author_id: 3
}
]
) {
returning {
id
title
}
}
}
Set a field to NULL during insert¶
If a field is nullable
in the database, to set its value to null
, either pass its value as null
or
just omit it from the input object.
Example: If age
is a nullable field, to set it to null
, either don’t pass the age field to the input object
or pass it as null
:
mutation insert_author_with_null_age {
insert_author(
objects: [
{
name: "Jeff"
}
]
) {
returning {
id
name
age
}
}
}
OR
mutation insert_author_with_null_age {
insert_author(
objects: [
{
name: "Jeff",
age: null
}
]
) {
returning {
id
name
age
}
}
}