GraphQL Mutations in Data SDK (Beta)

GraphQL mutations are operations that create, update, or delete Salesforce records. Use the graphql.mutate() method for all mutation operations.

Unlike queries, mutations:

  • Are never cached and don’t write to the cache
  • Return MutationResult<T> with only data and errors fields
  • Don’t provide subscription support
  • Don’t write to the cache, so they won’t affect subsequent query results

Create a new record using the <ObjectName>Create mutation.

A mutation operation follows the RecordCreate name pattern, for example, AccountCreate. See Mutations Schema in the GraphQL API Developer Guide.

Run npm run graphql:codegen to generate TypeScript types.

Implement the client-side mutation function that invokes dataSdk.graphql?.mutate() with the generated types.

This component example shows how to call createAccount, handle loading and error states, and react to the created result.

Update an existing record using the <ObjectName>Update mutation.

Implement the update function: call dataSdk.graphql?.mutate() with the update payload, then check and handle any returned errors.

This form component demonstrates using updateAccount and calling onSuccess after a successful update, while displaying errors when present.

Delete a record using the <ObjectName>Delete mutation.

Define the delete mutation in a .graphql file that accepts the delete input and returns the deleted record Id.

Delete mutations only return the ID of the deleted record, not a Record object.

Implement the delete function that calls dataSdk.graphql?.mutate(), validates the result, and returns the deleted ID to callers.

This example shows a button component that calls deleteAccount, displays progress, and handles any error returned by the mutation.

Since mutations don’t update the cache, you need to manually refresh related queries to reflect the changes in the UI.

If you have access to the QueryResult object from a previous query, call refresh():

If you don’t have access to the QueryResult, re-execute the query.

You can choose to update the UI before the mutation completes.

Here are several best practices for working with GraphQL mutation.

Include Id in your mutation return fields.

Define interfaces for mutation inputs for type safety.

Show loading states during mutations to notify users on what to expect.

Show success and error messages to communicate expectations with users.

Reset form fields after successful mutations.

If you must perform multiple mutations, consider batching them.