2020-01-14 15:57:45 +03:00
.. meta ::
:description: Update an object in the database using a mutation
:keywords: hasura, docs, mutation, update
2020-03-11 22:42:36 +03:00
.. _update:
2018-09-11 14:11:24 +03:00
Update mutation
===============
2018-12-03 15:12:24 +03:00
.. contents :: Table of contents
:backlinks: none
:depth: 1
:local:
2019-01-21 12:20:14 +03:00
Auto-generated update mutation schema
-------------------------------------
2020-10-05 14:17:56 +03:00
**For example** , the auto-generated schema for the update mutation field for a table `` article `` looks like the following:
2018-12-03 15:12:24 +03:00
.. code-block :: graphql
update_article (
_inc: article_inc_input
_set: article_set_input
where: article_bool_exp!
): 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!
2020-05-18 14:13:57 +03:00
# data of the affected rows by the mutation
2018-12-03 15:12:24 +03:00
returning: [article!]!
}
2020-05-18 14:13:57 +03:00
# single object update (supported from v1.2.0)
update_article_by_pk (
_inc: article_inc_input
_set: article_set_input
# primary key columns arg
pk_columns: article_pk_columns_input!
): article
2018-12-03 15:12:24 +03:00
As you can see from the schema:
2020-03-11 22:42:36 +03:00
- The `` where `` argument is compulsory to filter rows to be updated. See :ref: `Filter queries <filter_queries>`
2018-12-03 15:12:24 +03:00
for filtering options. Objects can be updated based on filters on their own fields or those in their nested objects.
2019-04-17 16:37:42 +03:00
The `` {} `` expression can be used to update all rows.
2018-12-03 15:12:24 +03:00
- You can return the number of affected rows and the affected objects (with nested objects) in the response.
2018-09-11 14:11:24 +03:00
2019-09-11 10:17:14 +03:00
See the :ref: `update mutation API reference <update_syntax>` for the full specifications.
2019-02-06 09:39:36 +03:00
2018-09-11 14:11:24 +03:00
.. note ::
2019-01-21 12:20:14 +03:00
- At least any one of `` _set `` , `` _inc `` operators or the jsonb operators `` _append `` , `` _prepend `` , `` _delete_key `` ,
`` _delete_elem `` , `` _delete_at_path `` is required.
2019-03-22 10:08:42 +03:00
2019-01-21 12:20:14 +03:00
- If a table is not in the `` public `` Postgres schema, the update mutation field will be of the format
`` update_<schema_name>_<table_name> `` .
2018-09-11 14:11:24 +03:00
2020-05-18 14:13:57 +03:00
Update an object by its primary key
-----------------------------------
You can update a single object in a table using the primary key.
The output type is the nullable table object. The mutation returns the updated
row object or `` null `` if the row does not exist.
**Example:** Update an article where `` id `` is `` 1 `` :
.. graphiql ::
:view_only:
:query:
mutation update_an_article {
update_article_by_pk (
pk_columns: {id: 1}
_set: { is_published: true }
) {
id
is_published
}
}
:response:
{
"data": {
"update_article_by_pk": {
"id": 1,
"is_published": true
}
}
}
**Example:** Update a non-existent article:
.. graphiql ::
:view_only:
:query:
mutation update_an_article {
update_article_by_pk (
pk_columns: {id: 100}
_set: { is_published: true }
) {
id
is_published
}
}
:response:
{
"data": {
"update_article_by_pk": null
}
}
2020-06-24 10:01:31 +03:00
.. note ::
`` update_<table>_by_pk `` will **only** be available if you have select permissions on the table, as it returns the updated row.
2020-05-18 14:13:57 +03:00
.. admonition :: Supported from
The `` update_<table>_by_pk `` mutation is supported in versions `` v1.2.0 ``
and above.
Update objects based on their fields
------------------------------------
**Example:** Update the `` rating `` and `` is_published `` of articles with a low `` rating `` :
2018-09-11 14:11:24 +03:00
.. graphiql ::
:view_only:
:query:
2018-12-03 15:12:24 +03:00
mutation update_article {
update_article(
2020-05-18 14:13:57 +03:00
where: {rating: {_lte: 2}},
2018-12-03 15:12:24 +03:00
_set: {
2020-05-18 14:13:57 +03:00
rating: 1,
is_published: false
2018-12-03 15:12:24 +03:00
}
2018-09-11 14:11:24 +03:00
) {
affected_rows
2018-12-03 15:12:24 +03:00
returning {
id
title
content
rating
2020-05-18 14:13:57 +03:00
is_published
2018-12-03 15:12:24 +03:00
}
2018-09-11 14:11:24 +03:00
}
}
:response:
{
"data": {
2018-12-03 15:12:24 +03:00
"update_article": {
2020-05-18 14:13:57 +03:00
"affected_rows": 2,
2018-12-03 15:12:24 +03:00
"returning": [
{
"id": 3,
2020-05-18 14:13:57 +03:00
"title": "article 3",
"content": "lorem ipsum dolor sit amet",
"rating": 1,
"is_published": false
},
{
"id": 6,
"title": "article 6",
"content": "lorem ipsum dolor sit amet",
"rating": 1,
"is_published": false
2018-12-03 15:12:24 +03:00
}
]
2018-09-11 14:11:24 +03:00
}
}
}
2019-04-17 16:37:42 +03:00
Using variables:
2019-02-06 09:39:36 +03:00
.. graphiql ::
:view_only:
:query:
2020-05-18 14:13:57 +03:00
mutation update_article($rating: Int, $changes: article_set_input) {
2019-02-06 09:39:36 +03:00
update_article(
2020-05-18 14:13:57 +03:00
where: {rating: {_lte: $rating}},
2019-02-06 09:39:36 +03:00
_set: $changes
) {
affected_rows
returning {
id
title
content
rating
2020-05-18 14:13:57 +03:00
is_published
2019-02-06 09:39:36 +03:00
}
}
}
:response:
{
"data": {
"update_article": {
2020-05-18 14:13:57 +03:00
"affected_rows": 2,
2019-02-06 09:39:36 +03:00
"returning": [
{
"id": 3,
2020-05-18 14:13:57 +03:00
"title": "article 3",
"content": "lorem ipsum dolor sit amet",
"rating": 1,
"is_published": false
},
{
"id": 6,
"title": "article 6",
"content": "lorem ipsum dolor sit amet",
"rating": 1,
"is_published": false
2019-02-06 09:39:36 +03:00
}
]
}
}
}
:variables:
{
2020-05-18 14:13:57 +03:00
"rating": 2,
2019-02-06 09:39:36 +03:00
"changes": {
2020-05-18 14:13:57 +03:00
"rating": 1,
"is_published": false,
2019-02-06 09:39:36 +03:00
}
}
OR
.. graphiql ::
:view_only:
:query:
2020-05-18 14:13:57 +03:00
mutation update_article($ratingLimit: Int, $rating: Int, $isPublished: Boolean) {
2019-02-06 09:39:36 +03:00
update_article(
2020-05-18 14:13:57 +03:00
where: {rating: {_lte: $ratingLimit}},
2019-02-06 09:39:36 +03:00
_set: {
2020-05-18 14:13:57 +03:00
rating: $rating,
2020-10-13 14:07:46 +03:00
is_published: $isPublished
2019-02-06 09:39:36 +03:00
}
) {
affected_rows
returning {
id
title
content
rating
2020-05-18 14:13:57 +03:00
is_published
2019-02-06 09:39:36 +03:00
}
}
}
:response:
{
"data": {
"update_article": {
2020-05-18 14:13:57 +03:00
"affected_rows": 2,
2019-02-06 09:39:36 +03:00
"returning": [
{
"id": 3,
2020-05-18 14:13:57 +03:00
"title": "article 3",
"content": "lorem ipsum dolor sit amet",
"rating": 1,
"is_published": false
},
{
"id": 6,
"title": "article 6",
"content": "lorem ipsum dolor sit amet",
"rating": 1,
"is_published": false
2019-02-06 09:39:36 +03:00
}
]
}
}
}
:variables:
{
2020-05-18 14:13:57 +03:00
"ratingLimit": 2,
"rating": 1,
"isPublished": false
2019-02-06 09:39:36 +03:00
}
2020-05-18 14:13:57 +03:00
Update objects based on nested objects' fields
----------------------------------------------
2019-04-17 16:37:42 +03:00
**Example:** Reset the `` rating `` of all articles authored by "Sidney":
2018-09-11 14:11:24 +03:00
.. graphiql ::
:view_only:
:query:
mutation update_ratings {
update_article(
where: {author: {name: {_eq: "Sidney"}}},
2019-04-17 16:37:42 +03:00
_set: {rating: null}
2018-09-11 14:11:24 +03:00
) {
affected_rows
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 3
}
}
}
2019-04-17 16:37:42 +03:00
Update all objects
------------------
You can update all objects in a table using the `` {} `` expression as the `` where `` argument. `` {} `` basically
2019-09-11 10:17:14 +03:00
evaluates to `` true `` for all objects.
2019-04-17 16:37:42 +03:00
**Example:** Reset rating of all articles:
.. graphiql ::
:view_only:
:query:
mutation reset_rating {
update_article (
where: {}
_set: { rating: null }
) {
affected_rows
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 20
}
}
}
2018-12-03 15:12:24 +03:00
Increment **int** columns
-------------------------
You can increment an `` int `` column with a given value using the `` _inc `` operator.
2018-09-11 14:11:24 +03:00
2018-12-03 15:12:24 +03:00
**Example:** Increment the `` likes `` of an article by 2:
2018-09-11 14:11:24 +03:00
.. graphiql ::
:view_only:
:query:
mutation update_likes {
update_article(
where: {id: {_eq: 1}},
2018-12-03 15:12:24 +03:00
_inc: {likes: 2} # initial value: 1
2018-09-11 14:11:24 +03:00
) {
affected_rows
returning {
id
likes
}
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 1,
"returning": {
"id": 1,
2018-12-03 15:12:24 +03:00
"likes": 3
2018-09-11 14:11:24 +03:00
}
}
}
}
2018-12-03 15:12:24 +03:00
Update **jsonb** columns
------------------------
The currently available `` jsonb `` operators are:
+----------------------+------------------------+--------------------------------------------------+
| Operator | Postgres equivalent | Function |
+======================+========================+==================================================+
| `` _append `` | `` || `` | append json value to a `` jsonb `` column |
+----------------------+------------------------+--------------------------------------------------+
| `` _prepend `` | `` || `` | prepend json value to a `` jsonb `` column |
+----------------------+------------------------+--------------------------------------------------+
| `` _delete_key `` | `` - `` | delete top-level key from `` jsonb `` column |
+----------------------+------------------------+--------------------------------------------------+
| `` _delete_elem `` | `` - `` | delete array element from `` jsonb `` column |
+----------------------+------------------------+--------------------------------------------------+
| `` _delete_at_path `` | `` #- `` | delete element at a path from `` jsonb `` column |
+----------------------+------------------------+--------------------------------------------------+
2018-09-11 14:11:24 +03:00
.. note ::
2019-09-11 10:17:14 +03:00
You can learn more about Postgres jsonb operators `here <https://www.postgresql.org/docs/current/static/functions-json.html#FUNCTIONS-JSONB-OP-TABLE> `__ .
2018-12-03 15:12:24 +03:00
.. contents :: Examples
:backlinks: none
:depth: 1
:local:
2018-09-11 14:11:24 +03:00
2018-12-03 15:12:24 +03:00
Append a json to a jsonb column
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can append any `` jsonb `` column with another json value by using the `` _append `` operator.
2018-09-11 14:11:24 +03:00
2018-12-03 15:12:24 +03:00
Since the input is a json value, it should be provided through a variable.
2018-09-11 14:11:24 +03:00
2019-09-11 10:17:14 +03:00
**Example:** Append the json `` {"key1": "value1"} `` to the `` jsonb `` column `` extra_info `` of the `` article `` table:
2018-09-11 14:11:24 +03:00
.. graphiql ::
:view_only:
:query:
mutation update_extra_info($value: jsonb) {
update_article(
where: {id: {_eq: 1}},
2018-12-03 15:12:24 +03:00
_append: {extra_info: $value} # initial value: {"key": "value"}
2018-09-11 14:11:24 +03:00
) {
affected_rows
returning {
id
extra_info
}
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 1,
"returning": {
"id": 1,
"extra_info": {
2018-12-03 15:12:24 +03:00
"key": "value",
"key1": "value1"
2018-09-11 14:11:24 +03:00
}
}
}
}
}
2019-01-15 17:34:39 +03:00
:variables:
{
"value": { "key1": "value1" }
}
2018-09-11 14:11:24 +03:00
2018-12-03 15:12:24 +03:00
Prepend a json to a jsonb column
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can prepend any `` jsonb `` column with another json value by using the `` _prepend `` operator.
2018-09-11 14:11:24 +03:00
2018-12-03 15:12:24 +03:00
Since the input is a json value, it should be provided through a variable.
2019-09-11 10:17:14 +03:00
**Example:** Prepend the json `` {"key0": "value0"} `` to the `` jsonb `` column `` extra_info `` of the `` article `` table:
2018-09-11 14:11:24 +03:00
.. graphiql ::
:view_only:
:query:
mutation update_extra_info($value: jsonb) {
update_article(
where: {id: {_eq: 1}},
2018-12-03 15:12:24 +03:00
_prepend: {extra_info: $value} # initial value "{"key": "value", "key1": "value1"}"
2018-09-11 14:11:24 +03:00
) {
affected_rows
returning {
id
extra_info
}
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 1,
"returning": {
"id": 1,
"extra_info": {
"key0": "value0",
2018-12-03 15:12:24 +03:00
"key": "value",
"key1": "value1"
2018-09-11 14:11:24 +03:00
}
}
}
}
}
2019-01-15 17:34:39 +03:00
:variables:
{
"value": { "key0": "value0" }
}
2018-09-11 14:11:24 +03:00
2018-12-03 15:12:24 +03:00
Delete a top-level key from a jsonb column
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can delete a top-level key of a `` jsonb `` column by using the `` _delete_key `` operator.
2019-09-11 10:17:14 +03:00
The input value should be a `` String `` .
2018-09-11 14:11:24 +03:00
2019-09-11 10:17:14 +03:00
**Example:** Delete the key `` key `` in the `` jsonb `` column `` extra_info `` of the `` article `` table:
2018-09-11 14:11:24 +03:00
.. graphiql ::
:view_only:
:query:
mutation update_extra_info {
update_article(
where: {id: {_eq: 1}},
2018-12-03 15:12:24 +03:00
_delete_key: {extra_info: "key"} # initial value "{"key0": "value0, "key": "value", "key1": "value1"}"
2018-09-11 14:11:24 +03:00
) {
affected_rows
returning {
id
extra_info
}
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 1,
"returning": {
"id": 1,
"extra_info": {
2018-12-03 15:12:24 +03:00
"key0": "value0",
"key1": "value1"
2018-09-11 14:11:24 +03:00
}
}
}
}
}
2018-12-03 15:12:24 +03:00
Delete an element from a jsonb column storing a json array
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If a `` jsonb `` column is storing a json array, you can delete an element from the array using the `` _delete_elem ``
operator.
2018-09-11 14:11:24 +03:00
2019-09-11 10:17:14 +03:00
The input value should be an `` Int `` .
2018-12-03 15:12:24 +03:00
2019-09-11 10:17:14 +03:00
**Example:** Delete the element at position 2 in the array value of the `` jsonb `` column `` extra_info ``
of the `` article `` table:
2018-09-11 14:11:24 +03:00
.. graphiql ::
:view_only:
:query:
mutation update_extra_info {
update_article(
where: {id: {_eq: 1}},
2018-12-03 15:12:24 +03:00
_delete_elem: {extra_info: 2} # initial value "["a", "b", "c"]"
2018-09-11 14:11:24 +03:00
) {
affected_rows
returning {
id
extra_info
}
}
}
:response:
{
"data": {
"update_article": {
"affected_rows": 1,
"returning": {
"id": 1,
"extra_info": ["a", "b"]
}
}
}
}
2018-12-03 15:12:24 +03:00
Delete an element at a specific path in a jsonb column
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can delete a field or element of a `` jsonb `` column at a specified path by using the `` _delete_at_path `` operator.
2019-09-11 10:17:14 +03:00
The input value should be a `` String Array `` .
2018-09-11 14:11:24 +03:00
2019-09-11 10:17:14 +03:00
**Example:** Delete element at json path `` name.last `` in the `` jsonb `` column `` extra_info `` of the author table:
2018-09-11 14:11:24 +03:00
.. graphiql ::
:view_only:
:query:
mutation update_extra_info {
update_author(
where: {id: {_eq: 1}},
2018-12-03 15:12:24 +03:00
_delete_at_path: {extra_info: ["name", "first"]} # initial value "{"name": {"first": "first_name", "last": "last_name"}}"
2018-09-11 14:11:24 +03:00
) {
affected_rows
returning {
id
extra_info
}
}
}
:response:
{
"data": {
"update_author": {
"affected_rows": 1,
"returning": {
"id": 1,
"extra_info": {
"name": {
"last": "last_name"
}
}
}
}
}
}
2019-12-10 13:37:20 +03:00
Replace all nested array objects of an object
---------------------------------------------
In order to replace all existing nested array objects of an object, currently it's required to use two mutations:
one to delete all the existing objects and one to add a list of new nested objects.
**Example:** Replace all articles of an author with a new list:
.. graphiql ::
:view_only:
:query:
mutation updateAuthorArticles($author_id: Int!) {
delete_articles(
where: {author_id: {_eq: $author_id}}
) {
affected_rows
}
insert_articles(
objects: [
{
author_id: $author_id,
title: "title",
content: "some content"
},
{
author_id: $author_id,
title: "another title",
content: "some other content"
}
]
) {
affected_rows
}
}
:response:
{
"data": {
"delete_article_tags": {
"affected_rows": 3
},
"insert_article_tags": {
"affected_rows": 2
}
}
}
:variables:
{
"author_id": 21
}