Before you start
Workflow
- 1Choose a delegated result contract only when ordinary permitted source queries do not fit. Declare its input/output schemas and exact source bindings.
- 2The handler examples below replace the handler in an action definition; they are not client scripts. Database reads require the declared published schema and readTables; warehouse reads require the selected source binding.
- 3Publish and grant invocation access after review. Use a new request ID for each new refresh and the same ID and input for retries.
Use delegated access and trusted caller identity
Run, Edit draft, Publish, and Change access are separate permissions. Granting draft or publication access does not grant execution; source delegation remains separately authorized. Existing level-based grants keep their current and historical invocation thresholds.
Permute authenticates callers and checks the action’s required invocation permission. Hosted app calls also require app access, an app invocation grant, and the action revision pinned in the served release. Editors need Read on referenced resources to save a draft; publishers need source Admin to approve the delegated capabilities.
Execution uses the action’s approved delegated capabilities; callers do not need direct access to the underlying sources. A bound connector uses the connected account’s access even when the caller has no connector access. Permute enforces declared execution capabilities and validates input/output schemas; the handler defines the operation exposed to callers.
The handler receives trusted caller: { id, type }, where type is user, apiKey, or system (a scheduled or webhook trigger run, whose id is the trigger ID), alongside input, db, warehouse, named connectors, optional platform, llm({ prompt, system?, outputSchema? }), and reject(). llm() returns a string, or with outputSchema the parsed JSON value, which must match the schema or the call fails. An answer over the output limit fails instead of being cut short; failed calls throw an Error whose message is safe to show and which carries no code. An action can use that identity and server-side business data to check or deny a request when its rules warrant it (such as an ownership rule or allowed state transition). Apply those checks before the affected reads or writes; use reject(code, message, details?) to deny the request. These checks supplement the platform checks. Permute does not require callers to hold the action’s underlying source permissions. Browser-supplied actor IDs or roles are not proof of identity or authority. Caller identity does not provide membership roles or a general permission lookup API.
Read managed database rows for the current caller
Business Actions support filtered server-side reads through db.read({ sourceId, table, where, limit }). Declare the database source ID, its published schema revisionId, and the allowed readTables in the action definition; use writeTables: [] for a read-only action. Publish the reviewed definition and typed input/output contracts before granting invocation access. Callers need action invocation permission, not Read on the database.
The handler below assumes a published deals table with text columns id, owner_id, and name, bound in readTables. Replace the example source ID with that declared database ID. It returns only the signed-in user’s deals and approved fields; it accepts no caller-supplied owner ID. API-key callers are rejected because their trusted identity is the key, not a user. A team or manager rule can read a separately declared server-side roster before selecting the permitted records.
where applies equality filters using string, boolean, or null values. Each read defaults to 100 rows and permits at most 1,000 rows and 1 MB; exceeding the bound fails instead of silently truncating. Design a bounded result contract. Ordinary queries against sources the viewer may read directly do not need an action.
Read-only actions still require an invocation requestId. Identical retries return the saved receipt, so use a new requestId for a new refresh. Hosted apps need an action grant and an exact action revision pin; the built-in assistant requires confirmation before invoking even a read-only action.
exports.handler = async ({ caller, db, reject }) => {
if (caller.type !== 'user') reject('permission_denied', 'Sign in to read your deals.');
const rows = await db.read({
sourceId: 'dbas_aaaaaaaaaaaaaaaaaaaaaaaa',
table: 'deals',
where: { owner_id: caller.id },
limit: 100,
});
return { deals: rows.map(({ id, name }) => ({ id, name })) };
};Design an approved delegated read contract
| Avoid this loading pattern | Use this instead | Why |
|---|---|---|
| Read all history for a default six-month view | Bound the initial date range; load older history on demand | History volume should not determine default-view latency. |
| Await one request per record in a serial loop | Use supported batch reads or bounded independent requests | Network round trips accumulate; unlimited concurrency can hit provider limits. |
| Wait for all panels and details before rendering | Resolve and render independent panels separately | A slow optional read should not block useful results. |
| Re-discover every file and schema on each visit | Use verified source/table configuration and deliberate schema refresh | Separate setup work from routine data reads. |
| Refetch the same data on every tab change | Deduplicate requests and cache by revision, identity, and inputs with an explicit refresh policy | Avoid redundant calls without presenting stale data as fresh. |
| Increase a timeout when a screen feels frozen | Measure the request chain and expose local loading/retry states | A longer wait does not correct an inefficient query or an unresponsive UI. |
Business Actions can expose read-only data; the create-customer example above is a write example, not a required starting point. For read actions, declare read invocation permission and only the required source access, omit database write tables, and make no mutating connector or SDK calls. Invocation permission alone does not make a handler read-only: inspect the handler and its delegated capabilities.
Define bounded inputs such as a date range, selected client, or page cursor, and a typed output containing rows or aggregates plus freshness and completeness metadata. Prefer compact overview results and separate detail reads to returning every source field for every screen. Validate ranges and cursors in the action; never interpolate unvalidated browser input into provider queries. Keep provider credentials and matching logic behind the action boundary.
Follow the provider’s pagination contract until complete, with repeated-cursor detection and an explicit safety bound. If a bound is reached, fail or mark the result incomplete; never display a partial total as complete. A warehouse.read limit is not a promise that the table fits in one read. Discover the schema and use supported filters or a prepared operation output when the required data exceeds the read capability.
Separate stable schema/configuration discovery from routine data reads. For many files or repeated expensive transformations, consider a prepared Data Flow output that the action reads, with freshness shown to users. Do not introduce a scheduled workflow merely to hide an inefficient interactive query; first measure and bound the query.
requestId identifies an invocation, not a cache key for a permanent live query. A deliberate fresh read or different page needs a new requestId; retry an uncertain invocation with its original ID and identical input. Give each distinct connector or SDK call within an invocation a stable, distinct step ID (platform.withStep for SDK calls). Aborting the browser wait does not prove server execution stopped and must never be interpreted as a failed write.
Read warehouse sources and operation outputs
Bind queryable warehouse sources with { sourceId }: data_ for processed files, conn_ for synced connectors, oper_ for Data Flow outputs, or enty_ for completed entity outputs. Operations need a completed output and entity outputs must be outside draft lifecycle state. Google Drive imports (like uploads) become individual data_ datasets; bind those file IDs. Saving requires source Read without delegating access. Publishing delegates reads of the whole selected source and requires source Admin.
warehouse.read({ sourceId }) returns text blocks with their IDs, order, and page numbers, plus table IDs, display names, and column schemas. Pass a table block ID or an unambiguous display name to read rows. where accepts equality filters with string, boolean, or null values. Unknown or ambiguous tables and unknown columns are rejected.
Each read permits at most 1,000 rows or text blocks and 1 MB of data; the default limit is 100. Oversized reads fail, so narrow table filters or raise limit within that bound. Warehouse reads use current available output, including retained output after a failed refresh; publishing an action does not freeze source content. Schemas and subscriptions have no query capability. Live SQL and external writes use supported named connector calls.
// Add { sourceId: fileId } to the action definition's sources, then publish.
// Handler source:
exports.handler = async ({ input, warehouse }) => {
const document = await warehouse.read({ sourceId: input.fileId });
if (!document.tables.length) return { blocks: document.blocks, rows: [] };
const rows = await warehouse.read({ sourceId: input.fileId, table: document.tables[0].id, limit: 1000 });
return { blocks: document.blocks, rows };
};