On this page GraphQL mutations are operations that allow the client to create, update, or delete data on the server. Unlike queries, which are read-only operations and can be executed in parallel, mutations are write operations. For more information about GraphQL mutations, refer to the [GraphQL documentation](https://graphql.org/learn/queries/#mutations). Medplum implements the draft [FHIR GraphQL Mutation spec](https://hl7.org/fhir/R4/graphql.html#mutations). For the inputs, you would append the action (Create, Update, or Delete) to the resource type. Here are examples of mutations for the `Patient` resource. You can test these mutations at [graphiql.medplum.com](https://graphiql.medplum.com/) ## Create Mutation [​](/content/docs/graphql/mutations#create-mutation "Direct link to Create Mutation"/index.html) You can create a resource using the `[resourceType]Create` mutation. To create a [`Patient`](/content/docs/api/fhir/resources/patient/index.html): - GraphQL - Typescript ```graphql mutation { # Define the fields for the resource being created PatientCreate( res: { resourceType: "Patient" gender: "male" name: [\ \ {\ \ given: "Homer"\ \ }\ \ ] } ) # Specify which of the newly created fields to return in the response { id gender name { given } } } } ``` ```ts const patient = await medplum.graphql(` mutation { # Define the fields for the resource being created PatientCreate( res: { resourceType: "Patient" gender: "male" name: [\ \ {\ \ given: "Homer"\ \ }\ \ ] } ) # Specify which of the newly created fields to return in the response { id gender name { given } } }`); ``` Example Response ```ts { data: { PatientCreate: { id: 'example-id', name: { given: 'Homer', }, gender: 'male', }, }, }; ``` ### Aliasing the output [​](/content/docs/graphql/mutations#aliasing-the-output "Direct link to Aliasing the output"/index.html) Just as with GraphQL queries, you can alias the newly created resource. - GraphQL - Typescript ```graphql mutation { # Define the fields for the resource being created, and alias as "newPatient" newPatient: PatientCreate( res: { resourceType: "Patient" gender: "male" name: [\ \ {\ \ given: "Homer"\ \ }\ \ ] } ) # Specify which of the newly created fields to return in the response { id gender name { given } } } } ``` ```ts const patientAlias = await medplum.graphql(` mutation { # Define the fields for the resource being created, and alias as "newPatient" newPatient: PatientCreate( res: { resourceType: "Patient" gender: "male" name: [\ \ {\ \ given: "Homer"\ \ }\ \ ] } ) # Specify which of the newly created fields to return in the response { id gender name { given } } }`); ``` Example Response ```ts { data: { newPatient: { id: 'example-id', name: { given: 'Homer', }, gender: 'male', }, }, }; ``` ### Built-in types [​](/content/docs/graphql/mutations#built-in-types "Direct link to Built-in types"/index.html) Medplum's graphQL schema provides type definitions for complex nested fields (aka " [Backbone Elements](https://www.hl7.org/fhir/R4/backboneelement.html#BackboneElement)"). These can be used to simplify arguments to your custom mutations. This examples demonstrates how to create a mutation that creates a [`Communication`](/content/docs/api/fhir/resources/communication/index.html) resource and takes an array of `CommunicationPayload` types as a parameter: - GraphQL - Typescript ```graphql # Use the built-in type `CommunicationPayloadCreate` as a parameter mutation CreateCommunicationWithPayload($payload: [CommunicationPayloadCreate!]!) { CommunicationCreate(res: { resourceType: "Communication", status: "draft", payload: $payload }) # Specify which of the newly created fields to return in the response { id, resourceType, payload { contentString, contentAttachment { url } } } } ``` ```ts const communication = await medplum.graphql(` # Use the built-in type CommunicationPayloadCreate as a parameter mutation CreateCommunicationWithPayload($payload: [CommunicationPayloadCreate!]!) { CommunicationCreate(res: { resourceType: "Communication", status: "draft", payload: $payload }) # Specify which of the newly created fields to return in the response { id, resourceType, payload { contentString, contentAttachment { url } } } }`); ``` ## Update Mutation [​](/content/docs/graphql/mutations#update-mutation "Direct link to Update Mutation"/index.html) - GraphQL - Typescript ```graphql mutation { # Define the elements for the updated resources. Note that this will *overwrite* the entire resource. PatientUpdate( id: "example-id" res: { id: "example-id" resourceType: "Patient" gender: "male" name: [\ \ {\ \ given: "Bob"\ \ },\ \ {\ \ family: "Smith"\ \ }\ \ ] } ) # Specify which fields to return from the updated resource { id gender name { given } } } } ``` ```ts const update = await medplum.graphql(` mutation { # Define the elements for the updated resources. Note that this will *overwrite* the entire resource. PatientUpdate( id: "example-id" res: { id: "example-id" resourceType: "Patient" gender: "male" name: [\ \ {\ \ given: "Bob"\ \ },\ \ {\ \ family: "Smith"\ \ }\ \ ] } ) # Specify which fields to return from the updated resource { id gender name { given } } } `); ``` Example Response ```ts { data: { PatientUpdate: { id: 'example-id', name: { given: 'Homer', }, gender: 'male', }, }, }; ``` ## Patch Mutation [​](/content/docs/graphql/mutations#patch-mutation "Direct link to Patch Mutation"/index.html) You can partially update a resource using the `[resourceType]Patch` mutation. This mutation takes an `id` and a `patch` array of operations (see [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902)). - GraphQL - Typescript ```graphql mutation { PatientPatch( id: "example-id" patch: [\ \ { op: "replace", path: "/name/0/family", value: "Smith" },\ \ { op: "replace", path: "/gender", value: "male" }\ \ ] ) { id gender name { family given } } } ``` ```ts const result = await medplum.graphql(` mutation { PatientPatch( id: "example-id" patch: [\ \ { op: "replace", path: "/name/0/family", value: "Smith" },\ \ { op: "replace", path: "/gender", value: "male" }\ \ ] ) { id gender name { family given } } } `); ``` > **Note:** The `value` field in the patch operation is always a string due to GraphQL input type limitations. For complex values, encode as JSON strings and decode server-side if needed. Example Response ```json { "data": { "PatientPatch": { "id": "example-id", "gender": "male", "name": [\ \ { "family": "Smith", "given": ["Alice"] }\ \ ] } } } ``` ## Delete Mutation [​](/content/docs/graphql/mutations#delete-mutation "Direct link to Delete Mutation"/index.html) - GraphQL - Typescript ```graphql mutation { PatientDelete( id: "example-id" ) { id } } ``` ```ts const deleteObject = await medplum.graphql(` mutation { PatientDelete( id: "example-id" ) { id } } `); ```