From 576245070cc6e8871772bee24daf1b7b811ebb02 Mon Sep 17 00:00:00 2001 From: Antoine Cormouls Date: Sun, 25 Dec 2022 16:07:17 +0100 Subject: [PATCH] docs: Add GraphQL docs for unset field (#853) --- _includes/graphql/files.md | 64 ++++++++++++++++++++++++++---------- _includes/graphql/objects.md | 63 ++++++++++++++++++++++++++++------- 2 files changed, 98 insertions(+), 29 deletions(-) diff --git a/_includes/graphql/files.md b/_includes/graphql/files.md index b5dc5bed..64fe3e88 100644 --- a/_includes/graphql/files.md +++ b/_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,6 +91,7 @@ You can add an existing file to an object. "X-Parse-Master-Key": "MASTER_KEY" // (optional) } ``` + ```graphql # GraphQL mutation createGameScore { @@ -97,9 +99,9 @@ mutation 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 + } + } + } +} +``` diff --git a/_includes/graphql/objects.md b/_includes/graphql/objects.md index c86e7acb..dd327a61 100644 --- a/_includes/graphql/objects.md +++ b/_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,6 +212,7 @@ The GraphQL API supports nested mutations, so you can create objects with comple "X-Parse-Master-Key": "MASTER_KEY" // (optional) } ``` + ```graphql mutation aNestedMutation { createCountry( @@ -177,13 +220,9 @@ mutation aNestedMutation { fields: { name: "Mars" cities: { - createAndAdd: [{ name: "Alpha", - companies: { - createAndAdd: [{ - name: "Motors" - }] - } - }] + createAndAdd: [ + { name: "Alpha", companies: { createAndAdd: [{ name: "Motors" }] } } + ] } } }