`executeMutation`

To work with mutation operations for record create, update, or delete, import executeMutation from lightning/graphql. Use the executeMutation method imperatively. executeMutation isn’t supported using the @wire annotation.

lightning/graphql doesn’t currently support Mobile Offline use cases. For more information, see GraphQL API Wire Adapter Comparison.

Note

Syntax

1import { LightningElement, wire } from "lwc";
2import { gql, executeMutation } from "lightning/graphql";
3
4export default class MutationGQLComponent extends LightningElement {
5  get mutationQuery() {
6    return gql`
7      mutation operationObjectName {
8        // mutation query here
9      }
10    `;
11  }
12
13  async mutateObject() {
14    const result = await executeMutation({
15      query: mutationQuery,
16      variables: {
17        // variables here
18      },
19    });
20    // do something with the result
21  }
22}

The mutation query includes an input argument.

1mutation operationObjectName {
2  uiapi {
3    ObjectNameOperation(input: {
4      // For create and update operations only
5      ObjectName: {
6        // Input fields
7      }
8      Id: ... // ID for update and delete operations only
9    }) {
10      // For create and update operations only
11      Record {
12        }
13        // Output fields
14      Id: ... // ID for delete operations only
15    }
16  }
17}

GraphQL API Resource

1POST /graphql

Like the GraphQL wire adapter, executeMutation uses the Salesforce GraphQL API resource.

Parameters

query—(Required) Parsed GraphQL query. Parse the query using the gql JavaScript template literal function. gql parses the GraphQL query into a format that executeMutation can use. gql isn’t reactive.
variables— An object that provides GraphQL Variables for the query.

The value passed to variables must include an input argument with the record Id field and fields for the record create or update.
Note
operationName—The name of the mutation operation you want to perform. Use operationName to select the operation to run if your GraphQL query defines more than one operation. We recommend labeling your queries with mutation operationName instead of using the shorthand syntax mutation for improved server-side debugging to identify different GraphQL requests. For example, mutation CreateCase or mutation UpdateContact.

Returns

data—GraphQL API response
errors—GraphQL API errors

To maintain compatibility with the GraphQL response specification, executeMutation also returns errors instead of error, unlike other imperative functions, like updateRecord.

Note

Usage

Consider these usage guidelines when running mutation operations.

Child relationships aren’t supported and can’t be queried as part of a mutation.

Note

Create a Record

When creating a record:

Include all required fields
Include only createable fields
Assign IDs to fields with type Reference using their API name

To ensure that new records are available in query results, use the refresh method.

This example creates a contact record using the FirstName and LastName fields.

1import { LightningElement } from "lwc";
2import { gql, executeMutation } from "lightning/graphql";
3
4export default class CreateRecordQuery extends LightningElement {
5  get createMutation() {
6    return gql`
7      mutation ContactCreateExample {
8        uiapi {
9          ContactCreate(
10            input: { Contact: { FirstName: "Astro", LastName: "Nomical", Title: "CEO" } }
11          ) {
12            Record {
13              Id
14              Name {
15                value
16              }
17            }
18          }
19        }
20      }
21    `;
22  }
23
24  async handleCreateContact() {
25    const result = await executeMutation({
26      query: this.createQuery,
27    });
28  }
29  catch(error) {
30    console.error("Error creating contact", error);
31  }
32}

Update a Record

When updating a record:

Include the ID of the record you want to update
Include only updateable fields
Assign IDs to fields with type Reference using their API name
The output field is Record

To ensure that updated records are available in query results, use the refresh method.

This example updates the Phone field on a contact record.

1import { LightningElement } from "lwc";
2import { gql, executeMutation } from "lightning/graphql";
3
4export default class UpdateRecordQuery extends LightningElement {
5  get updateMutation() {
6    return gql`
7      mutation UpdateContact($input: ContactUpdateInput!) {
8        uiapi {
9          ContactUpdate(input: $input) {
10            success
11          }
12        }
13      }
14    `;
15  }
16  async handleUpdateContact() {
17    const result = await executeMutation({
18      query: this.updateQuery,
19      variables: {
20        input: {
21          Id: "003Z6000001W5zXIAS",
22          Contact: {
23            Phone: "18888888888",
24          },
25        },
26      },
27    });
28    console.log("result", result);
29  }
30  catch(error) {
31    console.error("Error creating contact", error);
32  }
33}

Delete a Record

When deleting a record, include only the ID of the record you want to delete.

This example deletes a contact record using the Id field.

1import { LightningElement } from "lwc";
2import { gql, executeMutation } from "lightning/graphql";
3
4export default class DeleteRecordQuery extends LightningElement {
5  get deleteMutation() {
6    return gql`
7      mutation ContactDeleteExample {
8        uiapi {
9          ContactDelete(input: { Id: "003Z6000001W5yaIAC" }) {
10            Id
11          }
12        }
13      }
14    `;
15  }
16
17  async handleDeleteContact() {
18    const result = await executeMutation({
19      query: this.deleteQuery,
20    });
21  }
22  catch(error) {
23    console.error("Error deleting contact", error);
24  }
25}

The lwc-recipes repo has a graphqlMutations example that saves record updates from inline editing using a lightning-datatable component.

Tip

See Also