| name | experience-ui-bundle-salesforce-data-access |
| description | MUST activate whenever a uiBundles/*/src/ project reads, writes, or displays Salesforce data — INCLUDING building a page, list, table, card grid, dashboard, or form that shows, filters, counts, or edits records of any object (e.g. Property__c, Account, Case), even when the prompt names only the UI or the object and never says query, GraphQL, or SDK. Records behind such a component come from Salesforce, so use this ALONGSIDE experience-ui-bundle-frontend-generate: that skill styles the component, this one wires its data. Also triggers on @salesforce/platform-sdk imports, sdk.graphql.query / mutate / sdk.fetch calls, *.graphql files, or stale data needing force-refresh. New read/write work uses the current @salesforce/platform-sdk API; migrate only EXISTING old @salesforce/sdk-data callable code. Not for pure styling/layout with no records, app shell, file upload, or auth/search scaffolding. DO NOT TRIGGER for OAuth, object/field schema changes, Bulk/Tooling/Metadata API, or declarative automation. |
| metadata | {"version":"2.2","minApiVersion":"66.0","relatedSkills":["experience-ui-bundle-frontend-generate","platform-metadata-deploy"],"cliTools":[{"tool":["node"],"semver":">=18.0.0"},{"tool":["npm"],"semver":">=9.0.0"},{"tool":["npx"],"semver":">=9.0.0"},{"tool":["sf"],"semver":">=2.0.0"}]} |
Salesforce Data Access (UI bundles)
All Salesforce data access in a UI bundle goes through the @salesforce/platform-sdk
data SDK. The SDK handles auth, CSRF, and base-URL resolution, and — on the WebApp
surface — caches every GraphQL query by default.
This file is the workflow + guardrail spine. Depth lives in linked docs:
- references/graphiti-cli.md — the
graphiti CLI (sf-gql-*
commands) that compiles a small JSON spec into a schema-correct, guardrail-applied query +
variables + types. The preferred way to author the GraphQL in steps below; falls back to the
schema-grep script when unavailable.
- references/sdk-api.md — the new call API:
query/mutate,
QueryResult, typing, error-handling stances.
- references/caching.md — on-by-default cache + the two refresh
modes (
result.refresh/subscribe vs per-call cacheControl).
- references/graphql-hand-authoring.md — schema lookup, read /
mutation templates, every platform guardrail (
@optional, pagination, limits,
semi-join, wrappers, error table…).
- references/rest-and-integration.md —
sdk.fetch,
the supported-API allowlist, and the reactive/lifecycle integration patterns.
- references/migration.md — old
@salesforce/sdk-data callable code
→ new namespace. The only place the dead API appears as usable code.
The one-paragraph mental model
const sdk = await createDataSDK(). Then sdk.graphql is a namespace, not a
function: sdk.graphql!.query({...}) for reads, sdk.graphql!.mutate({...})
for writes. On WebApp, every query() is cached by default (300s). HTTP 200 never
means success — always check result.errors. Verify every entity and field against the
schema before you query it: one unverified field fails the whole query at runtime, and
schema.graphql is too large to eyeball — look it up.
import { createDataSDK, gql } from "@salesforce/platform-sdk";
const sdk = await createDataSDK();
const result = await sdk.graphql!.query({ query: GET_ACCOUNTS, variables });
if (result.errors?.length) throw new Error(result.errors.map((e) => e.message).join("; "));
const rows = result.data?.uiapi?.query?.Account?.edges?.map((e) => e.node) ?? [];
Typed call params (query<GetAccountsQuery, GetAccountsQueryVariables>), the CacheControl
type, and NodeOfConnection<T> (extracts a node type from a Connection for clean typing) all
live in references/sdk-api.md.
This changed (breaking — PR #502). The previous callable sdk.graphql(...) form and the
previous package name are dead — the code above is the only correct form. If you encounter
the old API in existing code (or a stale dist/ artifact), don't copy it; convert it per
Working on existing code.
sdk.graphql! is WebApp-only. The non-null assertion above is correct only if the
bundle runs solely on WebApp. On other surfaces it can crash — decide before you write it.
See Surfaces — ! vs guard below.
Ground the SDK contract on the installed types (tier-2a)
@salesforce/platform-sdk force-publishes on a shared version line and moves
fast. This SKILL's prose is a point-in-time snapshot of the call contract; the
installed declarations are authoritative for the version you actually have.
Before writing any query/mutate, read the installed types and let them win:
node_modules/@salesforce/platform-sdk/dist/core/data.d.ts — query/mutate
signatures, QueryResult (has subscribe/refresh) vs MutationResult (has
neither, by design), the CacheControl union, the default TTL.node_modules/@salesforce/platform-sdk/dist/data/index.d.ts — createDataSDK,
gql, NodeOfConnection.
Precedence — installed .d.ts beats this SKILL's prose. If a signature,
type, or default here disagrees with the installed declaration, follow the
declaration and note the drift; do not "correct" the types to match the prose.
Grounding ladder (one model, two axes):
| Tier | Grounds | Answers | Via |
|---|
| tier-1 | GraphQL schema | what data exists | graphiti / graphql-search.sh (Precondition #2) |
| tier-2a | SDK contract | how you call it | the installed .d.ts above |
| spine | this SKILL.md | workflow + guardrails that orchestrate both; the fallback when a tier can't ground | |
Fallback when the .d.ts is absent — the package is installed but ships
no declarations (a stale or types-stripped build artifact). Then use this SKILL's
prose as best-effort. This fallback does not cover a missing package: if
@salesforce/platform-sdk isn't installed, stop and install it (Precondition #1)
— do not author calls from prose against a dependency you don't have.
Surfaces — sdk.graphql! vs guard
createDataSDK() runs on multiple surfaces, and sdk.graphql / sdk.fetch are genuinely
optional (typed graphql?: …). Whether you may assert them with ! depends entirely on
where the bundle runs — this is the one surface decision that turns into a runtime crash if
you get it wrong, so make it explicitly before writing any query/mutate call:
| Surface(s) | sdk.graphql | Write |
|---|
| WebApp only | always present | sdk.graphql!.query({...}) — ! is safe; every shipped WebApp consumer uses it |
| Mosaic / OpenAI / MCPApps (or any bundle that might run off-WebApp) | can be undefined | guard first (if (!sdk.graphql) return …), then call |
Rule of thumb: if you cannot prove the bundle is WebApp-only, guard. A bare sdk.graphql!
that later ships to another surface throws Cannot read properties of undefined at runtime —
TypeScript won't catch it because ! silences exactly that check (same applies to sdk.fetch!).
The portable guard snippet lives in references/sdk-api.md.
Step 0 — Route the task
GraphQL covers far more than record reads and writes — prefer it for anything the uiapi
namespace exposes (see Beyond record CRUD). Reach for REST only when
the data genuinely lives outside uiapi (Apex REST, file upload, Einstein) — see
references/rest-and-integration.md.
Preconditions — verify before writing any query
<skill-dir> below is wherever this skill is installed (the directory this
SKILL.md loaded from). The schema-lookup script ships inside it. The script does
not hunt for schema.graphql by walking up the tree — an ancestor schema can
belong to a different org and would validate fields against the wrong one. Resolve
the schema explicitly: run from the SFDX project root (where schema.graphql lives),
or pass --schema <path> / set GRAPHQL_SCHEMA=<path>. The script echoes the schema
it resolved ([graphql-search] using schema: … on stderr) — glance at it to confirm
you grounded against the right file.
| # | Requirement | Verify | If missing |
|---|
| 1 | @salesforce/platform-sdk installed and its contract read | package.json in the UI bundle dir lists it; then read node_modules/@salesforce/platform-sdk/dist/core/data.d.ts + dist/data/index.d.ts and let them win over this SKILL's prose (tier-2a) | Not installed → tell user to install it; cannot proceed. Installed but .d.ts absent (stale artifact) → use prose fallback |
| 2 | A grounding tool resolves | Preferred: npx graphiti sf-gql-discover '{"org":"<alias>","mode":"list_objects"}' from the UI bundle dir returns objects. Fallback: bash <skill-dir>/scripts/graphql-search.sh <Entity> from the project root prints a lookup, not "schema.graphql not found" | No graphiti dep / org won't prime → use the script. Script can't find schema.graphql → pass --schema <path>, or npm run graphql:schema from the UI bundle dir. (references/graphiti-cli.md covers CLI setup) |
| 3 | Target objects/fields deployed | The object appears in sf-gql-discover (or graphql-search.sh <Entity> returns output) | Entity absent usually means it isn't deployed (or the cache/schema is stale). Refresh: npx graphiti sf-gql-connect '{"org":"<alias>","forceRefresh":true}' (CLI) or npm run graphql:schema (script). If still absent, deploy the metadata (the platform-metadata-deploy skill handles this) and assign the permission sets, then re-check |
If preconditions aren't met you may still scaffold components, routes, and layout — but
use empty arrays / null for data, mark query sites with
// TODO: add query after schema verification, and add a plan item to return. Do not
write GraphQL strings until the schema workflow is complete.
Read workflow
-
Look up the schema first — never guess a name. Preferred (graphiti): when the exact
API name is at all uncertain, list before you describe —
npx graphiti sf-gql-discover '{"org":"<alias>","mode":"list_objects","search":"<intent>"}'
to find the real name, then
npx graphiti sf-gql-discover '{"org":"<alias>","mode":"describe_object","object":"<Entity>"}'
for exact field/type names, picklist values, filterable/sortable. An empty list or missing object
is a fact about the org (wrong name or not deployed), not a tool failure — re-list or
forceRefresh; do not fall back to the script for this (see guardrail 2). Fallback is
only for a CLI that genuinely can't run (no graphiti dep / org won't prime):
bash <skill-dir>/scripts/graphql-search.sh <Entity> from the SFDX project root.
(Full rules: references/graphql-hand-authoring.md.)
-
Write the query. Preferred — compile it with graphiti:
npx graphiti sf-gql-list '{"org":"<alias>","object":"<Entity>","fields":[…],"first":N}'
returns a { query, variables, types, warnings } envelope with @optional, value/displayValue,
edges/node, and first:/pageInfo already applied. Confirm warnings: [] (a non-empty
array means the object wasn't in the primed schema — the query is degraded; don't ship it), then
paste the query verbatim into inline gql (simple) or an external .graphql file (one operation
per file, imported with the bundler's ?raw suffix — import Q from "./q.graphql?raw" brings the
file in as a plain string). Fallback — hand-author: apply @optional to every selectable
FLS-gated field — scalar leaf fields (Name @optional { value }) and parent/child
relationships and the fields inside them — but NOT on Id, on connection plumbing
(edges, node, the connection field itself), or on pageInfo; the graphiti output leaves
those bare and is the canonical placement. Always set , include if it may
page. Either way, full mechanics and the primed-vs-degraded behavior:
.
Defend consuming code with ?./?? (because @optional can omit fields). Error-handling
stances (strict / tolerant / discriminated) and NodeOfConnection typing: references/sdk-api.md.
Write workflow
1–3 as above (schema lookup → write the mutation → codegen). To compile the mutation with
graphiti, use sf-gql-create / sf-gql-update / sf-gql-delete — they emit the
uiapi { <Object>Create(input: $input) { Record {…} } } shape; the types field tells you
the input shape. Details: references/graphiti-cli.md.
4. Call mutate() — note the option key is mutation, not query, and that
mutations are never cached. The runtime variables shape differs per operation —
values are raw (never {value}-wrapped; that wrapper is a read-shape thing and breaks
writes) and nest under the entity key:
variables: { input: { Account: { Name: "Acme", Industry: "Technology" } } }
variables: { input: { Id: "001…", Account: { Industry: "Finance" } } }
variables: { input: { Id: "001…" } }
const { data, errors } = await sdk.graphql!.mutate<CreateAccountMutation, CreateAccountMutationVariables>({
mutation: CREATE_ACCOUNT,
variables: { input: { Account: { Name: "Acme" } } },
});
if (errors?.length) throw new Error(errors.map((e) => e.message).join("; "));
This is the variables shape the spine owns; the CLI types-field interpretation is in
references/graphiti-cli.md and the GraphQL-document field constraints
(createable/updateable, ApiName references, @{alias} chaining) in
references/graphql-hand-authoring.md.
5. Re-freshen affected reads. mutate() has no refresh. To update a live list
after a write, hold the QueryResult from your earlier query() call (e.g.
accountsResult) and call await accountsResult.refresh() (forced re-fetch, pushes
to subscribers) — note this is the read's handle, not anything mutate() returns. See
Freshness & caching.
Mutation syntax is exacting: wrap under uiapi(input: { allOrNone: ... }), only
createable/updateable fields, Create/Update output is always Record but Delete has no
Record field — select Id only. Full template + chaining + constraints:
references/graphql-hand-authoring.md.
Beyond record CRUD
The uiapi namespace is not just record reads/writes. Before reaching for REST, check
whether GraphQL already covers it — the same sdk.graphql!.query() call, different
sub-selection. The top-level uiapi fields:
| Need | Use | Returns |
|---|
| Query records | uiapi { query { <Entity>(...) } } | records (the Read workflow) |
| Counts / sums / grouped rollups without pulling rows | uiapi { aggregate { <Entity>(groupBy: …) } } | aggregated buckets |
Object/field metadata — labels, data types, createable/updateable, record types | uiapi { objectInfos(apiNames: […]) } | ObjectInfo[] |
| Picklist values (per record type) | uiapi { objectInfos(objectInfoInputs: […]) { fields … on PicklistField { … } } } | picklist values |
| Related-list metadata — display columns, ordering for a parent's related list | uiapi { relatedListByName(parentApiName, relatedListName) } | RelatedListInfo |
Same rules as record reads: verify every type/field first, @optional where FLS applies, check
result.errors. Aggregations can be compiled with npx graphiti sf-gql-aggregate (pass
groupBy + aggregations); object metadata / picklists / related lists are hand-authored —
templates: references/graphql-hand-authoring.md.
Two related capabilities (the current-user record and layout delivery) need
confirmation against a current org schema before this skill documents a query shape —
tracked as a follow-up, not yet covered here.
Freshness & caching
Caching is ON by default on WebApp. Every sdk.graphql!.query() is cached with a
300-second max-age TTL — no opt-in flag, no factory, no import subpath. Do not
build your own cache (no React Query, SWR, localStorage, or hand-rolled Map). The
cache is shared across SDK instances by baseUrl: the same query+variables from a
different createDataSDK() targeting the same host is a cache hit. Only non-empty,
error-free data is cached. mutate() is never cached.
There are two distinct freshness tools — keep them separate:
- Per-call
cacheControl — a one-shot policy override on the query options bag
("no-cache" / "only-if-cached" / { type: "max-age", maxAge: <seconds> }). The type and
exact per-value behavior live in references/sdk-api.md.
Take cacheControl as an optional param on the read function and expose each distinct policy as
a thin named export in the same data-layer file — a "call site" is a named export, not a new
React component. For getAccounts(first, after?, cacheControl?): export const refreshAccounts = () => getAccounts(20, undefined, "no-cache") (and likewise offlineAccounts → "only-if-cached",
shortLivedAccounts → { type: "max-age", maxAge: 10 }). Keep the policy in the data layer.
- Reactive
subscribe / refresh — a stateful handle on a live QueryResult:
result.subscribe(cb) fires on every later snapshot, result.refresh() re-fetches bypassing
the cache and pushes to subscribers. Shape in references/sdk-api.md;
subscription lifecycle (always unsubscribe on teardown) in references/caching.md.
| Want | Reach for |
|---|
| Freshness within ~5 min is fine | nothing (default cache) |
| This one read must bypass the cache (refresh button) | cacheControl: "no-cache" |
| Read only cached data, tolerate misses (offline-first) | cacheControl: "only-if-cached" — a miss is expected, not an error: it surfaces a DataNotFoundError on result.errors (no network, no throw). Check result.errors, render empty state, do not throw and do not fall back to the network — that defeats offline-first. |
| Tighter/looser TTL for this query | cacheControl: { type: "max-age", maxAge: 60 } (maxAge is in seconds) |
| Mounted component reflects updates over time | result.subscribe(cb) |
| Re-fetch now + notify all subscribers (e.g. after a mutation) | result.refresh() |
cacheControl is fire-and-forget at call time; subscribe/refresh is a live handle.
Different mechanisms, different jobs — don't conflate "refresh" with "no-cache". Full
behavior, the reactive-subscription lifecycle, and uncached-surface caveats: references/caching.md.
Working on existing code (migration)
Only enter this path if the existing code actually uses the old API — i.e. it imports
@salesforce/sdk-data or calls the callable sdk.graphql(query, vars) form. For any new
read/write, ignore migration entirely and use the Read workflow /
Write workflow — those already show the only correct API.
When you do have old code to convert, see references/migration.md for the
before→after diff (imports, query/mutate calls, optional-chaining → non-null assertion, codegen
type placement) and a checklist. The target API is exactly what the Read/Write workflows above
prescribe — migrating is just swapping the old form for that.
Platform guardrails — never regress these
These are Salesforce GraphQL platform behaviors, independent of the SDK. Violations cause
silent runtime failures. (Details + templates: references/graphql-hand-authoring.md.)
- HTTP 200 ≠ success — always parse
result.errors; the Promise resolves even on failure.
- Schema is the only source of truth — verify, never invent. Verify every
entity/field/type via graphiti
sf-gql-discover (preferred) or
bash <skill-dir>/scripts/graphql-search.sh <Entity> before use. Case-sensitive;
__c/__e; _Record entity suffix (v60+). When graphiti is primed, a
"not found"/empty/Cannot query field answer (including from
graphql-codegen/@graphql-eslint, even when the message points at schema.graphql)
is a fact about the org — wrong name or undeployed/inaccessible metadata, not a tool
failure: fix the operation, or deploy the metadata (the platform-metadata-deploy skill)
- assign perms + refresh (
sf-gql-connect --forceRefresh / npm run graphql:schema). Do
not fall back to the script, hand-author around it, or guess a name — a guessed entity or
field silently fails the whole query at runtime; if lookups aren't converging, ask the user
rather than keep spiraling. schema.graphql and the codegen output
(src/api/graphql-operations-types.ts) are read-only generated mirrors — never open or edit
them (honor any # DO NOT EDIT marker). Hand-adding a missing type satisfies codegen/lint
but grants no org access; it just hides the failure until runtime. Fall back to the script
only when the CLI can't run at all (no dep / SCHEMA_PRIME_FAILED).
@optional on every FLS-gated field at each nesting level — scalar leaf fields plus each
parent/child relationship and the fields inside it (FLS fails the whole query otherwise, v65+).
Do NOT decorate Id, the connection plumbing (edges, node, the connection field), or
pageInfo — those are not FLS-gated and the graphiti output leaves them bare. Consume with
?./??. Placement rules: references/graphql-hand-authoring.md.- Mutations wrap under
uiapi(input: { allOrNone: ... }); set allOrNone explicitly;
output excludes child/navigated-reference fields; the output field is literally named
(unrelated to the entity suffix in rule 2) — Delete → only. GA v66+.
One SDK convention lives in the workflows, not this list (it's not a platform behavior):
always run npm run graphql:codegen and use the generated types after writing an operation
(Read workflow step 3). Also in the Pre-flight checklist.
graphiti applies most of these for you. When you compile a query with sf-gql-* against an
object that's in the primed schema, rules 3 (@optional), 4 (mutation Record output
envelope and entity-keyed input — not allOrNone, which you still add yourself),
5 (first:/pageInfo), and 7 (value/displayValue wrappers) come out already satisfied —
which is exactly why you paste the query verbatim rather than re-deriving it. Rules 1
(check result.errors), 6 (governor limits), 8 (compound fields), and 9 (supported APIs) are
still on you. And the automation only fires when the object is primed: a non-empty warnings
array means it isn't, and the emitted query is degraded (bare fields, no guardrails) —
see references/graphiti-cli.md.
Commands & layout
<skill-dir>/ ← wherever this skill is installed
└── scripts/graphql-search.sh ← schema lookup (ships with the skill)
<project-root>/ ← SFDX project root; run the script from here
├── schema.graphql ← generated mirror; grep target (never open or edit; script reads ./schema.graphql)
└── force-app/main/default/uiBundles/<app>/ ← UI bundle dir
├── package.json ← npm scripts
└── src/api/ ← queries, generated types, SDK calls
| Command | Run from | Purpose |
|---|
npx graphiti sf-gql-discover '{…}' | UI bundle dir | Discover objects/fields against the live org (preferred grounding) |
npx graphiti sf-gql-<list|detail|aggregate|create|update|delete|raw> '{…}' | UI bundle dir | Compile a guardrail-applied query/mutation (references/graphiti-cli.md) |
npx graphiti sf-gql-connect '{"org":"<alias>","forceRefresh":true}' | UI bundle dir | Refresh graphiti's schema cache after a deploy |
bash <skill-dir>/scripts/graphql-search.sh <Entity> | project root (or pass --schema <path>; no tree walk-up) | Schema lookup fallback (grep over local schema.graphql) |
npm run graphql:schema | UI bundle dir | Fetch/refresh schema.graphql (for the fallback script) |
npm run graphql:codegen | UI bundle dir | Generate operation types |
npx eslint <file> | UI bundle dir | Lint (catches gql schema violations) |
Pre-flight checklist
