MD_RUN_FLIGHT

Preview

This feature is in preview and is subject to change.

Triggers a new run of a Flight using the Flight's current version. The run is asynchronous: MD_RUN_FLIGHT returns immediately with a RUN_STATUS_RUNNING (or RUN_STATUS_PENDING) row. Use MD_LIST_FLIGHT_RUNS to poll for completion and MD_GET_FLIGHT_LOGS to read the output.

Syntax

SELECT * FROM MD_RUN_FLIGHT(flight_id := '<flight_id>');

MD_RUN_FLIGHT is a table function; you can also call it with CALL when you don't need the result row:

CALL MD_RUN_FLIGHT(flight_id := '<flight_id>');

Parameters

Parameter	Type	Required	Description
flight_id	UUID	Yes	Identifier of the Flight to run.
config	MAP(VARCHAR, VARCHAR)	No	Per-run config overrides. Only keys already defined on the Flight can be set; keys you omit keep their stored values. The override applies to this run only and leaves the stored config and version untouched.

Return columns

Column	Type	Description
run_id	UUID	Unique identifier of the new run.
flight_id	UUID	The Flight identifier.
flight_name	VARCHAR	The Flight name.
flight_version	INTEGER	The version this run locked to.
config	MAP(VARCHAR, VARCHAR)	The effective config for this run: the stored config with any per-run overrides applied.
run_number	INTEGER	Sequential run number assigned to this run.
is_scheduled	BOOLEAN	false for on-demand runs.
status	VARCHAR	Initial run status (RUN_STATUS_PENDING or RUN_STATUS_RUNNING).
created_at	TIMESTAMP WITH TIME ZONE	When the run was created.

The row is the same run record returned by MD_LIST_FLIGHT_RUNS; the timing columns (started_at, ended_at, cancelled_at) and exit_code are still NULL when MD_RUN_FLIGHT returns.

Behavior

• The new run locks to the Flight's current version. Subsequent updates to the Flight do not affect this run.
• The run number is assigned sequentially per Flight and visible through MD_LIST_FLIGHT_RUNS.
• Multiple concurrent runs of the same Flight are allowed; each gets its own run number.
• A config argument overrides stored config values for this run only. You can override only keys the Flight already defines; it can't add new keys. The config a run used is recorded in the config column of MD_LIST_FLIGHT_RUNS.

Examples

Trigger a run and capture the row:

SELECT flight_version, status
FROM MD_RUN_FLIGHT(flight_id := '80000000-0000-0000-0000-000000000001');

Trigger and then poll until the run finishes:

-- Kick off the run
CALL MD_RUN_FLIGHT(flight_id := '<flight_id>');

-- Poll the latest run's status
SELECT run_number, status
FROM MD_LIST_FLIGHT_RUNS(flight_id := '<flight_id>')
ORDER BY run_number DESC
LIMIT 1;

Override a config value for a single run:

CALL MD_RUN_FLIGHT(
    flight_id := '<flight_id>',
    config := MAP {'REGION': 'eu-central-1'}
);

Related

• MD_LIST_FLIGHT_RUNS — List runs for a Flight.
• MD_GET_FLIGHT_LOGS — Read combined stdout/stderr for a run.
• MD_CANCEL_FLIGHT_RUN — Cancel an in-progress run.
• run_flight MCP tool — AI-agent equivalent.