GraphQL Usage in Data SDK (Beta)

Use a GraphQL query or mutation operation to work with Salesforce data, such as to query record data from an Account or Contact.

To access Salesforce data via GraphQL:

  1. Define TypeScript interfaces for the response shape.
  2. Write the GraphQL query using uiapi syntax.
  3. Use createDataSDK() and dataSdk.graphql?.() with proper typing.
  4. Extract and return the data from the response.

For more information about GraphQL usage, see the GraphQL API Developer Guide.

Use one of these patterns for defining GraphQL queries.

This pattern is useful for simple queries without variables or fragments.

  • Use the gql template tag (never plain template literals)
  • Ensure the query operation name matches what codegen expects
  • Import generated types from graphql-operations-types.ts

This pattern is useful for complex queries with variables, fragments, or queries shared across files.

  • Import .graphql files with the ?raw suffix
  • Import generated types from graphql-operations-types.ts
  • Provide response and variables type generics to dataSdk.graphql?.<T, V>()
  • Use optional chaining for nested response data

To implement a query using a .graphql external file:

  1. Create a .graphql file under src/api/utils/query/
  1. Generate the types using npm run graphql:codegen. The command generates the types in src/api/graphql-operations-types.ts. For example:
    1. Response type: GetMyDataQuery
    2. Variables type: GetMyDataQueryVariables
  2. Implement the data access function.

To provide type safety for GraphQL operations, define your return type. These TypeScript interfaces define the shape of data flowing in (query variables) and out (query results) of your GraphQL operations.

Export the interfaces so they can be imported and reused across components. You can also use graphql-codegen to generate the interfaces for the interfaces to stay in sync with your schema. Use the return types in your methods and variables.

GraphQL fragments are reusable units of query logic that are used to define a set of fields.
This example uses GraphQL fragments and directives to keep one query reusable while conditionally including fields.

  • FinancialFields and ContactFields are reusable field groups for Account.
  • In the main query, each fragment is attached with @include(if: $...):
    • ...FinancialFields @include(if: $includeFinancials)
    • ...ContactFields @include(if: $includeContacts)
  • At runtime, variables (includeFinancials, includeContacts) decide whether those field blocks are fetched.

dataSdk.graphql?.<Response, Variables>(QUERY, variables) executes the query with:

  • explicit response type (GetAccountDetailsQuery)
  • explicit variables type (GetAccountDetailsQueryVariables)
  • runtime variables object (id, includeFinancials, includeContacts)

All the GraphQL queries go through the UI API endpoint.

Supported mutation operations are Create, Update, and Delete only.

For more information, see the UI API query and mutation structures in the GraphQL API Developer Guide.

When using GraphQL via the Data SDK, consider these usage patterns.

Direct API calls aren't supported. Always use the Data SDK to make your API calls.

Provide the response type instead of making untyped GraphQL calls.

Use the gql template tag or an external .graphql file instead of plain string queries.

Use optional chaining instead of non-null assertion on a GraphQL call.