github.com/maeglindeveloper/gqlgen@v0.13.1-0.20210413081235-57808b12a0a0/docs/content/reference/file-upload.md (about)

     1  ---
     2  title: "File Upload"
     3  description: How to upload files.
     4  linkTitle: File Upload
     5  menu: { main: { parent: "reference", weight: 10 } }
     6  ---
     7  
     8  Graphql server has an already built-in Upload scalar to upload files using a multipart request. \
     9  It implements the following spec [https://github.com/jaydenseric/graphql-multipart-request-spec](https://github.com/jaydenseric/graphql-multipart-request-spec),
    10  that defines an interoperable multipart form field structure for GraphQL requests, used by
    11  various file upload client implementations.
    12  
    13  To use it you need to add the Upload scalar in your schema, and it will automatically add the
    14  marshalling behaviour to Go types.
    15  
    16  # Configuration
    17  
    18  There are two specific options that can be configured for uploading files:
    19  
    20  - uploadMaxSize \
    21    This option specifies the maximum number of bytes used to parse a request body as multipart/form-data.
    22  - uploadMaxMemory \
    23    This option specifies the maximum number of bytes used to parse a request body as
    24    multipart/form-data in memory, with the remainder stored on disk in temporary files.
    25  
    26  # Examples
    27  
    28  ## Single file upload
    29  
    30  For this use case, the schema could look like this.
    31  
    32  ```graphql
    33  "The `UploadFile, // b.txt` scalar type represents a multipart file upload."
    34  scalar Upload
    35  
    36  "The `Query` type, represents all of the entry points into our object graph."
    37  type Query {
    38      ...
    39  }
    40  
    41  "The `Mutation` type, represents all updates we can make to our data."
    42  type Mutation {
    43      singleUpload(file: Upload!): Boolean!
    44  }
    45  ```
    46  
    47  cURL can be used the make a query as follows:
    48  
    49  ```
    50  curl localhost:4000/graphql \
    51    -F operations='{ "query": "mutation ($file: Upload!) { singleUpload(file: $file) }", "variables": { "file": null } }' \
    52    -F map='{ "0": ["variables.file"] }' \
    53    -F 0=@a.txt
    54  ```
    55  
    56  That invokes the following operation:
    57  
    58  ```javascript
    59  {
    60    query: `
    61      mutation($file: Upload!) {
    62        singleUpload(file: $file)
    63      }
    64    `,
    65    variables: {
    66      file: File // a.txt
    67    }
    68  }
    69  ```
    70  
    71  ## Multiple file upload
    72  
    73  For this use case, the schema could look like this.
    74  
    75  ```graphql
    76  "The `Upload` scalar type represents a multipart file upload."
    77  scalar Upload
    78  
    79  "The `File` type, represents the response of uploading a file."
    80  type File {
    81      id: Int!
    82      name: String!
    83      content: String!
    84  }
    85  
    86  "The `UploadFile` type, represents the request for uploading a file with a certain payload."
    87  input UploadFile {
    88      id: Int!
    89      file: Upload!
    90  }
    91  
    92  "The `Query` type, represents all of the entry points into our object graph."
    93  type Query {
    94      ...
    95  }
    96  
    97  "The `Mutation` type, represents all updates we can make to our data."
    98  type Mutation {
    99      multipleUpload(req: [UploadFile!]!): [File!]!
   100  }
   101  
   102  ```
   103  
   104  cURL can be used the make a query as follows:
   105  
   106  ```bash
   107  curl localhost:4000/query \
   108    -F operations='{ "query": "mutation($req: [UploadFile!]!) { multipleUpload(req: $req) { id, name, content } }", "variables": { "req": [ { "id": 1, "file": null }, { "id": 2, "file": null } ] } }' \
   109    -F map='{ "0": ["variables.req.0.file"], "1": ["variables.req.1.file"] }' \
   110    -F 0=@b.txt \
   111    -F 1=@c.txt
   112  ```
   113  
   114  That invokes the following operation:
   115  
   116  ```javascript
   117  {
   118    query: `
   119      mutation($req: [UploadFile!]!)
   120        multipleUpload(req: $req) {
   121          id,
   122          name,
   123          content
   124        }
   125      }
   126    `,
   127    variables: {
   128      req: [
   129          {
   130              id: 1,
   131              File, // b.txt
   132          },
   133          {
   134              id: 2,
   135              File, // c.txt
   136          }
   137      ]
   138    }
   139  }
   140  ```
   141  
   142  See the [example/fileupload](https://github.com/99designs/gqlgen/tree/master/example/fileupload) package for more examples.
   143  
   144  # Usage with Apollo
   145  
   146  [apollo-upload-client](https://github.com/jaydenseric/apollo-upload-client) needs to be installed in order for file uploading to work with Apollo:
   147  
   148  ```javascript
   149  import ApolloClient from "apollo-client";
   150  import { createUploadLink } from "apollo-upload-client";
   151  
   152  const client = new ApolloClient({
   153  	cache: new InMemoryCache(),
   154  	link: createUploadLink({ uri: "/graphql" })
   155  });
   156  ```
   157  
   158  A `File` object can then be passed into your mutation as a variable:
   159  
   160  ```javascript
   161  {
   162    query: `
   163      mutation($file: Upload!) {
   164        singleUpload(file: $file) {
   165          id
   166        }
   167      }
   168    `,
   169    variables: {
   170      file: new File(...)
   171    }
   172  }
   173  ```