Mutations | Medplum
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.
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 [](/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:
- GraphQL
- Typescript
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
}
}
}
}
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
{
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
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
}
}
}
}
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
{
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"). 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:
- GraphQL
- Typescript
# 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
}
}
}
}
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
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
}
}
}
}
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
{
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).
- GraphQL
- Typescript
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 }
}
}
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
valuefield 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
{
"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
mutation {
PatientDelete(
id: "example-id"
) {
id
}
}
const deleteObject = await medplum.graphql(`
mutation {
PatientDelete(
id: "example-id"
) {
id
}
}
`);