docs/mssql: add update and update index

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3477
Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com>
GitOrigin-RevId: 7e2d705baa98ceebf7a77dcd774756467e69a0b5

docs/graphql/core/databases/ms-sql-server/index.rst

@@ -35,12 +35,11 @@ Here are 2 ways you can get started with Hasura and SQL Server:
 Supported features
 ------------------
 
-Hasura currently supports queries, subscriptions, inserts, deletes, relationships and permissions on MS SQL Server.
+Hasura currently supports queries, subscriptions, mutations, relationships and permissions on MS SQL Server.
 
 Next up on our roadmap for Hasura + SQL Server:
 
 - Support for stored procedures & functions (`#7073 <https://github.com/hasura/graphql-engine/issues/7073>`__)
-- Mutations: Run updates, stored procedures and transactions securely on SQL Server over a GraphQL API (`#7074 <https://github.com/hasura/graphql-engine/issues/7074>`__)
 - Event triggers: Trigger HTTP webhooks with atomic capture and atleast once guarantee whenever data changes inside the database (`#7075 <https://github.com/hasura/graphql-engine/issues/7075>`__)
 - Remote Joins: Join models in SQL Server to models from other API services (GraphQL or REST) (`#7076 <https://github.com/hasura/graphql-engine/issues/7076>`__)
 

docs/graphql/core/databases/ms-sql-server/mutations/index.rst

@@ -33,18 +33,13 @@ The following types of mutation requests are possible:
 
   Insert <insert>
   Upsert <upsert>
+  Update <update>
   Delete <delete>
 
 
-.. note::
-
-  Support for the update mutation will be added soon.
-
-
 .. TODO: DBCOMPATIBILITY
 
   .. toctree::
     :maxdepth: 1
 
-    Update <update>
     multiple-mutations

docs/graphql/core/databases/ms-sql-server/mutations/update.rst

@@ -0,0 +1,436 @@
+.. meta::
+   :description: Update an object in MS SQL Server using a mutation
+   :keywords: hasura, docs, ms sql server, mutation, update
+
+.. _ms_sql_server_update:
+
+MS SQL Server: Update mutation
+==============================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Auto-generated update mutation schema
+-------------------------------------
+
+**For example**, the auto-generated schema for the update mutation field for a table ``article`` looks like the following:
+
+.. 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!
+    # data of the affected rows by the mutation
+    returning: [article!]!
+  }
+
+  # single object update
+  update_article_by_pk (
+    _inc: article_inc_input
+    _set: article_set_input
+    # primary key columns arg
+    pk_columns: article_pk_columns_input!
+  ): article
+
+As you can see from the schema:
+
+- The ``where`` argument is compulsory to filter rows to be updated. See :ref:`Filter queries <_ms_sql_server_filter_queries>`
+  for filtering options. Objects can be updated based on filters on their own fields or those in their nested objects.
+  The ``{}`` expression can be used to update all rows.
+- You can return the number of affected rows and the affected objects (with nested objects) in the response.
+
+See the :ref:`update mutation API reference <update_syntax>` for the full specifications.
+
+.. note::
+
+  - At least any one of ``_set``, ``_inc`` operators is required.
+  - If a table is not in the ``dbo`` MS SQL Server schema, the update mutation field will be of the format
+    ``update_<schema_name>_<table_name>``.
+
+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
+      }
+    }
+
+.. note::
+
+   ``update_<table>_by_pk`` will **only** be available if you have select permissions on the table, as it returns the updated row.
+
+Update objects based on their fields
+------------------------------------
+**Example:** Update the ``rating`` and ``is_published`` of articles with a low ``rating``:
+
+.. graphiql::
+  :view_only:
+  :query:
+    mutation update_article {
+      update_article(
+        where: {rating: {_lte: 2}},
+        _set: {
+          rating: 1,
+          is_published: false
+        }
+      ) {
+        affected_rows
+        returning {
+          id
+          title
+          content
+          rating
+          is_published
+        }
+      }
+    }
+  :response:
+    {
+      "data": {
+        "update_article": {
+          "affected_rows": 2,
+          "returning": [
+            {
+              "id": 3,
+              "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
+            }
+          ]
+        }
+      }
+    }
+
+Using variables:
+
+.. graphiql::
+  :view_only:
+  :query:
+    mutation update_article($rating: Int, $changes: article_set_input) {
+      update_article(
+        where: {rating: {_lte: $rating}},
+        _set: $changes
+      ) {
+        affected_rows
+        returning {
+          id
+          title
+          content
+          rating
+          is_published
+        }
+      }
+    }
+  :response:
+    {
+      "data": {
+        "update_article": {
+          "affected_rows": 2,
+          "returning": [
+            {
+              "id": 3,
+              "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
+            }
+          ]
+        }
+      }
+    }
+  :variables:
+    {
+      "rating": 2,
+      "changes": {
+        "rating": 1,
+        "is_published": false,
+      }
+    }
+
+OR
+
+.. graphiql::
+  :view_only:
+  :query:
+    mutation update_article($ratingLimit: Int, $rating: Int, $isPublished: Boolean) {
+      update_article(
+        where: {rating: {_lte: $ratingLimit}},
+        _set: {
+          rating: $rating,
+          is_published: $isPublished
+        }
+      ) {
+        affected_rows
+        returning {
+          id
+          title
+          content
+          rating
+          is_published
+        }
+      }
+    }
+  :response:
+    {
+      "data": {
+        "update_article": {
+          "affected_rows": 2,
+          "returning": [
+            {
+              "id": 3,
+              "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
+            }
+          ]
+        }
+      }
+    }
+  :variables:
+    {
+      "ratingLimit": 2,
+      "rating": 1,
+      "isPublished": false
+    }
+
+Update objects based on nested objects' fields
+----------------------------------------------
+**Example:** Reset the ``rating`` of all articles authored by "Sidney":
+
+.. graphiql::
+  :view_only:
+  :query:
+    mutation update_ratings {
+      update_article(
+        where: {author: {name: {_eq: "Sidney"}}},
+        _set: {rating: null}
+      ) {
+        affected_rows
+      }
+    }
+  :response:
+    {
+      "data": {
+        "update_article": {
+          "affected_rows": 3
+        }
+      }
+    }
+
+Update all objects
+------------------
+
+You can update all objects in a table using the ``{}`` expression as the ``where`` argument. ``{}`` basically
+evaluates to ``true`` for all objects.
+
+**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
+        }
+      }
+    }
+
+Increment/Decrement **int** columns
+-----------------------------------
+You can increment/decrement an ``int`` column with a given value using the ``_inc`` operator.
+
+**Example:** Increment the ``likes`` of an article by 2:
+
+.. graphiql::
+  :view_only:
+  :query:
+    mutation update_likes {
+      update_article(
+        where: {id: {_eq: 1}},
+        _inc: {likes: 2}  # initial value: 1
+      ) {
+        affected_rows
+        returning {
+          id
+          likes
+        }
+      }
+    }
+  :response:
+    {
+      "data": {
+        "update_article": {
+          "affected_rows": 1,
+          "returning": {
+            "id": 1,
+            "likes": 3
+          }
+        }
+      }
+    }
+
+**Example:** Decrement the ``likes`` of an article by 2:
+
+.. graphiql::
+  :view_only:
+  :query:
+    mutation update_likes {
+      update_article(
+        where: {id: {_eq: 1}},
+        _inc: {likes: -2}  # initial value: 3
+      ) {
+        affected_rows
+        returning {
+          id
+          likes
+        }
+      }
+    }
+  :response:
+    {
+      "data": {
+        "update_article": {
+          "affected_rows": 1,
+          "returning": {
+            "id": 1,
+            "likes": 1
+          }
+        }
+      }
+    }
+
+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
+    }