スキルOfficialdevelopment

🔐aidp-verified-queries

プラグイン: oracle-ai-data-platform-workbench-engineer-agent
ソース: GitHub で見る ↗

説明

再利用可能な「質問→Spark SQL」のペアを `.aidp/verified-queries.md` に登録・検証し、エージェントが新しいSQLを生成する前に信頼済みのSQLを再利用できるようにします。次のような場合に使用: - 動作確認済みのクエリを正規クエリとして保存したい - 検証済みクエリのリポジトリを構築したい - 繰り返し発生する質問に対する回答の信頼性を向上させたい各ペアは「検証済み」としてマークする前に、クラスター上で実際に検証されます。

原文を表示

Register and validate reusable question→Spark-SQL pairs in .aidp/verified-queries.md so the agent reuses trusted SQL before generating new SQL. Use when the user wants to save a working query as canonical, build a verified-query repository, or improve answer reliability for recurring questions. Validates each pair on the cluster before marking it verified.

ユースケース

✓動作確認済みクエリを正規クエリとして保存する
✓検証済みクエリのリポジトリを構築する
✓繰り返し発生する質問への回答信頼性を向上させる

本文（日本語訳）

`aidp-verified-queries` — 検証済みクエリリポジトリ（VQR）

.aidp/verified-queries.md を管理するスキルです。このファイルには、検証済みの「質問 → Spark SQL」ペアが蓄積されており、 aidp-analyzing-data がゼロからSQLを生成する前に再利用します。これは、最も高い信頼性を持つNL-to-SQLメカニズムです。

次のような場合に使用

動作確認済みのクエリを、繰り返し問われる質問への標準的な回答として保存する場合
検証済みクエリリポジトリの整理・クリーニングを行う場合

品質ゲート（重要 — スキップ厳禁）

誤った検証済みクエリは、精度を悪化させます。 verified: true に設定する前に、以下の条件をすべて満たす必要があります。

構文的に有効な Spark SQL であること
クラスター上で実行可能であること（同梱の scripts/aidp_sql.py ヘルパー経由で実行）
記載された質問に実際に回答していること（結果の形状・値をサニティチェック）

いずれかのチェックが失敗した場合は verified: false（DRAFT）のままにし、理由を記録してください。失敗したペアを自動的に昇格させてはなりません。

ワークフロー

候補となる質問とSQL（または aidp-analyzing-data で最後に実行されたクエリ）を読み込む。
.aidp/semantic.md の論理名を優先し、参照する物理テーブルを記録する。
同梱ヘルパーを使ってSQLをクラスター上で実行し、検証する（MCP不要）:
```
python "$PLUGIN_DIR/scripts/aidp_sql.py" \
  --region <region> --datalake <DATALAKE_OCID> --workspace <ws> --cluster <cluster-key> \
  --code "spark.sql('''<your SELECT … LIMIT 50>''').show(50, truncate=False)"
```
このスクリプトは、api_key の DEFAULT プロファイルから UPST を生成し、スクラッチノートブックを自動作成して、{status, outputs, spark_job_ids} 形式のJSONを返します。 status == "ok" であること、かつ質問に回答する結果が得られることを確認してください。検証コストを抑えるため、件数を絞ったサンプル（LIMIT を付加）で実行してください。
所定のフォーマットに従いエントリを .aidp/verified-queries.md に追記する。 verified: true は、実行成功が記録されている場合のみ設定すること（クラスターと日付を明記）。
再利用時、aidp-analyzing-data は質問の類似度とテーブルの重複度でマッチングし、日付・バインド値のみを適宜調整して使用する。

備考

.aidp/verified-queries.md はユーザーが編集可能で、gitの管理対象外です（プロジェクトごとに設定）。
エントリは小さく単一目的に保つこと。複雑な問いには、完全な作業例をそのまま記載してください。
このスキルは自己完結しています。検証は scripts/aidp_sql.py を通じて実行され、 MCPサーバーは不要です。aidp MCPが設定されている場合は nb_execute_code をアクセラレーターとして使用してもかまいませんが、必須ではありません。

参考資料

references/verified-queries.md · references/semantic-model.md
SQL実行ヘルパー: references/no-mcp-rest-map.md（scripts/aidp_sql.py を使ったMCP不要のSQL実行）

原文（English）を表示

`aidp-verified-queries` — the verified-query repository (VQR)

Maintain .aidp/verified-queries.md: validated question → Spark SQL pairs that aidp-analyzing-data reuses before generating SQL from scratch — the highest-reliability NL-to-SQL mechanism.

When to use

Save a working query as the canonical answer to a recurring question.
Curate/clean the verified-query repository.

Quality gate (critical — do not skip)

A wrong verified query makes accuracy worse. Before setting verified: true, the pair MUST:

be syntactically valid Spark SQL,
execute on the cluster (run it via the bundled scripts/aidp_sql.py helper),
actually answer the stated question (sanity-check the result shape/values). If any check fails, keep verified: false (DRAFT) and explain why — never auto-promote a failing pair.

Workflow

Read the candidate question + SQL (or take the last query run in aidp-analyzing-data).
Prefer logical names from .aidp/semantic.md; record the physical tables touched.
Validate by running the SQL on the cluster with the bundled helper (no MCP required):
```
python "$PLUGIN_DIR/scripts/aidp_sql.py" \
  --region <region> --datalake <DATALAKE_OCID> --workspace <ws> --cluster <cluster-key> \
  --code "spark.sql('''<your SELECT … LIMIT 50>''').show(50, truncate=False)"
```
It mints a UPST from the api_key DEFAULT profile, auto-creates a scratch notebook, and returns JSON {status, outputs, spark_job_ids}. Require status == "ok" and a result that answers the question. Run on a bounded sample (add LIMIT) to keep validation cheap.
Append the entry to .aidp/verified-queries.md in the documented format; set verified: true only on a recorded successful run (note cluster + date).
On reuse, aidp-analyzing-data matches by question similarity + table overlap and adapts only dates/bind values.

Notes

.aidp/verified-queries.md is user-editable and git-ignored (per-project).
Keep entries small, single-purpose; complex asks get a complete worked example.
This skill is self-contained: validation runs through scripts/aidp_sql.py, not any MCP server. If an aidp MCP happens to be configured you may use its nb_execute_code as an accelerator, but it is not required.

References

references/verified-queries.md · references/semantic-model.md
SQL execution helper: references/no-mcp-rest-map.md (No-MCP SQL via scripts/aidp_sql.py)

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。