diff --git a/docs/graphql/manual/api-reference/postgresql-types.rst b/docs/graphql/manual/api-reference/postgresql-types.rst index 1d2ed6cc7ee..ecc33853e5a 100644 --- a/docs/graphql/manual/api-reference/postgresql-types.rst +++ b/docs/graphql/manual/api-reference/postgresql-types.rst @@ -33,7 +33,6 @@ E.g. objects: [ { - id: 1, int_col: 27 } ] @@ -50,7 +49,6 @@ E.g. objects: [ { - id: 1, float_col: 0.8 } ] @@ -67,7 +65,6 @@ E.g. objects: [ { - id: 1, numeric_col: 0.00000008 } ] @@ -84,7 +81,6 @@ E.g. objects: [ { - id: 1, is_published: true } ] @@ -101,7 +97,6 @@ E.g. objects: [ { - id: 1, char_column: "a" } ] @@ -120,7 +115,6 @@ E.g. objects: [ { - id: 1, name: "Raven" } ] @@ -138,7 +132,6 @@ E.g. objects: [ { - id: 1, date: "1996-03-15" } ] @@ -156,7 +149,6 @@ E.g. objects: [ { - id: 1, time: "17:30:15+05:30" } ] @@ -174,7 +166,6 @@ E.g. objects: [ { - id: 1, timestamptz_col: "2016-07-20T17:30:15+05:30" } ] @@ -191,7 +182,6 @@ E.g. objects: [ { - id: 1, json_col: "{ \"name\": \"raven\" }" } ] @@ -210,15 +200,13 @@ E.g. insert_test( objects: [ { - id: 1, jsonb_col: $value } ] ) { affected_rows returning{ - id - details + jsonb_col } } } @@ -322,7 +310,6 @@ In ISO 8601 format objects: [ { - id: 1, time_col: "04:05:06.789" } ] @@ -333,7 +320,6 @@ E.g. For macaddr type objects: [ { - id: 1, macaddr_col: "08:00:2b:01:02:03" } ] diff --git a/docs/graphql/manual/getting-started/first-graphql-query.rst b/docs/graphql/manual/getting-started/first-graphql-query.rst index 50ba7e2194a..e58e1506b01 100644 --- a/docs/graphql/manual/getting-started/first-graphql-query.rst +++ b/docs/graphql/manual/getting-started/first-graphql-query.rst @@ -23,7 +23,7 @@ the following columns: .. code-block:: sql profile ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, -- serial -> auto-incrementing integer name TEXT ) diff --git a/docs/graphql/manual/mutations/insert.rst b/docs/graphql/manual/mutations/insert.rst index ac661792a20..1848f966c7a 100644 --- a/docs/graphql/manual/mutations/insert.rst +++ b/docs/graphql/manual/mutations/insert.rst @@ -62,7 +62,6 @@ Insert a single object mutation insert_single_article { insert_article_one( object: { - id: 21, title: "Article 1", content: "Sample article content", author_id: 3 @@ -105,7 +104,6 @@ Using variables: :variables: { "object": { - "id": 21, "title": "Article 1", "content": "Sample article content", "author_id": 3 @@ -128,13 +126,11 @@ Insert multiple objects of the same type in the same mutation insert_article( objects: [ { - id: 22, title: "Article 2", content: "Sample article content", author_id: 4 }, { - id: 23, title: "Article 3", content: "Sample article content", author_id: 5 @@ -201,13 +197,11 @@ Using variables: { "objects": [ { - "id": 22, "title": "Article 2", "content": "Sample article content", "author_id": 4 }, { - "id": 23, "title": "Article 3", "content": "Sample article content", "author_id": 5 @@ -227,7 +221,6 @@ Insert an object and get a nested object in response insert_article( objects: [ { - id: 21, title: "Article 1", content: "Sample article content", author_id: 3 @@ -283,23 +276,19 @@ Let's say an ``author`` has an ``object relationship`` called ``address`` to the insert_authors (objects: [ { - id: 26, name: "John", address: { data: { - id: 27, location: "San Francisco" } }, articles: { data: [ { - id: 28, title: "GraphQL Guide", content: "Let's see what we can do with GraphQL" }, { - id: 29, title: "Authentication Guide", content: "Let's look at best practices for authentication" } @@ -387,7 +376,6 @@ a bridge table ``article_tags``. mutation insertArticle { insert_articles(objects: [ { - id: 34, title: "How to make fajitas", content: "Guide on making the best fajitas in the world", author_id: 3, @@ -497,7 +485,6 @@ Insert an object with a JSONB field insert_author ( objects: [ { - id: 1, name: "Ash", address: $address } @@ -557,7 +544,6 @@ To insert fields of array types, you currently have to pass them as a `Postgres insert_author ( objects: [ { - id: 1, name: "Ash", emails: "{ash@ash.com, ash123@ash.com}" } @@ -597,7 +583,6 @@ Using variables: insert_author ( objects: [ { - id: 1, name: "Ash", emails: $emails } diff --git a/docs/graphql/manual/mutations/multiple-mutations.rst b/docs/graphql/manual/mutations/multiple-mutations.rst index 6ae90febfc6..18ddd9cda13 100644 --- a/docs/graphql/manual/mutations/multiple-mutations.rst +++ b/docs/graphql/manual/mutations/multiple-mutations.rst @@ -79,12 +79,10 @@ in the response: insert_article( objects: [ { - id: 21, title: "Article 1", content: "Sample article content", author: { data: { - id: 11, name: "Cory" } } diff --git a/docs/graphql/manual/mutations/upsert.rst b/docs/graphql/manual/mutations/upsert.rst index 51208e775c1..f66cd53e57e 100644 --- a/docs/graphql/manual/mutations/upsert.rst +++ b/docs/graphql/manual/mutations/upsert.rst @@ -11,6 +11,9 @@ Upsert mutation :backlinks: none :depth: 1 :local: + +Introduction +------------ An upsert query will insert an object into the database in case there is no conflict with another row in the table. In case there is a conflict with one or more rows, it will either update the fields of the conflicted rows or ignore @@ -63,8 +66,11 @@ If not all required columns are present, an error like ``NULL value unexpected f Update selected columns on conflict ----------------------------------- -Insert a new object in the ``article`` table or, if the primary key constraint ``article_pkey`` is violated, update -the columns specified in ``update_columns``: + +The ``update_columns`` field can be used to specify which columns to update in case a conflict occurs. + +**Example**: Insert a new object in the ``article`` table or, if the unique constraint ``article_title_key`` is +violated, update the ``content`` column of the existing article: .. graphiql:: :view_only: @@ -73,15 +79,14 @@ the columns specified in ``update_columns``: insert_article ( objects: [ { - id: 2, - title: "ex quis mattis", - content: "Pellentesque lobortis quam non leo faucibus efficitur", + title: "Article 1", + content: "Article 1 content", published_on: "2018-10-12" } ], on_conflict: { - constraint: article_pkey, - update_columns: [title, content] + constraint: article_title_key, + update_columns: [content] } ) { returning { @@ -98,23 +103,27 @@ the columns specified in ``update_columns``: "insert_article": { "returning": [ { - "id": 2, - "title": "ex quis mattis", - "content": "Pellentesque lobortis quam non leo faucibus efficitur", - "published_on": "2018-06-10" + "id": 1, + "title": "Article 1", + "content": "Article 1 content", + "published_on": "2018-06-15" } ] } } } -The ``published_on`` column is left unchanged as it wasn't present in ``update_columns``. +Note that the ``published_on`` column is left unchanged as it wasn't present in ``update_columns``. Update selected columns on conflict using a filter -------------------------------------------------- -Insert a new object in the ``article`` table, or if the primary key constraint ``article_pkey`` is violated, update -the columns specified in ``update_columns`` only if the provided ``where`` condition is met: +A ``where`` condition can be added to the ``on_conflict`` clause to check a condition before making the update in case a +conflict occurs + +**Example**: Insert a new object in the ``article`` table, or if the unique key constraint ``article_title_key`` is +violated, update the ``published_on`` columns specified in ``update_columns`` only if the previous ``published_on`` +value is lesser than the new value: .. graphiql:: :view_only: @@ -123,12 +132,12 @@ the columns specified in ``update_columns`` only if the provided ``where`` condi insert_article ( objects: [ { - id: 2, + title: "Article 2", published_on: "2018-10-12" } ], on_conflict: { - constraint: article_pkey, + constraint: article_title_key, update_columns: [published_on], where: { published_on: {_lt: "2018-10-12"} @@ -137,6 +146,7 @@ the columns specified in ``update_columns`` only if the provided ``where`` condi ) { returning { id + title published_on } } @@ -148,6 +158,7 @@ the columns specified in ``update_columns`` only if the provided ``where`` condi "returning": [ { "id": 2, + "title": "Article 2", "published_on": "2018-10-12" } ] @@ -155,12 +166,12 @@ the columns specified in ``update_columns`` only if the provided ``where`` condi } } -The ``published_on`` column is updated only if the new value is greater than the old value. - Ignore request on conflict -------------------------- -If ``update_columns`` is an **empty array** then the GraphQL engine ignores changes on conflict. Insert a new object into -the author table or, if the unique constraint ``author_name_key`` is violated, ignore the request. +If ``update_columns`` is an **empty array** then on conflict the changes are ignored. + +**Example**: Insert a new object into the author table or, if the unique constraint ``author_name_key`` is violated, +ignore the request. .. graphiql:: :view_only: @@ -168,7 +179,7 @@ the author table or, if the unique constraint ``author_name_key`` is violated, i mutation upsert_author { insert_author( objects: [ - {name: "John", id: 10} + { name: "John" } ], on_conflict: { constraint: author_name_key, @@ -194,6 +205,8 @@ Upsert in nested mutations -------------------------- You can specify the ``on_conflict`` clause while inserting nested objects: +**Example**: + .. graphiql:: :view_only: :query: @@ -201,19 +214,17 @@ You can specify the ``on_conflict`` clause while inserting nested objects: insert_author( objects: [ { - id: 10, name: "John", articles: { data: [ { - id: 1, - title: "Article 1 title", - content: "Article 1 content" + title: "Article 3", + content: "Article 3 content" } ], on_conflict: { - constraint: article_pkey, - update_columns: [title, content] + constraint: article_title_key, + update_columns: [content] } } } diff --git a/docs/graphql/manual/schema/basics.rst b/docs/graphql/manual/schema/basics.rst index 6082cfc2835..43890f6a0ae 100644 --- a/docs/graphql/manual/schema/basics.rst +++ b/docs/graphql/manual/schema/basics.rst @@ -23,12 +23,12 @@ Let's say we want to create two simple tables for an article/author schema: .. code-block:: sql author ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, name TEXT ) article ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, title TEXT, content TEXT, rating INT, @@ -150,17 +150,29 @@ Here are a couple of examples: mutation add_author { insert_author( objects: [ - {id: 11, name: "Jane"} + { name: "Jane" } ] ) { affected_rows + returning { + id + name + } } } :response: { "data": { "insert_author": { - "affected_rows": 1 + "affected_rows": 1, + "returning": [ + { + "id": 11, + "name": "Jane" + } + ] } } } + +Note that the author's ``id`` does not need to passed as an input as it is of type ``serial`` (auto incrementing integer). diff --git a/docs/graphql/manual/schema/default-values/postgres-defaults.rst b/docs/graphql/manual/schema/default-values/postgres-defaults.rst index 7e4ccca1a54..14bcf940136 100644 --- a/docs/graphql/manual/schema/default-values/postgres-defaults.rst +++ b/docs/graphql/manual/schema/default-values/postgres-defaults.rst @@ -56,8 +56,38 @@ Step 2: Run an insert mutation Now if you do not pass the ``created_at`` field value while running an insert mutation on the ``article`` table, its value will be set automatically by Postgres. -.. thumbnail:: /img/graphql/manual/schema/default-value-response.png - :alt: Run an insert mutation +.. graphiql:: + :view_only: + :query: + mutation { + insert_article( + objects: [ + { + title: "GraphQL manual", + author_id: 11 + } + ]) { + returning { + id + title + created_at + } + } + } + :response: + { + "data": { + "insert_article": { + "returning": [ + { + "id": 12, + "title": "GraphQL manual", + "created_at": "2020-04-23T11:42:30.499315+00:00" + } + ] + } + } + } Also see -------- diff --git a/docs/graphql/manual/schema/relationships/database-modelling/many-to-many.rst b/docs/graphql/manual/schema/relationships/database-modelling/many-to-many.rst index 6d096527918..4b76248c969 100644 --- a/docs/graphql/manual/schema/relationships/database-modelling/many-to-many.rst +++ b/docs/graphql/manual/schema/relationships/database-modelling/many-to-many.rst @@ -20,13 +20,13 @@ Say we have the following two tables in our database schema: .. code-block:: sql article ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, title TEXT ... ) tag ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, tag_value TEXT ... ) diff --git a/docs/graphql/manual/schema/relationships/database-modelling/one-to-many.rst b/docs/graphql/manual/schema/relationships/database-modelling/one-to-many.rst index c9ba8bb5163..eacdf7b0fa1 100644 --- a/docs/graphql/manual/schema/relationships/database-modelling/one-to-many.rst +++ b/docs/graphql/manual/schema/relationships/database-modelling/one-to-many.rst @@ -19,12 +19,12 @@ Say we have the following two tables in our database schema: .. code-block:: sql author ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, name TEXT ) article ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, author_id INT title TEXT ... diff --git a/docs/graphql/manual/schema/relationships/database-modelling/one-to-one.rst b/docs/graphql/manual/schema/relationships/database-modelling/one-to-one.rst index d0b84acadd7..801673a32a3 100644 --- a/docs/graphql/manual/schema/relationships/database-modelling/one-to-one.rst +++ b/docs/graphql/manual/schema/relationships/database-modelling/one-to-one.rst @@ -19,12 +19,12 @@ Say we have the following two tables in our database schema: .. code-block:: sql author ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, name TEXT ) passport_info ( - id INT PRIMARY KEY, + id SERIAL PRIMARY KEY, owner_id INT NOT NULL passport_number TEXT ... diff --git a/docs/img/graphql/manual/schema/default-value-response.png b/docs/img/graphql/manual/schema/default-value-response.png deleted file mode 100644 index c711ab40907..00000000000 Binary files a/docs/img/graphql/manual/schema/default-value-response.png and /dev/null differ