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.

The mutation query includes an input argument.

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

  • 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.

  • 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.

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

Consider these usage guidelines when running mutation operations.

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

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.

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.

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.

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

See Also