MD_CREATE_FLIGHT

Preview

This feature is in preview and is subject to change.

Creates a new Flight and returns its summary. The initial version is captured from source_code, requirements_txt, config, access_token_name, and flight_secret_names.

You are responsible for the code you run and the packages it installs. Flights does not scan customer code or dependencies. Avoid untrusted packages, pin dependency versions, and treat dependency installs as a supply-chain risk.

Syntax

SELECT * FROM MD_CREATE_FLIGHT(
    name := 'my_flight',
    source_code := '<python_source>',
    schedule_cron := '0 * * * *',
    requirements_txt := 'duckdb==1.5.3',
    config := MAP {'KEY': 'value'},
    access_token_name := '<token_name>',
    flight_secret_names := ['secret_name']
);

Parameters

Parameter	Type	Required	Description
name	VARCHAR	Yes	Human-readable Flight name. Must be non-empty.
access_token_name	VARCHAR	No	Label of a MotherDuck access token to run the Flight as. The token value is injected into the Flight as MOTHERDUCK_TOKEN. Omit it to use the default MotherDuck Flights access token for your user. List labels with SELECT * FROM md_access_tokens();.
source_code	VARCHAR	Yes	Python source for the Flight. A single-file program, executed as a plain script; end it with if __name__ == "__main__": main() to invoke your entrypoint.
schedule_cron	VARCHAR	No	5-field cron expression in UTC. Omit for an on-demand-only Flight.
requirements_txt	VARCHAR	No	Contents of a requirements.txt, one pinned package per line.
config	MAP(VARCHAR, VARCHAR)	No	Non-secret key/value pairs surfaced to the Flight as environment variables.
flight_secret_names	LIST(VARCHAR)	No	List of names of Flight secrets (TYPE FLIGHTS). Each key in a secret's PARAMS map is surfaced to the Flight as an environment variable.

note

source_code is capped at 200 KB and requirements_txt at 20 KB. Load large reference data from object storage at run time instead of embedding it in the source.

Return columns

Column	Type	Description
flight_id	UUID	Unique identifier of the created Flight.
flight_name	VARCHAR	The Flight name.
schedule_cron	VARCHAR	The cron expression, or NULL for on-demand.
status	VARCHAR	Schedule status (for example, JOB_STATUS_ACTIVE).
current_version	INTEGER	Always 1 for a newly created Flight.
created_at	TIMESTAMP WITH TIME ZONE	Creation timestamp.
updated_at	TIMESTAMP WITH TIME ZONE	Last update timestamp.

Examples

Minimal Flight, no schedule:

SELECT flight_id
FROM MD_CREATE_FLIGHT(
    name := 'heartbeat',
    source_code := 'def main(): print("hello")

if __name__ == "__main__":
    main()'
);

Scheduled Flight with config, running as a specific access token:

SELECT flight_id, current_version
FROM MD_CREATE_FLIGHT(
    name := 'hourly_metrics',
    access_token_name := 'analytics_token',
    source_code := $$
import duckdb

def main():
    con = duckdb.connect("md:")
    con.execute("INSERT INTO analytics.hourly_counts SELECT now(), COUNT(*) FROM events")

if __name__ == "__main__":
    main()
$$,
    requirements_txt := 'duckdb==1.5.3',
    schedule_cron := '0 * * * *',
    config := MAP {'REGION': 'eu-central-1'}
);

Related

• MD_UPDATE_FLIGHT — Modify a Flight's content or metadata.
• MD_RUN_FLIGHT — Trigger an on-demand run.
• MD_DELETE_FLIGHT — Delete a Flight.
• create_flight MCP tool — AI-agent equivalent.