docs: Add GraphQL docs for unset field (#853)

_includes/graphql/files.md

@@ -3,6 +3,7 @@
 The GraphQL API supports file upload via [GraphQL Upload](https://github.com/jaydenseric/graphql-upload), to send a `File` through `GraphQL` it's recommended to use the [Apollo Upload Client](https://github.com/jaydenseric/apollo-upload-client).
 
 ## Add a File field to a Class
+
 First of all we will update our `GameScore` class with a `screenshot` field of type `File`.
 
 ```jsonc
@@ -12,15 +13,14 @@ First of all we will update our `GameScore` class with a `screenshot` field of t
   "X-Parse-Master-Key": "MASTER_KEY"
 }
 ```
+
 ```graphql
 # GraphQL
 mutation updateGameScoreClass {
   updateClass(
-    input: { 
-      name: "GameScore",
-      schemaFields: { 
-        addFiles: [{ name: "screenshot" }]
-      }
+    input: {
+      name: "GameScore"
+      schemaFields: { addFiles: [{ name: "screenshot" }] }
     }
   ) {
     class {
@@ -53,6 +53,7 @@ The GraphQL API supports nested mutation for the `File` type, so you can send th
   "X-Parse-Master-Key": "MASTER_KEY" // (optional)
 }
 ```
+
 ```graphql
 # GraphQL
 # $file is a GraphQL Variable, see https://github.com/jaydenseric/apollo-upload-client
@@ -90,16 +91,17 @@ You can add an existing file to an object.
   "X-Parse-Master-Key": "MASTER_KEY" // (optional)
 }
 ```
+
 ```graphql
 # GraphQL
 mutation createGameScore {
   createGameScore(
     input: {
       fields: {
         playerName: "John"
-        screenshot: { 
-          file :{
-            __type: "File",
+        screenshot: {
+          file: {
+            __type: "File"
             name: "6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
             url: "http://localhost:1337/graphq/files/APPLICATION_ID/6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
           }
@@ -133,6 +135,7 @@ mutation createGameScore {
 ```
 
 ## Create and add a file
+
 Lets create a new `GameScore` object and upload the file.
 ```jsonc
 // Header
@@ -141,19 +144,13 @@ Lets create a new `GameScore` object and upload the file.
   "X-Parse-Master-Key": "MASTER_KEY" // (optional)
 }
 ```
+
 ```graphql
 # GraphQL
 # $file is a GraphQL Variable, see https://github.com/jaydenseric/apollo-upload-client
-mutation createGameScore($file: Upload! ) {
+mutation createGameScore($file: Upload!) {
   createGameScore(
-    input: {
-      fields: {
-        playerName: "John"
-        screenshot: { 
-          upload : $file
-        }
-      }
-    }
+    input: { fields: { playerName: "John", screenshot: { upload: $file } } }
   ) {
     gameScore {
       screenshot {
@@ -179,3 +176,36 @@ mutation createGameScore($file: Upload! ) {
   }
 }
 ```
+
+## Unlink a file
+
+Let's update a `GameScore` object and unset the file linked in the `screenshot` field. By setting the `screenshot` field to `null`, the linked file will be removed from the `Gamescore` object.
+
+**Note:** The file will be not deleted from your file storage.
+
+```graphql
+# GraphQL
+mutation updateGameScore($id: ID!) {
+  updateGameScore(input: { id: $id, fields: { screenshot: null } }) {
+    gameScore {
+      screenshot {
+        name
+        url
+      }
+    }
+  }
+}
+```
+
+```js
+// Response
+{
+  "data": {
+    "updateGameScore": {
+      "gameScore": {
+        "screenshot": null
+      }
+    }
+  }
+}
+```

_includes/graphql/objects.md

@@ -20,11 +20,7 @@ mutation createAGameScore {
   createGameScore(
     input: {
       clientMutationId: "anUniqueId"
-      fields: {
-        playerName: "Sean Plott",
-        score: 1337,
-        cheatMode: false
-      }
+      fields: { playerName: "Sean Plott", score: 1337, cheatMode: false }
     }
   ) {
     clientMutationId
@@ -85,6 +81,7 @@ For example, if you have a class named `GameScore` in the schema, Parse Server a
   "X-Parse-Master-Key": "MASTER_KEY" // (optional)
 }
 ```
+
 ```graphql
 # GraphQL
 mutation updateAGameScore {
@@ -114,8 +111,53 @@ mutation updateAGameScore {
   }
 }
 ```
+
 **Note:** If you use [Apollo Client](https://www.apollographql.com/docs/react/) it's recommended to request the modified fields and `id` during the Mutation, then the [Apollo Client](https://www.apollographql.com/docs/react/) will automatically update its local store and push the new data across your app; i.e. If you update `playerName` you should request `playerName` and `id` like the code above.
 
+### Unset a field
+
+Across the whole GraphQL API you can simply unset a field by setting its value to `null`.
+
+Following the official GraphQL API Specs, setting a field to `null` through the GraphQL API will completly unset the field in the database on the targeted Parse Object. GraphQL API will transform `null` on the server before saving the object to correctly unset the field into the database.
+
+```js
+// Header
+{
+  "X-Parse-Application-Id": "APPLICATION_ID",
+  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
+}
+```
+
+```graphql
+# GraphQL
+mutation updateAGameScore {
+  updateGameScore(
+    input: { id: "R2FtZVNjb3JlOmM3TVpDZEhQY2w=", fields: { playerName: null } }
+  ) {
+    gameScore {
+      id
+      playerName
+    }
+  }
+}
+```
+
+```js
+// Response
+{
+  "data": {
+    "updateGameScore": {
+      "gameScore": {
+        "id": "R2FtZVNjb3JlOmM3TVpDZEhQY2w=",
+        "playerName": null
+      }
+    }
+  }
+}
+```
+
+The GraphQL API will always return `null` if the field is `null` or `undefined` in the database. The GraphQL API does not differentiate between `null` and `undefined` in the data response.
+
 ## Delete
 
 For each class in your application's schema, Parse Server automatically generates a custom mutation for deleting this class' objects through the GraphQL API.
@@ -170,20 +212,17 @@ The GraphQL API supports nested mutations, so you can create objects with comple
   "X-Parse-Master-Key": "MASTER_KEY" // (optional)
 }
 ```
+
 ```graphql
 mutation aNestedMutation {
   createCountry(
     input: {
       fields: {
         name: "Mars"
         cities: {
-          createAndAdd: [{ name: "Alpha",
-            companies: {
-              createAndAdd: [{
-                name: "Motors"
-              }]
-            }
-          }]
+          createAndAdd: [
+            { name: "Alpha", companies: { createAndAdd: [{ name: "Motors" }] } }
+          ]
         }
       }
     }