スキルOfficialdevelopment

📊aidp-analyzing-data

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

説明

Spark SQL を使用して AIDP レイクハウス上のビジネスに関する質問に回答します。次のような場合に使用: ユーザーがデータに関する質問（「件数は？」「上位N件は？」「見せて」「推移は？」「売上の内訳は？」など）をしたとき、またはアドホックな Spark SQL を実行したいとき。 `.aidp/catalog.md` および `.aidp/semantic.md` を根拠として参照し、SQL を生成する前に検証済みクエリを再利用します。その後、バンドルされた `aidp_sql.py` ヘルパー経由でクエリを実行します。

原文を表示

Answer business questions over the AIDP lakehouse with Spark SQL. Use when the user asks a data question ("how many…", "top N…", "show me…", "trend of…", "revenue by…") or wants to run ad-hoc Spark SQL. Grounds in .aidp/catalog.md + .aidp/semantic.md and reuses validated verified queries before generating SQL, then executes via the bundled aidp_sql.py helper.

ユースケース

✓データに関する質問に回答するとき
✓件数や上位N件などの集計を確認するとき
✓売上内訳などの分析結果を見たいとき
✓データの推移を確認するとき
✓アドホックなSpark SQLを実行したいとき

本文（日本語訳）

`aidp-analyzing-data` — 自然言語 → Spark SQL

カタログ／セマンティックモデルに基づいてビジネス上の問いに答えるスキルです。検証済みクエリを可能な限り再利用し、付属の scripts/aidp_sql.py ヘルパー経由で Spark SQL を実行します。

次のような場合に使用

データに関する質問全般、または「この SQL を AIDP 上で実行したい」場合。

ソースが外部システム／非レイクハウスシステム（Fusion、EPM、Oracle ADB/ExaCS、Snowflake、S3 など）の場合、このスキルは レイクハウスネイティブの Spark SQL です。外部ソースからデータを取得するには、oracle-ai-data-platform-workbench-spark-connectors plugin の aidp-<source> スキルを使用してください（未インストールの場合はインストールし、 aidp-connectors-bootstrap スキルを一度実行してヘルパーパッケージをクラスターにデプロイしてください）。複数ソースをまたいだ結合には aidp-federate を使用します。

ワークフロー（グラウンディング優先 — これが精度を左右します）

検証済みクエリとのマッチング。 .aidp/verified-queries.md を読み込み、verified: true のエントリが質問と近似している場合（テキストが類似しておりテーブルが重複している場合）、その SQL を再利用します（日付やバインド値のみを適宜修正）。その旨をユーザーに伝えてください。
グラウンディング。 上記に該当しない場合は .aidp/catalog.md と .aidp/semantic.md を読み込みます。クイックリファレンス／シノニムを通じて概念→テーブルのマッピングを行い、記録された 結合キーを使用し（結合を推測しない）、 WHERE 句のリテラルには値ディクショナリを活用し、セマンティックモデルのメトリクス SQL 式を優先して使用します。カタログキャッシュが存在しない場合は、先に aidp-catalog-init を実行してください。
スコープを絞る。 質問に必要な最小限のテーブルのみを使用します。大規模ファクトテーブルには日付フィルターを追加し、複雑なクエリが繰り返される場合は事前結合済みビューの利用を検討してください。
実行。 付属のヘルパー経由で SQL を実行します。ヘルパーは api_key の DEFAULT プロファイルから UPST を生成し、対象クラスター上にスクラッチノートブックを自動作成します（MCP も AIDP_SESSION も不要）:
```
python "$PLUGIN_DIR/scripts/aidp_sql.py" \
  --region <region> --datalake <DATALAKE_OCID> --workspace <ws> --cluster <cluster-key> \
  --code "spark.sql('''<SQL>''').show(50, truncate=False)"
```
戻り値は JSON 形式 {status, execution_count, outputs, spark_job_ids, error} です。呼び出しのたびにセルが実行されます。後続のやり取りでも同じ <SQL> の構造を維持してください。接続確認には --code "spark.sql('SELECT 1').show()" を使用してください。
結果の提示。 結果を明確に提示します（テーブル形式 + 内容を一行で要約）。実行した SQL も示してください。
学習内容のキャッシュ。 新たな概念→テーブルのマッピングを .aidp/catalog.md に保存するか、 aidp-verified-queries 経由で動作確認済みクエリを登録することを提案してください（検証済みとしてマークする前にバリデーションが行われます）。

信頼性に関するルール

現実の NL→SQL 変換はグラウンディングなしでは不安定です。カラム名やテーブル名を推測で生成しないでください。不確かな場合はカタログキャッシュ（または SHOW COLUMNS / DESCRIBE セル）で確認するか、ユーザーに尋ねてください。
テーブルは完全修飾名で指定してください（catalog.schema.table）。カタログ／スキーマのデフォルト省略はユーザーが明示的に示した場合のみ許容します。メタデータコマンドも同様です。SHOW TABLES IN <catalog>.<schema> の形式を使用してください（例: SHOW TABLES IN default.default）。 SHOW TABLES IN default のような非修飾形式は使用しないでください — default がスキーマではなくカタログとして解釈されるため、 AnalysisException: [SCHEMA_NOT_FOUND] が発生します。
クエリがエラーになった場合は、ヘルパーの error フィールドから Spark エラーを読み取り、カタログに基づいて修正してから再試行してください。繰り返し推測による修正は行わないでください。
実行前にクラスターが RUNNING 状態であることを確認してください（aidp-cluster-ops 参照）。ヘルパーは --cluster で指定されたクラスターにアタッチします。
SQL 内での LLM 活用（ai_generate）については aidp-ai-sql を、クロスソース結合については aidp-federate を参照してください。

参考資料

scripts/aidp_sql.py — 付属の Spark SQL 実行ヘルパー（pluginの唯一のコード）
references/verified-queries.md · references/semantic-model.md · references/no-mcp-rest-map.md

原文（English）を表示

`aidp-analyzing-data` — natural language → Spark SQL

Answer business questions by grounding in the catalog/semantic model, reusing verified queries when possible, then executing Spark SQL via the bundled scripts/aidp_sql.py helper.

When to use

Any data question, or "run this SQL on AIDP".

Source is an external / non-lakehouse system (Fusion, EPM, Oracle ADB/ExaCS, Snowflake, S3, …)? This skill is lakehouse-native Spark SQL. To pull from an external source, use the oracle-ai-data-platform-workbench-spark-connectors plugin's aidp-<source> skill (install it if absent; run its aidp-connectors-bootstrap skill once to push the helper package to the cluster), or aidp-federate to join across sources.

Workflow (grounding-first — this is the accuracy lever)

Verified-query match. Read .aidp/verified-queries.md; if a verified: true entry closely matches the question (similar text + table overlap), reuse its SQL (adapt only dates/bind values) and say so.
Ground. Otherwise read .aidp/catalog.md + .aidp/semantic.md: map concepts→tables via Quick Reference/synonyms, use recorded join keys (don't guess joins), use value dictionaries for WHERE literals, prefer metric SQL expressions from the semantic model. If the catalog cache is missing, run aidp-catalog-init first.
Scope small. Use the few tables the question needs; for big fact tables add date filters; consider a pre-joined view for repeated complex asks.
Execute. Run the SQL via the bundled helper — it mints a UPST from the api_key DEFAULT profile and auto-creates a scratch notebook on the target cluster (no MCP, no AIDP_SESSION required):
```
python "$PLUGIN_DIR/scripts/aidp_sql.py" \
  --region <region> --datalake <DATALAKE_OCID> --workspace <ws> --cluster <cluster-key> \
  --code "spark.sql('''<SQL>''').show(50, truncate=False)"
```
Returns JSON {status, execution_count, outputs, spark_job_ids, error}. Each invocation runs the cell; keep the same <SQL> shape across follow-ups. Smoke-test connectivity with --code "spark.sql('SELECT 1').show()".
Present the result clearly (table + a one-line read of what it shows). Show the SQL you ran.
Cache the learning. Offer to save a new concept→table mapping to .aidp/catalog.md and/or register the working query via aidp-verified-queries (which validates before marking it verified).

Reliability rules

Real-world NL-to-SQL is unreliable without grounding — never fabricate column/table names; if unsure, confirm against the catalog cache (or a SHOW COLUMNS / DESCRIBE cell) or ask.
Qualify tables fully (catalog.schema.table). Default catalog/schema only when the user implies them. This includes metadata commands: use SHOW TABLES IN <catalog>.<schema> (e.g. SHOW TABLES IN default.default), not the unqualified SHOW TABLES IN default — the bare form raises AnalysisException: [SCHEMA_NOT_FOUND] because default resolves as a catalog, not a schema.
If a query errors, read the Spark error from the helper's error field, fix grounded in the catalog, and retry — don't guess repeatedly.
Ensure the cluster is RUNNING before executing (see aidp-cluster-ops); the helper attaches to the cluster you pass via --cluster.
For LLM-in-SQL (ai_generate) see aidp-ai-sql; for cross-source joins see aidp-federate.

References

scripts/aidp_sql.py — bundled Spark-SQL executor (the plugin's only code)
references/verified-queries.md · references/semantic-model.md · references/no-mcp-rest-map.md

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