Salesforce Data Access

Data SDK Requirement

All Salesforce data access MUST use the Data SDK (
@salesforce/sdk-data
). The SDK handles authentication, CSRF, and base URL resolution.

typescript

import { createDataSDK, gql } from "@salesforce/sdk-data";
import type { ResponseTypeQuery } from "../graphql-operations-types";

const sdk = await createDataSDK();

// GraphQL for record queries/mutations (PREFERRED)
const response = await sdk.graphql?.<ResponseTypeQuery>(query, variables);

// REST for Connect REST, Apex REST, UI API (when GraphQL insufficient)
const res = await sdk.fetch?.("/services/apexrest/my-resource");

Always use optional chaining (

sdk.graphql?.()

sdk.fetch?.()

) — these methods may be undefined in some surfaces.

Preconditions — verify before starting

#	Requirement	How to verify	If missing
1	`@salesforce/sdk-data` installed	Check `package.json` in the UI bundle dir	Cannot proceed — tell user to install it
2	`schema.graphql` at project root	Check if file exists	Run `npm run graphql:schema` from UI bundle dir
3	Custom objects/fields deployed	Run `graphql-search.sh <Entity>` — no output means not deployed	Ask user to deploy metadata and assign permission sets

If preconditions are not met, you may scaffold components, routes, layout, and UI logic, but use empty arrays /

null

for data and mark query locations with

// TODO: add query after schema verification

and include in the plan to go back, resolve requirements and write the GraphQL. Do not write GraphQL query strings until the schema workflow is complete.

Supported APIs

Only the following APIs are permitted. Any endpoint not listed here must not be used.

API	Method	Endpoints / Use Case
GraphQL	`sdk.graphql`	All record queries and mutations via `uiapi { }` namespace
UI API REST	`sdk.fetch`	`/services/data/v{ver}/ui-api/records/{id}` — record metadata when GraphQL is insufficient
Apex REST	`sdk.fetch`	`/services/apexrest/{resource}` — custom server-side logic, aggregates, multi-step transactions
Connect REST	`sdk.fetch`	`/services/data/v{ver}/connect/file/upload/config` — file upload config
Einstein LLM	`sdk.fetch`	`/services/data/v{ver}/einstein/llm/prompt/generations` — AI text generation

Not supported:

Enterprise REST query endpoint (
```
/services/data/v*/query
```
with SOQL) — blocked at the proxy level. Use GraphQL for record reads; use Apex REST if server-side SOQL aggregates are required.
Aura-enabled Apex (
```
@AuraEnabled
```
) — an LWC/Aura pattern with no invocation path from React UI bundles.
Chatter API (
```
/chatter/users/me
```
) — use
```
uiapi { currentUser { ... } }
```
in a GraphQL query instead.
Any other Salesforce REST endpoint not listed in the supported table above.

Decision: GraphQL vs REST

Need	Method	Example
Query/mutate records	`sdk.graphql`	Account, Contact, custom objects
Current user info	`sdk.graphql`	`uiapi { currentUser { Id Name { value } } }`
UI API record metadata	`sdk.fetch`	`/ui-api/records/{id}`
Connect REST	`sdk.fetch`	`/connect/file/upload/config`
Apex REST	`sdk.fetch`	`/services/apexrest/auth/login`
Einstein LLM	`sdk.fetch`	`/einstein/llm/prompt/generations`

GraphQL is preferred for record operations. Use REST only when GraphQL doesn't cover the use case.

GraphQL Non-Negotiable Rules

These rules exist because Salesforce GraphQL has platform-specific behaviors that differ from standard GraphQL. Violations cause silent runtime failures.

HTTP 200 does not mean success — Salesforce returns HTTP 200 even when operations fail. Always parse the
errors
array in the response body.
Schema is the single source of truth — Every entity name, field name, and type must be confirmed via the schema search script before use in a query. Never guess — Salesforce field names are case-sensitive, relationships may be polymorphic, and custom objects use suffixes (
```
__c
```
,
```
__e
```
). Objects added to UI API in v60+ may use a
```
_Record
```
suffix (e.g.,
```
FeedItem_Record
```
instead of
```
FeedItem
```
).
@optional
on all record fields (read queries) — Salesforce field-level security (FLS) causes queries to fail entirely if the user lacks access to even one field. The
```
@optional
```
directive (v65+) tells the server to omit inaccessible fields instead of failing. Apply it to every scalar field, parent relationship, and child relationship. Consuming code must use optional chaining (
```
?.
```
) and nullish coalescing (
```
??
```
).
Correct mutation syntax — Mutations wrap under
```
uiapi(input: { allOrNone: true/false })
```
, not bare
```
uiapi { ... }
```
. Always set
```
allOrNone
```
explicitly. Output fields cannot include child relationships or navigated reference fields.
Explicit pagination — Always include
```
first:
```
in every query. If omitted, the server silently defaults to 10 records. Include
```
pageInfo { hasNextPage endCursor }
```
for any query that may need pagination. Forward-only (
```
first
```
/
```
after
```
) —
```
last
```
/
```
before
```
are unsupported.
SOQL-derived execution limits — Max 10 subqueries per request, max 5 levels of child-to-parent traversal, max 1 level of parent-to-child (no grandchildren), max 2,000 records per subquery. If a query would exceed these, split into multiple requests.
Only requested fields — Only generate fields the user explicitly asked for. Do NOT add extra fields.
Compound fields — When filtering or ordering, use constituent fields (e.g.,
```
BillingCity
```
,
```
BillingCountry
```
), not the compound wrapper (
```
BillingAddress
```
). The compound wrapper is only for selection.

GraphQL Workflow

Step	Action	Key output
1	Acquire schema	`schema.graphql` exists
2	Look up entities	Field names, types, relationships confirmed
3	Generate query	`.graphql` file or inline `gql` tag
4	Generate types	`graphql-operations-types.ts`
5	Validate	Lint + codegen pass

Step 1: Acquire Schema

The

schema.graphql

file (265K+ lines) is the source of truth. Never open or parse it directly — no cat, less, head, tail, editors, or programmatic parsers.

Verify preconditions 1–3 (see Preconditions), then proceed to Step 2.

Step 2: Look Up Entity Schema

Map user intent to PascalCase names ("accounts" →

Account

), then run the search script from the
sfdx-project
folder (project root):

bash

bash scripts/graphql-search.sh Account
# Multiple entities:
bash scripts/graphql-search.sh Account Contact Opportunity

The script outputs seven sections per entity:

Type definition — all queryable fields and relationships
Filter options — available fields for
```
where:
```
conditions
Sort options — available fields for
```
orderBy:
```
Create mutation wrapper —
```
<Entity>CreateInput
```
Create mutation fields —
```
<Entity>CreateRepresentation
```
(fields accepted by create mutations)
Update mutation wrapper —
```
<Entity>UpdateInput
```
Update mutation fields —
```
<Entity>UpdateRepresentation
```
(fields accepted by update mutations)

Maximum 2 script runs. If the entity still can't be found, ask the user — the object may not be deployed.

Entity Identification

If a candidate does not match:

Try
```
__c
```
suffix for custom objects,
```
__e
```
for platform events
Try
```
_Record
```
suffix — objects added in v60+ may use
```
<EntityName>_Record
```
If still unresolved, ask the user — do not guess

Iterative Introspection (max 3 cycles)

Introspect — Run the script for each unresolved entity
Fields — Extract requested field names and types from the type definition
References — Identify reference fields. If polymorphic (multiple types), use inline fragments. Add newly discovered entity types to the working list.
Child relationships — Identify Connection types. Add child entity types to the working list.
Repeat if unresolved entities remain (max 3 cycles)

Hard stops: If no data returned for an entity, stop — it may not be deployed. If unknown entities remain after 3 cycles, ask the user. Do not generate queries with unconfirmed entities or fields.

Step 3: Generate Query

Every field name must be verified from the script output in Step 2.

Read Query Template

graphql

query QueryName($after: String) {
  uiapi {
    query {
      EntityName(
        first: 10
        after: $after
        where: { ... }
        orderBy: { ... }
      ) {
        edges {
          node {
            Id
            FieldName @optional { value }
            # Parent relationship (non-polymorphic)
            Owner @optional { Name { value } }
            # Parent relationship (polymorphic — use fragments)
            What @optional {
              ...WhatAccount
              ...WhatOpportunity
            }
            # Child relationship — max 1 level, no grandchildren
            Contacts @optional(first: 10) {
              edges { node { Name @optional { value } } }
            }
          }
        }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
}

fragment WhatAccount on Account {
  Id
  Name @optional { value }
}
fragment WhatOpportunity on Opportunity {
  Id
  Name @optional { value }
}

Consuming code must defend against missing fields:

typescript

const name = node.Name?.value ?? "";
const relatedName = node.Owner?.Name?.value ?? "N/A";

Filtering

graphql

# Implicit AND
Account(where: { Industry: { eq: "Technology" }, AnnualRevenue: { gt: 1000000 } })

# Explicit OR
Account(where: { OR: [{ Industry: { eq: "Technology" } }, { Industry: { eq: "Finance" } }] })

# NOT
Account(where: { NOT: { Industry: { eq: "Technology" } } })

# Date literal
Opportunity(where: { CloseDate: { eq: { value: "2024-12-31" } } })

# Relative date
Opportunity(where: { CloseDate: { gte: { literal: TODAY } } })

# Relationship filter (nested objects, NOT dot notation)
Contact(where: { Account: { Name: { like: "Acme%" } } })

# Polymorphic relationship filter
Account(where: { Owner: { User: { Username: { like: "admin%" } } } })

String equality (

eq

) is case-insensitive. Both 15-char and 18-char record IDs are accepted.

Ordering

graphql

Account(
  first: 10,
  orderBy: { Name: { order: ASC }, CreatedDate: { order: DESC } }
) { ... }

Unsupported for ordering: multi-select picklist, rich text, long text area, encrypted fields. Add

Id

as tie-breaker for deterministic ordering.

UpperBound Pagination (v59+)

For >200 records per page or >4,000 total records, use

upperBound

first

must be 200–2000 when set.

graphql

Account(first: 2000, after: $cursor, upperBound: 10000) {
  edges { node { Id Name @optional { value } } }
  pageInfo { hasNextPage endCursor }
}

Semi-Join and Anti-Join

Filter a parent entity by conditions on child entities using

inq

(semi-join) or

ninq

(anti-join) on the parent's

Id

. If the only condition is child existence, use

Id: { ne: null }

graphql

query SemiJoinExample {
  uiapi {
    query {
      Account(where: {
        Id: {
          inq: {
            Contact: { LastName: { like: "Smith%" } }
            ApiName: "AccountId"
          }
        }
      }, first: 10) {
        edges { node { Id Name @optional { value } } }
      }
    }
  }
}

Replace

inq

with

ninq

for anti-join. Restrictions: no

OR

in subquery, no

orderBy

in subquery, no nesting joins within each other.

Current User

Use

uiapi.currentUser

(no arguments) instead of the standard query pattern:

graphql

query CurrentUser {
  uiapi { currentUser { Id Name { value } } }
}

Field Value Wrappers

Schema fields use typed wrappers — access via

.value

Wrapper Type	Underlying	Wrapper Type	Underlying
`StringValue`	`String`	`BooleanValue`	`Boolean`
`IntValue`	`Int`	`DoubleValue`	`Double`
`CurrencyValue`	`Currency`	`PercentValue`	`Percent`
`DateTimeValue`	`DateTime`	`DateValue`	`Date`
`PicklistValue`	`Picklist`	`LongValue`	`Long`
`IDValue`	`ID`	`TextAreaValue`	`TextArea`
`EmailValue`	`Email`	`PhoneNumberValue`	`PhoneNumber`
`UrlValue`	`Url`

All wrappers also expose

displayValue: String

(server-rendered via

toLabel()

format()

) — use for UI display instead of formatting client-side.

Mutation Template

Mutations are GA in API v66+. Three operations: Create, Update, Delete.

graphql

# Create
mutation CreateAccount($input: AccountCreateInput!) {
  uiapi(input: { allOrNone: true }) {
    AccountCreate(input: $input) {
      Record { Id Name { value } }
    }
  }
}

# Update — must include Id
mutation UpdateAccount {
  uiapi(input: { allOrNone: true }) {
    AccountUpdate(input: { Id: "001xx000003GYkZAAW", Account: { Name: "New Name" } }) {
      Record { Id Name { value } }
    }
  }
}

Input constraints:

Create: Required fields (unless
```
defaultedOnCreate
```
), only
```
createable
```
fields, no child relationships. Reference fields set by
```
ApiName
```
(e.g.,
```
AccountId
```
).
Update: Must include
```
Id
```
, only
```
updateable
```
fields, no child relationships.
Delete:
```
Id
```
only.
IdOrRef
type: The
```
Id
```
field in Update and Delete inputs uses the
```
IdOrRef
```
type, which accepts either a literal record ID (e.g.,
```
"001xx..."
```
) or a mutation chaining reference (
```
"@{Alias}"
```
). Reference fields in Create inputs (e.g.,
```
AccountId
```
) also accept
```
@{Alias}
```
for chaining.
Raw values: No commas, currency symbols, or locale formatting (e.g.,
```
80000
```
not
```
"$80,000"
```
).

Output constraints:

Create/Update: Exclude child relationships, exclude navigated reference fields (only
```
ApiName
```
member allowed). Output field is always named
```
Record
```
.
Delete:
```
Id
```
only.

allOrNone
semantics:

```
true
```
(default) — All operations succeed or all roll back.
```
false
```
— Independent operations succeed individually, but dependent operations (using
```
@{alias}
```
) still roll back together.

Mutation Chaining

Chain related mutations using

@{alias}

references to

Id

from earlier mutations. Required for parent-child creation (nested child creates are not supported).

graphql

mutation CreateAccountAndContact {
  uiapi(input: { allOrNone: true }) {
    AccountCreate(input: { Account: { Name: "Acme" } }) {
      Record { Id }
    }
    ContactCreate(input: { Contact: { LastName: "Smith", AccountId: "@{AccountCreate}" } }) {
      Record { Id }
    }
  }
}

Rules:

must come before

in the query.

@{A}

is always the

Id

from mutation

. Only

Create

Delete

can be chained from (not

Update

Delete Mutation

Delete uses generic

RecordDeleteInput

(not entity-specific). Output is

Id

only — no

Record

field.

graphql

mutation DeleteAccount($id: ID!) {
  uiapi(input: { allOrNone: true }) {
    AccountDelete(input: { Id: $id }) {
      Id
    }
  }
}

Object Metadata & Picklist Values

Use

uiapi { objectInfos(...) }

to fetch field metadata or picklist values. Pass either

apiNames

objectInfoInputs

— never both.

typescript

// Object metadata
const GET_OBJECT_INFO = gql`
  query GetObjectInfo($apiNames: [String!]!) {
    uiapi {
      objectInfos(apiNames: $apiNames) {
        ApiName
        label
        labelPlural
        fields { ApiName label dataType updateable createable }
      }
    }
  }
`;

// Picklist values (use objectInfoInputs + inline fragment)
const GET_PICKLIST_VALUES = gql`
  query GetPicklistValues($objectInfoInputs: [ObjectInfoInput!]!) {
    uiapi {
      objectInfos(objectInfoInputs: $objectInfoInputs) {
        ApiName
        fields {
          ApiName
          ... on PicklistField {
            picklistValuesByRecordTypeIDs {
              recordTypeID
              picklistValues { label value }
            }
          }
        }
      }
    }
  }
`;

Step 4: Generate Types (codegen)

After writing the query (whether in a

.graphql

file or inline with

gql

), generate TypeScript types:

bash

# Run from UI bundle dir
npm run graphql:codegen

Output:

src/api/graphql-operations-types.ts

Generated type naming conventions:

<OperationName>Query

<OperationName>Mutation

— response types

<OperationName>QueryVariables

<OperationName>MutationVariables

— variable types

Always import and use the generated types when calling

sdk.graphql

typescript

import type { GetAccountsQuery, GetAccountsQueryVariables } from "../graphql-operations-types";

const response = await sdk.graphql?.<GetAccountsQuery, GetAccountsQueryVariables>(GET_ACCOUNTS, variables);

Use

NodeOfConnection<T>

to extract the node type from a Connection for cleaner typing:

typescript

import { type NodeOfConnection } from "@salesforce/sdk-data";

type AccountNode = NodeOfConnection<GetAccountsQuery["uiapi"]["query"]["Account"]>;

Step 5: Validate & Test

Lint:
```
npx eslint <file>
```
from UI bundle dir
codegen:
```
npm run graphql:codegen
```
from UI bundle dir

Common Error patterns

Error Contains	Resolution
`Cannot query field` / `ValidationError`	Field name wrong — re-run `graphql-search.sh <Entity>`
`Unknown type`	Type name wrong — verify PascalCase entity name via script
`Unknown argument`	Argument wrong — check Filter/OrderBy sections in script output
`invalid syntax` / `InvalidSyntax`	Fix syntax per error message
`VariableTypeMismatch` / `UnknownType`	Correct argument type from schema
`invalid cross reference id`	Entity deleted — ask for valid Id
`OperationNotSupported`	Check object availability and API version
`is not currently available in mutation results`	Remove field from mutation output
`Cannot invoke JsonElement.isJsonObject()`	Use API version 64+ for update mutation `Record` selection

On PARTIAL If a mutation returns both data and errors (partial success): Report inaccessible fields, explain they cannot be in mutation output, offer to remove them. Wait for user consent before changing.

UI Bundle Integration (React)

Two integration patterns:

Pattern 1 — External

.graphql

file (complex queries)

One operation per
.graphql
file. Each file contains exactly one

query

mutation

(plus its fragments). Do not combine multiple operations in a single file.

typescript

import { createDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
import MY_QUERY from "./query/myQuery.graphql?raw"; // ?raw suffix required
import type { GetMyDataQuery, GetMyDataQueryVariables } from "../graphql-operations-types";

const sdk = await createDataSDK();
const response = await sdk.graphql?.<GetMyDataQuery, GetMyDataQueryVariables>(MY_QUERY, variables);

After creating/changing

.graphql

files, run

npm run graphql:codegen

to generate types into

src/api/graphql-operations-types.ts

Pattern 2 — Inline

gql

tag (simple queries)

Must use
gql
— plain template strings bypass ESLint schema validation.

typescript

import { createDataSDK, gql } from "@salesforce/sdk-data";
import type { GetAccountsQuery } from "../graphql-operations-types";

const GET_ACCOUNTS = gql`
  query GetAccounts {
    uiapi {
      query {
        Account(first: 10) {
          edges { node { Id Name @optional { value } } }
        }
      }
    }
  }
`;

const sdk = await createDataSDK();
const response = await sdk.graphql?.<GetAccountsQuery>(GET_ACCOUNTS);

Error Handling

typescript

// Strict (default) — any errors = failure
if (response?.errors?.length) {
  throw new Error(response.errors.map(e => e.message).join("; "));
}

// Tolerant — log errors, use available data
if (response?.errors?.length) {
  console.warn("GraphQL partial errors:", response.errors);
}

// Discriminated — fail only when no data returned
if (!response?.data && response?.errors?.length) {
  throw new Error(response.errors.map(e => e.message).join("; "));
}

const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];

REST API Patterns

Use

sdk.fetch

when GraphQL is insufficient. See the Supported APIs table for the full allowlist.

typescript

declare const __SF_API_VERSION__: string;
const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";

// Connect — file upload config
const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/connect/file/upload/config`);

// Apex REST (no version in path)
const res = await sdk.fetch?.("/services/apexrest/auth/login", {
  method: "POST",
  body: JSON.stringify({ email, password }),
  headers: { "Content-Type": "application/json" },
});

// UI API — record with metadata (prefer GraphQL for simple reads)
const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/ui-api/records/${recordId}`);

// Einstein LLM
const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/prompt/generations`, {
  method: "POST",
  body: JSON.stringify({ promptTextorId: prompt }),
});

Current user: Do not use Chatter (

/chatter/users/me

). Use GraphQL instead:

typescript

const GET_CURRENT_USER = gql`
  query CurrentUser {
    uiapi { currentUser { Id Name { value } } }
  }
`;
const response = await sdk.graphql?.(GET_CURRENT_USER);

Directory Structure

<project-root>/                              ← SFDX project root
├── schema.graphql                           ← grep target (lives here)
├── sfdx-project.json
├── scripts/graphql-search.sh                ← schema lookup script
└── force-app/main/default/uiBundles/<app-name>/  ← UI bundle dir
    ├── package.json                         ← npm scripts
    └── src/

Command	Run From	Why
`npm run graphql:schema`	UI bundle dir	Script in UI bundle's package.json
`npm run graphql:codegen`	UI bundle dir	Generate GraphQL types
`npx eslint <file>`	UI bundle dir	Reads eslint.config.js
`bash scripts/graphql-search.sh <Entity>`	project root	Schema lookup

Quick Reference

Schema Lookup (from project root)

Run the search script to get all relevant schema info in one step:

bash

bash scripts/graphql-search.sh <EntityName>

Script Output Section	Used For
Type definition	Field names, parent/child relationships
Filter options	`where:` conditions
Sort options	`orderBy:`
CreateRepresentation	Create mutation field list
UpdateRepresentation	Update mutation field list

Error Categories

Error Contains	Resolution
`Cannot query field`	Field name is wrong — run `graphql-search.sh <Entity>` and use the exact name from the Type definition section
`Unknown type`	Type name is wrong — run `graphql-search.sh <Entity>` to confirm the correct PascalCase entity name
`Unknown argument`	Argument name is wrong — run `graphql-search.sh <Entity>` and check Filter or OrderBy sections
`invalid syntax`	Fix syntax per error message
`validation error`	Field name is wrong — run `graphql-search.sh <Entity>` to verify
`VariableTypeMismatch`	Correct argument type from schema
`invalid cross reference id`	Entity deleted — ask for valid Id

Checklist

All field names verified via search script (Step 2)
```
@optional
```
applied to all record fields (reads)
Mutations use
```
uiapi(input: { allOrNone: ... })
```
wrapper
```
first:
```
specified in every query
Optional chaining in consuming code
```
errors
```
array checked in response handling
Lint passes:
```
npx eslint <file>
```

using-ui-bundle-salesforce-data

NPX Install

Tags

SKILL.md Content

Salesforce Data Access

Data SDK Requirement

Preconditions — verify before starting

Supported APIs

Decision: GraphQL vs REST

GraphQL Non-Negotiable Rules

GraphQL Workflow

Step 1: Acquire Schema

Step 2: Look Up Entity Schema

Entity Identification

Iterative Introspection (max 3 cycles)

Step 3: Generate Query

Read Query Template

Filtering

Ordering

UpperBound Pagination (v59+)

Semi-Join and Anti-Join

Current User

Field Value Wrappers

Mutation Template

Mutation Chaining

Delete Mutation

Object Metadata & Picklist Values

Step 4: Generate Types (codegen)

Step 5: Validate & Test

Common Error patterns

UI Bundle Integration (React)

Pattern 1 — External
`.graphql`
file (complex queries)

Pattern 2 — Inline
`gql`
tag (simple queries)

Error Handling

REST API Patterns

Directory Structure

Quick Reference

Schema Lookup (from project root)

Error Categories

Checklist