motherduck-create-flight

创建和管理 MotherDuck Flights

唯一事实来源

• **不可妥协的顺序：**当 MotherDuck MCP 可用时，必须先调用 get_flight_guide，再调用 create_flight、update_flight 或 edit_flight_source。该指南定义了当前的编写约定、运行时限制和工具语义。
• get_flight_guide 还会展示保留的 flights 指南主题中的约定。适用于所请求工作负载时，请遵循这些约定。
• 优先采用最新的 MotherDuck Flights 文档，而非凭记忆作答。请核实生命周期状态、运行时限制和工具语义，不要将其作为固定的提示词声明保留下来。
• 不使用 MCP 时，同样的操作可通过 SQL 函数（MD_CREATE_FLIGHT、MD_RUN_FLIGHT、MD_LIST_FLIGHTS() 等）在 MotherDuck 连接上于服务端执行。这两种方式的参数名称略有不同；请参阅 references/FLIGHTS_GUIDE.md 中的名称对照表。

默认原则

• 一个 Flight = 一个包含 def main(): ... 和 if __name__ == "__main__": main() 的单文件 Python 脚本。不接受 CLI 参数——所有可调项都通过 config 中的环境变量（非机密）或 TYPE flights 密钥（敏感信息）提供。
• 使用 duckdb.connect("md:") 连接；运行时会自动注入 MOTHERDUCK_TOKEN。切勿在源代码、配置或 requirements 中硬编码令牌。
• 始终在 requirements_txt 中锁定依赖版本。编写新的 Flight 前，请先从 https://motherduck.com/docs/duckdb-versions.json 确定 MotherDuck 支持的最高 DuckDB 版本；只有在复现这些示例时，才使用随附模板中经过测试的固定版本。未锁定版本或不受支持的 duckdb 版本可能导致连接失败。
• 每个密钥参数都会注入到稳定的命名空间 <secret_name>_<PARAM> 键下，并在安全时提供一个不带命名空间的 <PARAM> 便捷别名。在已部署的 Flight 代码中优先使用命名空间键；不带命名空间的别名可能冲突、被配置覆盖，且对保留的运行时键不会提供。
• 批量加载，切勿逐行加载：先暂存到 /tmp/，再使用 read_csv_auto/read_json_auto/read_parquet，或使用单条 CTAS / INSERT ... SELECT。不要对 MotherDuck 使用 executemany()。
• 确保每次运行都幂等：完整刷新时使用 CREATE OR REPLACE TABLE，或使用分区 DELETE + INSERT，或使用带主键的 dlt write_disposition="merge"。使用 CREATE DATABASE IF NOT EXISTS / CREATE SCHEMA IF NOT EXISTS 引导初始化，确保首次运行能在全新账户上成功。
• 在将配置提供的标识符（数据库、架构、表名）插入 DDL 前，使用 [A-Za-z_][A-Za-z0-9_]* 验证；所有数据值都使用 ? 参数绑定。
• 创建 Flight 时先不设置计划，触发一次按需运行并查看日志，然后再添加 schedule_cron（5 字段 cron，UTC）。
• 如果工作负载需要明确的上限，请设置并验证 max_runtime_sec；读取当前计划限制时，使用 get_flight_guide，而非硬编码。
• 在生产环境中，通过 access_token_name 使用服务账号令牌，并将其数据库权限限制在工作负载所需的最小范围内。
• 将 Flight 视为编排和轻量处理工具，而非在 Python 内存中处理大型表的场所。将繁重计算交给 SQL，并在确定磁盘或内存密集型工作的规模前，使用 get_flight_guide 确认运行时容量。
• dbt、dlt 和多步骤 Python 工作流使用默认规格（F16）。对于主要调用 API 或发送 SQL 的轻量任务，选择 F4，因为针对 md: 的 SQL 会在 Duckling 上运行，而非 Flight 上。只有在降低峰值内存后运行仍因内存不足而失败时，才升级到 F32（Business 和 Enterprise）。通过 create_flight/update_flight 中的 instance_type，或 MD_CREATE_FLIGHT/MD_UPDATE_FLIGHT 设置规格。
• 如果 Flight 只访问一个或少数几个数据库，请使用 duckdb.connect("md:<db>?attach_mode=single") 连接，并显式附加其他数据库；附加整个工作区会拖慢每次运行的启动速度。
• 如果要在 Flight 中执行分类、提取或嵌入，请通过现有连接在 SQL 中调用 prompt_jev()、prompt() 或 embedding()，而非添加 LLM SDK。
• 若要让队友、某个角色或 Dive 的查看者启动 Flight，所有者需授予 run 权限（通过 MCP 使用 grant_access，或执行 GRANT RUN ON FLIGHT '<flight_id>' TO ROLE <role>）。建议授权对象，并且只在用户确认后授予；请求共享 Dive 不代表已确认。优先选择角色而非 ORGANIZATION，后者包含服务账号。每次运行都会使用所有者的令牌和密钥，因此必须将调用者可传入的每个配置值都视为不可信输入并进行验证。
• 编写多步骤 Flight 前，先决定是否需要让运行过程可供查看：Flight Explainer 的监测功能（# @flight Mermaid 步骤图及 @flight-run <step> <status> 日志行）只涵盖添加该功能后启动的运行。添加前请调用 get_flight_viz_guide，并使用 view_flight_run 将运行显示为步骤图，而不是粘贴原始日志。
• 请用户在 MotherDuck UI（Settings, Secrets）中创建 Flight 密钥，避免密钥值经过聊天传递；使用 SELECT name FROM duckdb_secrets() WHERE type = 'flights' 检查密钥是否存在。

工作流

1. 对任务进行分类：数据摄取、转换/刷新、导出或告警，或管理自动化。如果任务是交互式分析或一次性查询，请改用 motherduck-query——无需使用 Flight。
2. 调用 get_flight_guide（MCP），并使用 motherduck-explore 确认 Flight 写入哪个数据库。
3. 如果适用，请复用 references/FLIGHT_EXAMPLES.md 中匹配的模板；否则，编写精简脚本，确保遵守运行时、密钥和幂等性约定。
4. 先创建所需的 TYPE flights 密钥，再调用 create_flight，并提供 name、source_code、固定版本的 requirements_txt、config 和密钥名称——暂不设置 schedule_cron。
5. 调用 run_flight，并在可用时轮询 get_flight_run（否则使用 list_flight_runs 作为备用方案），直到运行结束，然后读取 get_flight_logs。使用 edit_flight_source（精细修改）或 update_flight（完整替换字段）进行迭代；每次内容变更都会创建新版本。
6. 如果用户要求设置计划任务，则仅在运行成功后使用 update_flight(schedule_cron = ...) 设置，并说明 cron 使用 UTC。仅在用户要求时，才使用 schedule_cron = "" 清除计划任务；无关修改应保留现有计划任务。
7. 首次成功运行创建或刷新持久化表后，请在 Guide 中记录该表，主题设为 data-sources（参见 motherduck-manage-guides）。
8. 如果其他用户或 Dive 必须触发 Flight，请建议授予 run 权限；仅在用户确认后才应用，并通过 SHOW GRANTS ON FLIGHT '<flight_id>' 验证。

对于解答、审查或规划请求，不要创建或安排 Flight。对于创建或更新请求，请完成请求范围内的部署和按需验证；只有请求中包含设置计划任务的要求时，才允许附加重复计划任务。

参考资料

只阅读当前任务所需的参考章节。

• 阅读 references/FLIGHTS_GUIDE.md，了解完整的概念和操作参考：组成结构、运行时环境和规格、配置与密钥、计划任务、版本控制、运行生命周期、运行权限、Flight Explainer 插桩、完整的 MCP 工具参考、MCP 与 SQL 的命名规则、按数据量选择加载策略，以及故障排查。
• 阅读 references/FLIGHT_EXAMPLES.md，查看三个完整的最佳实践 Flight 模板（dlt 数据摄取、Postgres 数据摄取、按计划刷新 S3 分区），以及对应的 requirements.txt、密钥设置和部署调用。

相关技能

仅当缺少所需功能时才加载相关技能；复用已有上下文。

• motherduck-load-data：选择 Flight 将运行的数据摄取 SQL（CTAS、INSERT ... SELECT、云存储密钥）
• motherduck-query：部署前验证 Flight 中的 DuckDB SQL
• motherduck-explore：确认目标数据库、架构和表是否存在
• motherduck-build-data-pipeline：当工作涉及完整的原始/暂存/分析型数据管道设计，且 Flight 仅用作其调度器时使用
• motherduck-create-dive：当 Dive 按钮或表单需要启动 Flight（写回）时使用
• motherduck-cli：当 Agent 有 shell 且应将 Flight 源代码保存在本地文件中时使用
• motherduck-manage-guides：管理可复用的个人或组织 Flight 约定