motherduck-load-data

MotherDuck にデータをロードする

情報源

• まず、MotherDuck の最新のデータロード、クラウドストレージ、Postgres エンドポイント経由のデータロードに関するドキュメントを優先してください。
• 保護されたオブジェクトストレージを使用するワークフローでは、CREATE SECRET とクラウドストレージのドキュメントを使用してください。
• ソースが既存のローカル .duckdb、.ddb、またはアタッチ済みの DuckDB データベースの場合は、DuckDB データベースのアップロードに関するドキュメントを使用してください。
• データロードに関するアドバイスは、MotherDuck が文書化している方針に沿わせてください。
  • ストリーミングよりバッチ処理を優先する
  • 形式を制御できる場合は、CSV より Parquet を優先する
  • 1 行ずつの挿入より、データフレーム、COPY、CTAS、または INSERT ... SELECT を優先する
  • DuckLake が明示的に必要でない限り、ネイティブの MotherDuck ストレージを優先する

デフォルト方針

• まず、ソースをオブジェクトストレージまたは HTTPS、ローカルファイルまたはローカル DuckDB、メモリ内の行、外部データベースに分類してください。
• 初回ロードには CREATE TABLE AS SELECT、追加には INSERT INTO ... SELECT を優先してください。
• DuckDB データベース全体を対象とする場合は、CREATE OR REPLACE DATABASE remote_name FROM CURRENT_DATABASE()、アタッチ済みのローカルデータベース、ネイティブクライアントからのローカルファイルパス、または S3 などのリモート .duckdb ファイル URL を使用してください。リモートファイルとローカルファイルのインポートではデータが物理的に MotherDuck にコピーされますが、データベースや共有のクローンソースではゼロコピーです。
• ソース形式を制御できる場合、永続的な一括転送には Parquet を使用してください。
• Postgres エンドポイントは、サーバー側でリモート読み取りを行うためのシンクライアント経路として扱い、ローカルファイルや拡張機能を使用したデータ取り込みには使用しないでください。
• データ取り込みツールがターゲットデータベースを自動作成しない場合は、まず MotherDuck にターゲットデータベースを作成してください。
• raw のランディングデータには最低限の変換のみを適用し、型変換、重複排除、ビジネスロジックはステージングまたはモデリングの工程で処理してください。
• 配置を制御できる場合は、ソースストレージを MotherDuck のリージョンに近づけてください。

ワークフロー

1. ソースデータが実際にどこにあるかを特定します。
2. データロード経路を選択します。
   • オブジェクトストレージまたは HTTPS：MotherDuck にリモート読み取りする
   • ローカルファイルまたはローカル DuckDB：DuckDB クライアント経路を使用する
   • リモート DuckDB データベースファイル：必要なクラウドシークレットを使って CREATE DATABASE ... FROM '<cloud-url>' を使用する
   • メモリ内の行：まず Arrow またはデータフレームによる一括ロードを行い、バッチ挿入は代替手段としてのみ使用する
   • 外部データベース：DuckDB を利用できる環境から、適切なスキャンまたはレプリケーション経路を使用する
3. 最小限の変換で、raw テーブルまたはステージングテーブルにデータを格納します。
4. ロード直後に、行数、型、いくつかのビジネス集計値を検証します。
5. 依頼に変換が含まれる場合にのみ、モデリング済みテーブルへ昇格します。宛先データの検証が完了すれば、ロード依頼は完了です。

回答、レビュー、または計画の依頼では、データを変更せずにデータロード経路を提案してください。ロードまたは実装の依頼では、対象範囲内で依頼された書き込みと検証を実行し、破壊的な置換や、より広範な外部書き込みを行う前に確認してください。

参考資料

現在のタスクに必要な参考セクションのみを参照してください。

• 形式別のオプション、クラウドストレージのシークレット、Postgres エンドポイント経由のデータロードにおけるトレードオフ、Python データフレーム経路、高度なデータ取り込みパターンについては、references/INGESTION_PATTERNS.md を参照してください。

関連スキル

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

• Postgres エンドポイントと DuckDB クライアント経路のどちらを選ぶか判断するには、motherduck-connect を使用する
• 宛先データベースの調査や、格納したテーブルの検証には、motherduck-explore を使用する
• CTAS、追加、検証用の SQL を作成するには、motherduck-query を使用する
• 格納したデータをステージングテーブルや分析テーブルへ昇格するには、motherduck-model-data を使用する
• オブジェクトストレージを基盤とするレイクハウスストレージが明示的に必要な場合に限り、motherduck-ducklake を使用する
• シェルベースのロードで構造化出力をファイルにストリーミングする場合は、motherduck-cli を使用する