motherduck-query

MotherDuck のクエリ

前提条件

• MotherDuck への接続が確立されていること（または MotherDuck MCP サーバーが稼働していること）
• 対象のデータベースとテーブルが特定されていること

基本方針

• MotherDuck MCP が利用可能で、クエリがビジネス上の質問に答える場合は、SQL を書く前に get_query_guide を呼び出します。関連するトピックのみをたどり、Guide の記載内容をライブスキーマと照合して確認します。
• PG エンドポイントを使用する場合でも、PostgreSQL SQL ではなく DuckDB SQL を記述します。
• "database"."schema"."table" の完全修飾名を優先します。複数のデータベースまたは共有がアタッチされている場合は、完全修飾名が必須です。
• クエリを最適化またはマテリアライズする前に、結果の粒度を維持し、結合のカーディナリティを確認します。
• 早い段階でフィルター処理と集計を行い、繰り返し読み込む場合は提供用テーブルまたはサマリーを優先します。
• SQL は分かりやすい複数行形式にし、粒度、フィルター、出力形式を明示します。
• DDL、DML、ATTACH、DETACH、CREATE SNAPSHOT、ALTER DATABASE ... SET SNAPSHOT、UNDROP DATABASE などの復旧コマンド、および SHUTDOWN などのライフサイクルコマンドは書き込みとして扱います。ユーザーの変更依頼で書き込みが許可されている場合は、MotherDuck MCP の query_rw ツールを使用します。操作が破壊的な場合、外部から確認可能な場合、または依頼された範囲外の場合にのみ、確認を求めます。
• 接続経路が対応している場合は、長期間使用するインテグレーションに custom_user_agent を設定します。このタグは Duckling Overview とクエリ履歴にクエリごとに表示されます。
• テキストや画像の分類、スコアリング、ルーティング、はい／いいえの判定には prompt_jev() を使用します。型付きの確率とラベルを返し、入力トークン分のみが課金され、行をまとめて処理します。生成テキストや、struct または json_schema を用いた自由形式の抽出には prompt() を使用します。どちらも行ごとに課金される呼び出しです。小さな LIMIT でテストし、結果をテーブルに保存して、NULL の行のみを再実行します。

ワークフロー

1. SQL を書く前に、実際のテーブル、列、粒度を確認します。
2. MCP が利用可能な場合は、スキーマの確認の代わりにすることなく、関連する Guide のコンテキストを読み込みます。
3. まず SQL でクエリを記述し、必要な場合にのみ Python または TypeScript でラップします。
4. クエリが簡潔になる場合は DuckDB ネイティブのパターンを使用します。単純な参照に CTE やマテリアライズは不要です。
5. 結果の形式と主要な集計値を検証します。パフォーマンスが依頼内容に含まれている場合、または実行に問題が発生した場合は、実行計画を確認します。
6. 必要に応じて、コストの高い繰り返しクエリを提供用テーブルまたは軽量なビューにマテリアライズします。

参考資料

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

• DuckDB のクエリパターン、探索用 SQL、パフォーマンスのルール、一般的な分析パターン、よくある間違いについては、references/QUERY_PLAYBOOK.md を読みます
• クエリで prompt_jev()、prompt()、または embedding() を呼び出す場合は、references/AI_FUNCTIONS.md を読みます

関連スキル

不足している機能を補う場合にのみ関連スキルを読み込み、確立済みのコンテキストを再利用します。

• セッション設定には motherduck-connect
• 構文と関数のリファレンスには motherduck-duckdb-sql
• クエリ作成前のソーススキーマの理解には motherduck-explore
• セマンティックな定義や再利用可能なクエリルールの確認・管理には motherduck-manage-guides