Skip to main content

Mutations

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.

Medplum implements the draft FHIR GraphQL Mutation spec. 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

Create Mutation​

You can create a resource using the [resourceType]Create mutation.

To create a Patient:

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
{
  data: {
    PatientCreate: {
      id: 'example-id',
      name: {
        given: 'Homer',
      },
      gender: 'male',
    },
  },
};

Aliasing the output​

Just as with GraphQL queries, you can alias the newly created resource.

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
{
  data: {
    newPatient: {
      id: 'example-id',
      name: {
        given: 'Homer',
      },
      gender: 'male',
    },
  },
};

Built-in types​

Medplum's graphQL schema provides type definitions for complex nested fields (aka "Backbone Elements"). These can be used to simplify arguments to your custom mutations.

This examples demonstrates how to create a mutation that creates a Communication resource and takes an array of CommunicationPayload types as a parameter:

  # 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​

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
{
  data: {
    PatientUpdate: {
      id: 'example-id',
      name: {
        given: 'Homer',
      },
      gender: 'male',
    },
  },
};

Delete Mutation​

mutation {
    PatientDelete(
      id: "example-id"
    ) {
      id
    }
  }