GraphQL Mutate Parameters (Beta)

The GraphQL mutate() method in the Data SDK includes several parameters.

Runs a GraphQL mutation without caching.

ParameterTypeDescription
mutationstringThe GraphQL mutation operation string.
variables?V, defaults to Record<string, unknown>Optional key-value map of GraphQL variables referenced by the mutation.
operationName?stringOptional operation name for multi-operation documents.

All GraphQL mutations follow this UI API structure.

For more information, see Mutations Schema in the GraphQL API Developer Guide.

For simple mutations without external .graphql files, use the gql template tag.

Use inline mutations when:

  • Simple mutations without complex input structures
  • Mutations used in only one place
  • Rapid prototyping or testing

Use external .graphql files when:

  • Complex mutations with many fields
  • Mutations shared across multiple files
  • When you want full type generation from codegen

For more information on generating types and implementing a mutation operation, see GraphQL Mutations in Data SDK.

The return type of dataSdk.graphql?.mutate(), which resolves to the typed GraphQL response payload.

Mutations don’t support subscribe() or refresh() like GraphQL queries. To update stale data after a mutation, use a query result reference to call result.refresh().

Consider these mutation response behavior:

  • A successful mutation returns data with no errors.
  • A partially successful mutation has both data and errors.
  • Data SDK preserves the partial data payload, so callers can still use returned fields even when errors exist.

GraphQL mutation operations return these response structures.

A create operation returns the record ID and any queried fields.

An update operation returns the record ID and the updated fields.

A delete operation returns the deleted record ID only.

A successful query response includes record data in the RecordCreate object.

A partially successful query response includes errors and some data.