Work with Data SDK (Beta)

The Data SDK handles authentication, CSRF tokens, and base path resolution internally. To work with Data SDK, import the functions from @salesforce/platform-sdk/data.

With the Data SDK, you can query and update Salesforce records extensively from your web app by using simple bindings for running GraphQL queries and mutations.

Export	Type	Description
`createDataSDK`	`async function`	Factory that creates a new DataSDK instance
`gql`	template tag	Identity template literal for inline GraphQL queries, which also enables editor syntax highlighting and codegen detection
`DataSDK`	`interface`	The SDK surface type with `graphql` and `fetch` methods
`SDKOptions`	`interface`	Base options type with optional surface override
`NodeOfConnection<T>`	utility type	Extracts the node type from a GraphQL connection with edges and node response

Creates a new DataSDK instance.

options: DataSDKOptions-Optional configuration for createDataSDK

DataSDKOptions

surface: string-For automatic surface detection
webapp: WebAppDataSDKOptions-Options specific to the web app surface

WebAppDataSDKOptions

basePath: string-Base URL prefix for Salesforce API calls
on401: () => Promise<unknown> | void-Optional callback
on403: () => Promise<unknown> | void-Optional callback

The return type for createDataSDK(options?), which resolves to a promise with the DataSDK object.

The GraphQL cache is shared across all DataSDK instances that use the same base URL, which improves performance and consistency when multiple components query the same data. Multiple calls to createDataSDK() share the same GraphQL cache. Cache updates from one SDK instance are visible to all other instances with the same base URL.

The gql tag is a template literal for inline GraphQL query definitions. When GraphQL queries are defined with TypeScript code, the Data SDK requires the use of gql to understand and apply special processing to your GraphQL queries at different stages of the component lifecycle. The use of the gql tag enables org-aware GraphQL syntax highlighting when using Agentforce Vibes.

See GraphQL Queries in Data SDK.

Defines the top-level SDK surface that exposes optional GraphQL and fetch APIs. Both graphql and fetch methods are optional as they’re supported in specific environments only.

GraphQL is the preferred way to work with record data.

To account for the lack of availability of GraphQL in some environments, use optional chaining (graphql?). See GraphQL Queries in Data SDK.

Use dataSdk.fetch?.() for Salesforce REST endpoints that aren’t covered by GraphQL. Use optional chaining to account for environments that don’t support fetch().

The fetch wrapper handles:

CSRF token management
Base path resolution
401/403 callback hooks

Consider using the dataSdk.fetch() call for:

Apex REST endpoints (e.g. /services/apexrest/auth/…)
Salesforce REST endpoints (e.g. /services/data/v{version}/…)

Defines the GraphQL methods available on the Data SDK, including queries and mutations.

Describes the options for graphql.query(). See GraphQL Query Parameters.

Describes the options for graphql.mutate(). See GraphQL Mutate Parameters.

Describes the reactive query result that’s returned by graphql.query().

Describes the one-shot result returned by graphql.mutate().

Describes the snapshot object passed to subscribe() callbacks.

Defines the shape of GraphQL error objects returned by the Data SDK. See Error Handling in Data SDK.

Describes supported cache control values for graphql.query(). See Cache Control in Data SDK.

These API endpoints are supported.

/services/apexrest
/services/data/v{version}/ui-api/records
/services/data/v{version}/ui-api/search-info
/services/data/v{version}/ui-api/layout
/services/data/v{version}/ui-api/session/csrf
/services/data/v{version}/connect/file/upload/config
/services/data/v{version}/connect/proxy/ui-telemetry
/services/data/v{version}/chatter/users/me
/services/data/v{version}/chatter/users/{userId}
/sfsites/c/_nc_external/system/security/session/SessionTimeServlet
/secur/logout.jsp

We recommend that you use optional chaining fetch?.() instead of a non-null assertion fetch!.(). Optional chaining is useful when you want to use fetch in a shared or cross-surface utility. If you’re not sure where your code is run, use optional chaining and handle the response appropriately.

The read-data examples in the Multi-framework recipes repo demonstrate how to call Chatter Connect API, Apex REST, and UI API REST.

Extracts the node type from a UIAPI connection response shape with the edges and node pattern.

Use NodeOfConnection when your GraphQL response uses the Salesforce connection shape (edges and node) and you want a clean, strongly-typed node type. For example:

Query returns: Account { edges { node { ... } } }
You define: type AccountNode = NodeOfConnection<MyQuery["uiapi"]["query"]["Account"]>
Use AccountNode for transforms, props, and list rendering

If your query doesn’t use connection fields or you already have simple flat generated types, you don’t need to use NodeOfConnection.

When using the Data SDK to access Salesforce data use standard web APIs and npm packages only. These functionalities aren’t supported:

@salesforce scoped modules, except @salesforce/platform-sdk/data
Lightning base components and lightning/* modules
@wire service

Coming from LWC, here’s what to use instead in React.

Don’t use (LWC-only)	Use instead in React
`@salesforce/apex/Class.method`	`dataSdk.fetch?.()` against `/services/apexrest/...`
`@salesforce/schema/Object.Field`	Hardcode the API name as a string in your GraphQL query
`@salesforce/user/Id`, `/CurrentUserId`	GraphQL `uiapi.currentUser` query via `dataSdk.graphql?.query(...)`
`lightning/uiRecordApi`: `get*` calls such as `getRecord` and `getListUi`	`dataSdk.graphql?.query(...)`
`lightning/uiRecordApi`: mutation calls such as `createRecord`, `updateRecord`, and `deleteRecord`	`dataSdk.graphql?.mutate(...)`
`@wire` decorator	React `useEffect` hook and `dataSdk.graphql?.query(...)`; `QueryResult.subscribe` for reactive updates

Use @salesforce/platform-sdk/data for all Salesforce API calls. The SDK handles authentication and CSRF validation. Follow these data access guidelines in order of preference.

Use GraphQL queries and mutations as the preferred way to access data. dataSdk.graphql?.query() and dataSdk.graphql?.mutate() send a POST request to Salesforce GraphQL.
Use UI API via sdk.fetch?.() for data access that calls /services/data/v{version}/ui-api/* or another Salesforce REST endpoint, such as an Apex controller that’s exposed via Apex REST.
Use GraphQL with sdk.fetch?.() if GET request is required, such as when your query and variables are small enough to fit in URL constraints. Or use a GraphQL GET request if you have a dependency on a roundtrip fetch of a CSRF token.
Use Apex REST when you want custom logic that GraphQL doesn’t support.
Don’t call fetch() or axios directly for Salesforce endpoints.

Review the examples in the React App Recipes GitHub repo. Install the app in a scratch org and explore each recipe to understand how to complete a specific task, whether it’s querying data with GraphQL or handling loading, an empty state, or error responses.