Work with Data SDK

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.

1import { createDataSDK, gql } from "@salesforce/platform-sdk/data";
2import type { DataSDK, SDKOptions, NodeOfConnection } from "@salesforce/platform-sdk/data";
3const dataSdk = await createDataSDK();

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.

Creates a new DataSDK instance.

1async function createDataSDK(options?: DataSDKOptions): Promise<DataSDK>;

1Promise<DataSDK>

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 target the same base URL and API version, which improves performance and consistency when multiple components query the same data. Multiple calls to createDataSDK() that resolve to the same base URL and API version share the same GraphQL cache, and cache updates from one SDK instance are visible to all other instances that share that cache. Instances that target different API versions get isolated caches, so a query response cached under one version is never served to an instance on another version.

1// Both instances resolve to the same base URL and API version,
2// so they share the same GraphQL cache
3const sdk1 = await createDataSDK();
4const sdk2 = await createDataSDK();
5
6// Query from sdk1 populates the cache
7await sdk1.graphql?.query<AccountData>({ query: GET_ACCOUNTS });
8
9// Query from sdk2 can read from the same cache (cache hit)
10await sdk2.graphql?.query<AccountData>({ query: GET_ACCOUNTS });
11
12// An instance on a different API version has an isolated cache,
13// so this query does not hit the cache populated above
14const sdk3 = await createDataSDK({ webapp: { apiVersion: "63.0" } });
15await sdk3.graphql?.query<AccountData>({ query: GET_ACCOUNTS });

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.

1import { createDataSDK, gql } from "@salesforce/platform-sdk/data";
2
3const MY_QUERY = gql`
4  query MyQuery {
5    uiapi {
6      ...
7    }
8  }
9`;

See GraphQL Queries in Data SDK.

Defines the top-level SDK surface that exposes an optional API version along with optional GraphQL and fetch APIs. The apiVersion, graphql, and fetch members are all optional as they’re supported in specific environments only.

1interface DataSDK {
2  readonly apiVersion?: string;
3  graphql?: DataSDKGraphQL;
4  fetch?: typeof fetch;
5}

• apiVersion: string—Read-only. The Salesforce API version the SDK resolved for the current environment, such as 64.0. Set it with the apiVersion option on createDataSDK(). It’s absent in environments that don’t resolve to a versioned API path.

GraphQL is the preferred way to work with record data.

1import { createDataSDK } from "@salesforce/platform-sdk/data";
2const dataSdk = await createDataSDK();
3// GraphQL — use optional chaining
4const result = await dataSdk.graphql?.query<MyQueryType>({
5  query,
6  variables,
7});

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

Pass options in several ways:

• Use graphql.query() based on the QueryOptions Interface.
• Use graphql.mutate() based on the MutateOptions Interface.

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().

1import { createDataSDK } from "@salesforce/platform-sdk/data";
2const dataSdk = await createDataSDK();
3// Prefer GraphQL for record/user data:
4const me = await dataSdk.graphql?.query({
5  query: gql`
6    query {
7      uiapi {
8        currentUser {
9          Id
10          Name {
11            value
12          }
13        }
14      }
15    }
16  `,
17});
18
19// Use fetch only for REST endpoints that GraphQL doesn't cover.
20// Replace {version} with the API version you want to use, for example `67.0`.
21
22// Example: UI API
23const result2 = await dataSdk.fetch?.("/services/data/v{version}/ui-api/records/{recordId}");
24const userData = await result2?.json();

The fetch wrapper handles:

• CSRF token management
• Base path resolution
• 401/403 callback hooks
• Language and locale preferences

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.

1interface DataSDKGraphQL {
2  /**
3   * Runs a GraphQL query.
4   *
5   * Resolves with { data, errors, subscribe, refresh } once the underlying
6   * request settles — either from the cache (cached surfaces only) or from
7   * the network. subscribe() streams subsequent snapshots; refresh() re-issues
8   * the request, bypassing the cache where one exists and propagating the
9   * result to subscribers.
10   */
11  query<T, V = Record<string, unknown>>(options: QueryOptions<V>): Promise<QueryResult<T>>;
12
13  /**
14   * Runs a GraphQL mutation. Pass-through to the underlying transport — does
15   * not read or write the cache. Queries and subscriptions passed here are
16   * rejected via the resolved errors field.
17   */
18  mutate<T, V = Record<string, unknown>>(options: MutateOptions<V>): Promise<MutationResult<T>>;
19}

Describes the raw GraphQL request that the SDK sends to the transport. QueryOptions and MutateOptions are the method-specific options. GraphQLRequest is the underlying request shape they resolve to.

1interface GraphQLRequest<V = Record<string, unknown>> {
2  query: string;
3  variables?: V;
4  operationName?: string;
5  headers?: GraphQLRequestHeaders;
6}

Describes the raw GraphQL response envelope that the transport returns, before the SDK wraps it in a reactive QueryResult<T> or a MutationResult<T>.

1interface GraphQLResponse<T> {
2  data: T;
3  errors?: GraphQLError[];
4}

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

1interface QueryOptions<V = Record<string, unknown>> {
2  query: string;
3  variables?: V;
4  operationName?: string;
5  cacheControl?: CacheControl;
6  headers?: GraphQLRequestHeaders;
7}

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

1interface MutateOptions<V = Record<string, unknown>> {
2  mutation: string;
3  variables?: V;
4  operationName?: string;
5  headers?: GraphQLRequestHeaders;
6}

The type of the per-request headers option on QueryOptions, MutateOptions, and GraphQLRequest. It’s an alias for the standard HeadersInit, so you can pass a plain object, an array of [name, value] tuples, or a Headers instance.

1type GraphQLRequestHeaders = HeadersInit;

For more information, see Per-Request Headers.

Describes the reactive query result that’s returned by graphql.query(). It extends QuerySnapshot<T>, so it carries the same data and errors fields and adds subscribe() and refresh().

1interface QueryResult<T> extends QuerySnapshot<T> {
2  subscribe(cb: QuerySubscriber<T>): Unsubscribe;
3  refresh(): Promise<void>;
4}

• data: T | undefined—The resolved query data, or undefined when the query didn’t resolve data.
• errors: GraphQLError[]—Optional. Any GraphQL or transport errors.
• subscribe(cb): (cb: QuerySubscriber<T>) => Unsubscribe—Registers a callback that receives a QuerySnapshot<T> on each subsequent resolution. Returns an Unsubscribe function.
• refresh(): () => Promise<void>—Re-issues the underlying request and propagates the result to subscribers.

The callback type passed to QueryResult.subscribe(). It receives a QuerySnapshot<T> on each new resolution.

1type QuerySubscriber<T> = (snapshot: QuerySnapshot<T>) => void;

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

1interface MutationResult<T> {
2  data: T | undefined;
3  errors?: GraphQLError[];
4}

Describes the snapshot object passed to subscribe() callbacks.

1interface QuerySnapshot<T> {
2  data: T | undefined;
3  errors?: GraphQLError[];
4}

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

1interface GraphQLError {
2  message: string;
3  locations?: { line: number, column: number }[];
4  path?: string[];
5  extensions?: Record<string, unknown>;
6}

• message: string—The error message.
• locations: { line: number, column: number }[]—Optional. Where in the query the error occurred.
• path: string[]—Optional. The response path to the field that errored.
• extensions: Record<string, unknown>—Optional. Free-form error metadata, the GraphQL extensions slot. Server-returned errors carry whatever extensions the resolver attached, verbatim.

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

1type Unsubscribe = () => void;
2
3type CacheControl = "no-cache" | "only-if-cached" | { type: "max-age", maxAge: number };

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.

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

1import { type NodeOfConnection } from "@salesforce/platform-sdk/data";
2// Extract Account node type from the query response
3type AccountNode = NodeOfConnection<GetHighRevenueAccountsQuery["uiapi"]["query"]["Account"]>;

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

If you’re familiar with Lightning Web Components (LWC), here’s what to use instead in Multi-Framework.

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.

Data SDK support differs by surface. Data SDK supports web apps, such as those built using React or Angular. It also fully support micro-frontends.

Because Data SDK support varies, use optional chaining (sdk.graphql?., sdk.fetch?.) so your code stays portable across surfaces.

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.

j

Salesforce Multi-Framework Overview

Configure Your Org for React Development

Integrate Your React App with the Headless 360 Platform

Style Your React Apps

Integrate Agentforce Conversation Client

Access Salesforce Data and Platform Capabilities

Work with the Data SDK

Access Salesforce APIs

GraphQL Query Parameters

GraphQL Mutate Parameters

GraphQL Queries

GraphQL Mutations

Error Handling

Cache Control

Per-Request Headers

Data SDK Extensions

Get App Identity

Manage the Host UI

Localize Your App

Use Skills for Data Access