motherduck-create-flight

MotherDuck フライトの作成と管理

信頼できる情報源

• 順序は厳守してください： MotherDuck MCP を利用できる場合は、create_flight、update_flight、edit_flight_source の前に get_flight_guide を呼び出してください。ガイドには、現在の作成契約、実行時の制限、ツールのセマンティクスが定義されています。
• get_flight_guide には、予約済みの flights ガイドトピックの規約も表示されます。依頼されたワークロードに合う場合は、それらの規約を適用してください。
• 記憶よりも、MotherDuck Flights の最新ドキュメントを優先してください。ライフサイクルのステータス、実行時の制限、ツールのセマンティクスを確認し、永続的なプロンプト上の主張として保持しないでください。
• MCP を利用できない場合も、同じ操作を SQL 関数（MD_CREATE_FLIGHT、MD_RUN_FLIGHT、MD_LIST_FLIGHTS()、...）として利用でき、MotherDuck 接続上でサーバー側で実行されます。パラメーター名は 2 つのインターフェース間で若干異なります。命名表については references/FLIGHTS_GUIDE.md を参照してください。

デフォルトの方針

• 1 つの 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 のコードでは、名前空間付きキーを優先してください。簡易エイリアスは衝突したり、設定によって上書きされたりする可能性があり、予約済みのランタイムキーには付与されません。
• 一括読み込みを行い、1 行ずつ処理しないでください。/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 を作成し、オンデマンド実行を 1 回起動してログを確認してから、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 は Flight ではなく Duckling 上で実行されます。ピークメモリを削減してもメモリ不足で実行に失敗する場合に限り、F32（Business および Enterprise）に変更します。create_flight／update_flight の instance_type、または MD_CREATE_FLIGHT／MD_UPDATE_FLIGHT で設定します。
• Flight が 1 つまたは少数のデータベースだけにアクセスする場合は、duckdb.connect("md:<db>?attach_mode=single") で接続し、ほかのデータベースは明示的にアタッチします。ワークスペース全体をアタッチすると、毎回の実行開始が遅くなります。
• Flight 内で分類、情報抽出、埋め込みを行う場合は、LLM SDK を追加せず、既存の接続を使った SQL 内で prompt_jev()、prompt()、embedding() を呼び出します。
• チームメイト、ロール、または Dive の閲覧者が Flight を開始できるようにするには、所有者が run 権限を付与します（MCP 経由の grant_access、または GRANT RUN ON FLIGHT '<flight_id>' TO ROLE <role>）。付与対象者を提案し、ユーザーの確認後にのみ権限を付与してください。Dive の共有依頼は、その確認に当たりません。ORGANIZATION にはサービスアカウントも含まれるため、ロールを優先してください。実行には毎回、所有者のトークンとシークレットが使われるため、呼び出し元が渡せる設定値はすべて、信頼できない入力として検証します。
• 複数ステップの Flight を作成する前に、実行を追跡可能にするかどうかを決めます。Flight Explainer の計測（Mermaid のステップ図を示す # @flight と、@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 シークレットを先に作成してから、name、source_code、固定した requirements_txt、config、シークレット名を指定して create_flight を呼び出します。まだ 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. 永続テーブルを作成または更新する初回の実行が成功したら、そのテーブルについて data-sources トピックの Guide に記録します（motherduck-manage-guides を参照）。
8. 他のユーザーまたは Dive が Flight を起動する必要がある場合は、run 権限の付与を提案し、ユーザーの確認後にのみ適用して、SHOW GRANTS ON FLIGHT '<flight_id>' で確認します。

回答、レビュー、または計画の依頼では、Flight を作成したりスケジュールを設定したりしないでください。作成または更新の依頼では、依頼の範囲内で求められたデプロイとオンデマンド検証を完了します。定期スケジュールの設定が許可されるのは、依頼にスケジュール設定が含まれている場合のみです。

参考資料

現在のタスクに必要な参考資料のセクションだけを読みます。

• 概念と操作に関する完全なリファレンスは references/FLIGHTS_GUIDE.md を読んでください。内容には、構成、ランタイム環境とサイズ、config とシークレットの違い、スケジュール設定、バージョン管理、実行のライフサイクル、実行権限、Flight Explainer の計測、MCP ツールの完全なリファレンス、MCP と SQL における命名の違い、データ量に応じたロード戦略、トラブルシューティングが含まれます。
• ベストプラクティスに沿った 3 つの完全な Flight テンプレート（dlt による取り込み、Postgres による取り込み、スケジュールされた S3 パーティションの更新）と、それぞれの requirements.txt、シークレットの設定、デプロイ呼び出しについては references/FLIGHT_EXAMPLES.md を読んでください。

関連スキル

不足している機能を補う場合にのみ関連スキルを読み込み、既存のコンテキストを再利用してください。

• Flight で実行する取り込み SQL（CTAS、INSERT ... SELECT、クラウドストレージのシークレット）を選ぶ場合は motherduck-load-data
• デプロイ前に Flight 内の DuckDB SQL を検証する場合は motherduck-query
• 対象のデータベース、スキーマ、テーブルの存在を確認する場合は motherduck-explore
• raw／staging／analytics の完全なパイプライン設計が作業の対象で、Flight はそのスケジューラーにすぎない場合は motherduck-build-data-pipeline
• Dive のボタンまたはフォームで Flight を開始する場合（書き戻し）は motherduck-create-dive
• エージェントがシェルを使用でき、Flight のソースをローカルファイルに保持する場合は motherduck-cli
• 再利用可能な個人または組織の Flight 規約を作成する場合は motherduck-manage-guides