useRunFlight hook
The useRunFlight hook runs a Flight from a Dive, for example from a button that refreshes data or a form that writes it back. Nothing runs until you call run, and each call starts a new run. Follow the run with useFlightRun.
See Build Dive apps for the end-to-end pattern.
Import
import { useRunFlight } from "@motherduck/react-sql-query";
Syntax
const { run, runAsync, status, isPending, data, error, reset } = useRunFlight(flightId, options);
Parameters
flightId
| Type | Required |
|---|---|
string | Yes |
The Flight's ID, a UUID. Write it into the Dive as a constant. Don't look it up by name inside the Dive: MD_LIST_FLIGHTS() lists only the viewer's own Flights (Admins see the organization's).
options
| Option | Type | Description |
|---|---|---|
onSuccess | (started, config) => void | Called when a run starts, with { runId, runNumber }. |
onError | (error, config) => void | Called when a run can't start. |
onSettled | (started, error, config) => void | Called after either outcome. |
Each callback also receives, as its last argument, the config passed to that call, so you can tell which row or form a result belongs to.
The callbacks fire for every call. When calls overlap, the latest one sets the hook's state.
Return value
| Property | Type | Description |
|---|---|---|
run | (config?) => void | Starts a run. Errors go to error. |
runAsync | (config?) => Promise<{ runId, runNumber }> | Starts a run and resolves when it has started. Rejects on error. |
mutate, mutateAsync | The same functions as run and runAsync, under TanStack Query names. | |
status | 'idle' | 'pending' | 'success' | 'error' | The state of the latest call. |
isIdle, isPending, isSuccess, isError | boolean | Shorthands for status. |
data | { runId, runNumber } | undefined | The run the latest call started. Pass data?.runNumber to useFlightRun. |
error | Error | null | Why the latest call couldn't start a run. |
reset | () => void | Returns the hook to idle. |
run and runAsync keep the same identity across renders.
config
An object of string keys and string values that overrides the Flight's config for this run only, for example run({ REGION: "eu" }). You can only pass keys the Flight already defines, and every value must be a string: convert numbers, dates, and booleans first.
Behavior
- Success means started.
runsucceeds when the run is accepted, not when it finishes. UseuseFlightRunto wait for the result. - Run only on a user action. Don't call
runwhile rendering, inuseEffect, or on a timer. - The Flight runs as its owner, with the owner's token and secrets. The viewer must own the Flight or have a
rungrant; otherwiserunreturns an error. - Errors stay in the Dive. Run errors don't open the query error overlay, so show
erroryourself. - Not available everywhere. In an embedded Dive, and in the MCP Dive viewer when the AI tool blocks its direct connection,
runfails withThis Dive can't run Flights. - Input checks. Before anything is sent, the hook checks its input:
useRunFlight: the Flight id must be a UUID, got <value>.anduseRunFlight: config value for '<key>' must be a string; convert it before passing it.Callingrunbefore the Dive connects fails withCan't run a Flight before the Dive is connected to MotherDuck. - Restricted viewers. Viewers with no roles, and Dives that connect with a read scaling token, get
Flights are not available for restricted members or when using a read-scaling token, even on Flights they own.
Example
import { useRunFlight } from "@motherduck/react-sql-query";
const REFRESH_CRM_FLIGHT = "7b1e2c3d-0000-4000-8000-000000000001";
export default function Dive() {
const refresh = useRunFlight(REFRESH_CRM_FLIGHT);
return (
<div className="p-6">
<button
className="rounded border px-3 py-1"
disabled={refresh.isPending}
onClick={() => refresh.run({ REGION: "eu" })}
>
{refresh.isPending ? "Starting…" : "Refresh CRM data"}
</button>
{refresh.data && <p>Started run #{refresh.data.runNumber}</p>}
{refresh.error && <p>Couldn't start the refresh: {refresh.error.message}</p>}
</div>
);
}
Related
useFlightRun— follow the run until it finishes.MD_RUN_FLIGHT— the SQL function the hook calls.