query

query skill の概要

query skill でできること

query skill は、接続済みの作業用データベースに対しても、直接指定したファイルに対しても DuckDB クエリを実行できるようにする skill です。素早く答えにたどり着きたい人向けに作られており、アドホックな SQL、自然言語でのデータ質問、DuckDB Friendly SQL を使ったシンプルなファイル分析に向いています。

どんな人に最適か

すでに DuckDB にデータがある場合、プロジェクトの state file がある場合、あるいは CSV/Parquet などのローカルファイルを持っていて、フルのパイプラインを組まずにすぐ答えが欲しいなら、Data Analysis に query skill を使うのが適しています。特に、データを素早く、反復しながら確認したいアナリスト、エンジニア、AI エージェントに有用です。

この skill が他と違う理由

query の大きな差別化ポイントは、モード選択です。既存の DuckDB state があるときは session mode で動作し、入力がファイルを参照している場合や state が使えない場合は ad-hoc mode に切り替わります。これにより迷いが減り、query skill は継続的なワークフローにも一回限りのワークフローにも使いやすくなります。

query skill の使い方

インストールと基本的な呼び出し方

query skill は npx skills add duckdb/duckdb-skills --skill query でインストールします。その後は SQL でも質問文でも呼び出せます。たとえば query "show daily revenue by country" や query "select count(*) from 'events.csv'" のように使います。query usage のパターンは、1 つの明確なクエリに落とし込めるくらい具体的な依頼で最も効果を発揮します。

session mode と ad-hoc mode の切り替え方

query skill はまず .duckdb-skills/state.sql または ~/.duckdb-skills/<project-id>/state.sql に既存の DuckDB state file があるかを確認します。見つかり、かつ接続済みデータベースが引き続き利用可能であれば session mode を使います。--file を指定した場合、ファイルパスを参照している場合、または利用可能な state がない場合は ad-hoc mode に切り替わり、ファイルを直接クエリするか、必要に応じて :memory: を使います。ここは query guide の中でも特に重要です。なぜなら、入力は実際に使いたいモードに合わせるべきだからです。

まず repo で読むべき箇所

まずは SKILL.md を読みましょう。実行フロー、モードのルール、フォールバック動作がまとまっています。インストール判断のためなら、通常これで十分です。自分のワークフローに合わせて skill を調整するなら、repository tree 内の参照先ファイルも確認してください。とくに state 管理や prompt 制約を定義しているものは要チェックです。この repo には、追加で学ぶべき rules/、resources/、補助スクリプトはありません。

より良い query のためにプロンプトを整える

skill が適切な query を組み立てられるよう、必要最小限の文脈だけを与えてください。対象のファイルや table、見たい metric、粒度、filter、時間範囲を明示します。たとえば query "For orders.csv, show revenue by month for 2024 and exclude refunds" のような入力は強く、query "analyze the sales data" のような入力は弱いです。前者なら、ファイルベースでアクセスすべきか、何を集計するか、どの例外条件が重要かまで skill に伝わります。

query skill FAQ

query skill は SQL の上級者だけ向けですか？

いいえ。query skill は生の SQL も自然言語の質問も受け付けるので、初心者でも基本的な分析に使えます。ただし、正確な join、filter、集計ルールが必要な場面では SQL のほうが有利です。

どんなときに query skill を使うべきではありませんか？

複数段階の変換ロジックが必要で、それが notebook、ETL job、アプリケーションコードに属するようなタスクには使わないでください。これはデータ質問を投げて答えを得るために最適化されており、完全な data product を作る用途には向いていません。

一般的な prompt と比べて何が違いますか？

一般的な prompt でももっともらしい query は生成されるかもしれませんが、query skill には運用上のルールがあります。DuckDB state を確認し、session と ad-hoc を切り替え、DuckDB が使えるかを検証し、attachment が失敗した場合も安全にフォールバックします。そのため、install 時の評価や繰り返しの query usage ではより信頼性が高くなります。

ファイルやローカル分析に向いていますか？

はい。ローカルの CSV、Parquet、または DuckDB で読み取り可能な他のファイルに対して query for Data Analysis をしたいなら、この skill は適しています。session state がない、あるいは使うべきでない場合でも、ファイルを直接クエリする前提で設計されているからです。

query skill の改善方法

データの形を正確に伝える

改善効果が最も大きいのは、入力元と出力の形を明確にすることです。table 名、file 名、必要な column、返してほしい粒度を含めてください。たとえば query "from sessions.parquet, group by user_id and return avg session length for paid users only" と書けば、skill は広すぎる結果や曖昧な結果を避けやすくなります。

最初の実行前に曖昧さをなくす

よくある失敗は、「insights が欲しい」とだけ伝えて、何を数えるのか、比較するのか、filter するのかを言わないことです。metric、日付範囲、セグメント条件が分かっているなら、最初から入れてください。やり取りの往復が減り、最初の回答が実用的になります。

モード固有の制約は早めに確認する

session mode を期待しているなら、project state が存在し、接続済みデータベースがまだ開けることを確認してください。file mode を期待しているなら、prompt でファイルを直接参照するか、--file を指定してください。query skill は既存 state を再利用できるか、ad hoc で動くしかないかによって挙動が変わるため、ここは重要です。

目標を少しずつ絞って反復する

最初の結果が出たら、次の prompt では 1 つずつ制約を足していきます。時間範囲を狭める、より適切な join key を指定する、grouping の粒度を変える、必須の除外条件を追加する、といった形です。そうすることで、query skill を曖昧な要約ではなく、意思決定に使える結果へ近づけられます。