Run Behavior & Triggering

Every data source declares a Run Behavior — Automatic or Manual — and that single setting decides when it executes. Automatic means the platform runs it for you: on page load and again whenever an input it depends on changes. Manual means it never runs until something explicitly triggers it. Picking the right behavior is the difference between a page that stays in sync by itself and a query that fires exactly once, when you say so.

Note: Open the data source's Input tab in the inspector. The Run Behaviour control shows Automatic and Manual. Read operations default to Automatic; write operations (mutations) default to Manual.

Automatic: Runs Itself, Re-runs on Change

An automatic data source is reactive. It runs without any action wiring, and whenever a value its configuration is bound to changes — a page input, another data source's result, a block's state — it re-runs with the fresh values and all bound blocks update.

When an Automatic Data Source Runs

Warning: An automatic data source re-runs when its bound inputs change. If the data changes on the backend while the page's inputs stay the same, the data source won't notice. Use polling or an explicit refresh for server-side changes.

Manual: Runs Only When Told To

A manual data source does nothing on its own. It runs when something fires it — most commonly the Trigger Data Source action on a button click or another event. Each trigger is a fresh, one-shot run.

Two Key Consequences of Manual Mode

Tip: Use manual run behavior for anything with side effects or cost — a save, an export, an expensive report — where "runs whenever an input wiggles" would be wrong.

Advanced Options

These settings live on the data source's Advanced tab under Timing and Trigger Conditions.

Page Load Order & Dependency Sequencing

When a page opens, every data source with Run query on page load enabled is queued. Runs are dependency-ordered, not simultaneous:

• If data source B's inputs use data source A's result, B waits until A has finished.

• A data source with no dependencies runs straight away.

• You define this ordering by binding one data source's output into another's inputs — no manual sequencing required.

Example — Dependency chain

// Data source A: fetch the current user profile user_profile → runs first (no dependencies) // Data source B: fetch orders for that user // Its input binds to A's result: orders_query input: customerId: {{ user_profile.data.id }} // Result: B automatically waits for A to finish before running. // No manual sequencing needed.

On-Success and On-Failure Events

After a run finishes, the data source fires its On Success or On Failure event. These are the reliable completion signals for chaining follow-up actions.

Warning: Putting a "show success toast" action after a Trigger Data Source action in a button's onClick does not wait for the fetch to complete. The fetch is async — the next action in the chain runs before the response arrives. Put the toast in the data source's own On Success event instead.

Legacy Mode

Data sources created before run behavior existed have no mode set. The platform treats them like automatic sources — they run on page load and participate in dependency ordering — but triggering them from an action behaves slightly differently: a legacy source only re-fetches if it has already loaded once.

Tip: Set an explicit run behavior (Automatic or Manual) on any old data source to move it onto the current rules and remove the ambiguity.

Disable Conditions — Gating a Run

The Disable query condition holds off a fetch until inputs are ready — for example, blocking a query until a filter has been chosen. While the condition evaluates truthy, an automatic source is treated as finished without fetching; triggers and page load are also suppressed.

Example — Only run when a filter is selected

// Disable query condition: {{ !status_filter.value }} // Disabled message: "Please select a status to load orders." // Result: the data source does not run until the user // picks a value in status_filter.

Gotchas

Frequently Asked Questions

When should I use Automatic vs Manual run behavior?

Use Automatic for read operations ��� fetching lists, displaying records, loading reference data. The source re-fetches whenever its inputs change, keeping the UI in sync without extra wiring. Use Manual for write operations and expensive queries — saves, deletes, exports, or any fetch that should only run when the user deliberately triggers it. The rule of thumb: if running it at the wrong moment would cause harm (double-save, wasted compute), use Manual.

My button triggers a data source but the next action still sees old data. Why?

Fetches are asynchronous — the trigger action starts the fetch but the very next chained action runs before the response arrives. The reliable completion signal is the data source's own On Success event. Move the action that needs fresh data into that event handler instead of chaining it directly after the trigger on the button.

Can I make a manual data source run on page load once?

Yes — enable Run query on page load in the Advanced tab even with Manual run behavior. The source gets a single seed run when the page opens, then runs only when explicitly triggered afterward. It still never re-runs automatically when bound inputs change.

How do I sequence two data sources so B runs only after A finishes?

Bind one of B's inputs to a value from A's result — for example, {{ customer_query.data.id }} as the input to an orders query. The platform detects this dependency and automatically runs A before B. No manual sequencing or event wiring is needed; the binding itself is the ordering.

Why is my data source not running even though the page loaded?

Check two things: (1) Is Run query on page load enabled in the Advanced tab? By default it is off — a data source must be referenced by a mounted block, or have page-load explicitly enabled, to run at startup. (2) Is there a Disable query condition that evaluates truthy? A disabled source silently skips every run without any error message.