Merge branch 'master' into 4547-introspection-reuse-variables

Author: Auke Booij

CHANGELOG.md

@@ -66,6 +66,7 @@ Read more about the session argument for computed fields in the [docs](https://h
 - cli: list all available commands in root command help (fix #4623)
 - docs: add section on actions vs. remote schemas to actions documentation (#4284)
 - docs: fix wrong info about excluding scheme in CORS config (#4685)
+- docs: add single object mutations docs (close #4622) (#4625)
 - docs: add docs page on query performance (close #2316) (#3693)
 - docs: add a sample Caddyfile for Caddy 2 in enable-https section (#4710)
 

docs/graphql/manual/api-reference/graphql-api/mutation.rst

@@ -11,11 +11,11 @@ API Reference - Mutation
   :backlinks: none
   :depth: 2
   :local:
-
+ 
 .. _insert_upsert_syntax:
 
-Insert / upsert syntax
-----------------------
+**insert** (upsert) syntax
+--------------------------
 
 .. code-block:: none
 
@@ -99,8 +99,8 @@ Insert / upsert syntax
 
 .. _insert_upsert_one_syntax:
 
-Insert / upsert one syntax
---------------------------
+**insert_one** syntax
+---------------------
 
 .. code-block:: none
 
@@ -157,11 +157,89 @@ Insert / upsert one syntax
       }
     }
 
+.. _update_by_pk_syntax:
+
+**update_by_pk** syntax
+-----------------------
+
+.. code-block:: none
+
+    mutation [<mutation-name>] {
+      <mutation-field-name> (
+        [pk-columns-argument!],
+        [set-argument!]
+      )
+      <object-fields>
+    }
+
+.. list-table::
+   :header-rows: 1
+
+   * - 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
+   * - 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
+
+**E.g. UPDATE BY PK**:
+
+.. code-block:: graphql
+
+    mutation update_articles {
+      update_article_by_pk (
+        pk_columns: {
+          id: 1
+        }
+        _set: { is_published: true }
+      ) {
+        id
+        title
+      }
+    }
 
 .. _update_syntax:
 
-Update syntax
--------------
+**update** syntax
+-----------------
 
 .. code-block:: none
 
@@ -238,10 +316,54 @@ Update syntax
       }
     }
 
+.. _delete_by_pk_syntax:
+
+**delete_by_pk** syntax
+-----------------------
+
+.. code-block:: none
+
+    mutation [<mutation-name>] {
+      <mutation-field-name> (
+        column1: value1
+        column2: value2
+      )
+      <object-fields>
+    }
+
+.. list-table::
+   :header-rows: 1
+
+   * - 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*
+
+**E.g. DELETE BY PK**:
+
+.. code-block:: graphql
+
+    mutation delete_articles {
+      delete_article_by_pk (
+        id: 1
+      ) {
+        id
+        title
+      }
+    }
+
 .. _delete_syntax:
 
-Delete syntax
--------------
+**delete** syntax
+-----------------
 
 .. code-block:: none
 
@@ -431,6 +553,29 @@ E.g.:
       where: {id: {_lt: 1}}
     }
 
+.. _pkColumnsArgExp:
+
+**pk_columns** argument
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``pk_columns`` argument is used to identify an object by its primary key columns in *update* mutations. 
+
+.. code-block:: none
+
+    pk_columns: {
+      column-1: value-1
+      column-2: value-2
+    }
+
+E.g.:
+
+.. code-block:: graphql
+
+    pk_columns: {
+      id: 1
+      name: "Harry"
+    }
+
 .. _whereArgExp:
 
 **where** argument

docs/graphql/manual/api-reference/graphql-api/query.rst

@@ -12,8 +12,8 @@ API Reference - Query / Subscription
   :depth: 3
   :local:
 
-Query / subscription syntax
----------------------------
+**query** / **subscription** syntax
+-----------------------------------
 
 .. code-block:: none
 
@@ -69,6 +69,57 @@ Query / subscription syntax
 
     For more examples and details of usage, please see :ref:`this <queries>`.
 
+**query_by_pk** / **subscription_by_pk** syntax
+-----------------------------------------------
+
+.. code-block:: none
+
+    query|subscription [<op-name>] {
+      <query-field-name> (
+        column1: value1
+        column2: value2
+      )
+      <object-fields>
+    }
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key
+     - Required
+     - Schema
+     - Description
+   * - op-name
+     - false
+     - Value
+     - Name query/subscription for observability
+   * - query-field-name
+     - true
+     - Value
+     - Name of the auto-generated query field, e.g. *article_by_pk*
+
+**E.g. QUERY BY PK**:
+
+.. code-block:: graphql
+
+    query {
+      article_by_pk(id: 1) {
+        id
+        title
+      }
+    }
+
+**E.g. SUBSCRIPTION BY PK**:
+
+.. code-block:: graphql
+
+    subscription {
+      article_by_pk(id: 1) {
+        id
+        title
+      }
+    }
+
 Syntax definitions
 ------------------
 

docs/graphql/manual/api-reference/schema-metadata-api/table-view.rst

@@ -133,8 +133,11 @@ Add a table/view ``author``:
               "select_by_pk": "Author",
               "select_aggregate": "AuthorAggregate",
               "insert": "AddAuthors",
+              "insert_one":"AddAuthor",
               "update": "UpdateAuthors",
-              "delete": "DeleteAuthors"
+              "update_by_pk": "UpdateAuthor",
+              "delete": "DeleteAuthors",
+              "delete_by_pk": "DeleteAuthor"
            },
            "custom_column_names": {
               "id": "authorId"
@@ -199,28 +202,40 @@ Custom Root Fields
      - Description
    * - select
      - false
-     - `String`
+     - ``String``
      - Customise the ``<table-name>`` root field
    * - select_by_pk
      - false
-     - `String`
+     - ``String``
      - Customise the ``<table-name>_by_pk`` root field
    * - select_aggregate
      - false
-     - `String`
+     - ``String``
      - Customise the ``<table-name>_aggregete`` root field
    * - insert
      - false
-     - `String`
+     - ``String``
      - Customise the ``insert_<table-name>`` root field
+   * - insert_one
+     - false
+     - ``String``
+     - Customise the ``insert_<table-name>_one`` root field
    * - update
      - false
-     - `String`
+     - ``String``
      - Customise the ``update_<table-name>`` root field
+   * - update_by_pk
+     - false
+     - ``String``
+     - Customise the ``update_<table-name>_by_pk`` root field
    * - delete
      - false
-     - `String`
+     - ``String``
      - Customise the ``delete_<table-name>`` root field
+   * - delete_by_pk
+     - false
+     - ``String``
+     - Customise the ``delete_<table-name>_by_pk`` root field
 
 .. _set_table_custom_fields:
 
@@ -249,8 +264,11 @@ Set custom fields for table/view ``author``:
            "select_by_pk": "Author",
            "select_aggregate": "AuthorAggregate",
            "insert": "AddAuthors",
+           "insert_one":"AddAuthor",
            "update": "UpdateAuthors",
-           "delete": "DeleteAuthors"
+           "update_by_pk": "UpdateAuthor",
+           "delete": "DeleteAuthors",
+           "delete_by_pk": "DeleteAuthor"
         },
         "custom_column_names": {
            "id": "authorId"