スキルOfficialdevelopment

📝aidp-sql-ddl

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

説明

AIDPレイクハウス上のSpark SQLによる書き込み系操作を担当します。対象操作は以下の通りです： - **DDL**: テーブル・ビュー・スキーマの作成（CREATE）／変更（ALTER）／削除（DROP） - **DML**: INSERT / UPDATE / DELETE / MERGE によるアップサート - **Deltaメンテナンス**: OPTIMIZE（最適化）、VACUUM（クリーンアップ）、タイムトラベル、RESTORE（復元）、スキーマエボリューション、リキッドクラスタリング次のような場合に使用: テーブルやビューの作成・変更・削除、行の挿入・更新・削除・マージ、アップサート、Deltaテーブルのコンパクション／最適化／バキューム、旧バージョンの参照（タイムトラベル）、リストア、スキーマの変更、またはSELECT以外のあらゆるSQL実行を行いたい場合。読み取り専用の分析には `aidp-analyzing-data` を使用してください。コントロールプレーン（CLI／REST）経由のテーブルライフサイクル管理には `aidp-table-management` を使用してください。

原文を表示

Write-side Spark SQL on the AIDP lakehouse — DDL (CREATE/ALTER/DROP table·view·schema), DML (INSERT/UPDATE/DELETE/MERGE upsert), and Delta maintenance (OPTIMIZE, VACUUM, time travel, RESTORE, schema evolution, liquid clustering). Use when the user wants to create/alter/drop a table or view, insert/update/delete/merge rows, upsert, compact/optimize/vacuum a Delta table, query an old version (time travel), restore, evolve a schema, or run any non-SELECT SQL. For read-only analytics use aidp-analyzing-data; for control-plane (CLI/REST) table lifecycle use aidp-table-management.

ユースケース

✓テーブル・ビュー・スキーマの作成・変更・削除
✓行の挿入・更新・削除・マージを実行
✓Deltaテーブルの最適化・クリーンアップ
✓旧バージョンのテーブル状態を参照
✓SELECT以外のSQL操作を実行

本文（日本語訳）

`aidp-sql-ddl` — レイクハウス書き込み SQL（DDL / DML / Delta メンテナンス）

AIDP は Spark 3.5 + Delta Lake 3.2（platform-ref §39）で動作するため、同梱の scripts/aidp_sql.py ヘルパーを通じて完全な書き込み文法が利用できます。これは aidp-analyzing-data が SELECT に使用しているのと同じエンジンです。本スキルはデータまたはスキーマを変更するすべての操作を対象とします。

AIDP 2026-06-10 にて動作確認済み（USER クラスター、aidp_sql.py 経由、すべてアンラップ済み → status: ok）: CREATE TABLE、INSERT、UPDATE、DELETE、MERGE、OPTIMIZE、VACUUM、 DESCRIBE HISTORY、タイムトラベル（VERSION AS OF）、DROP — Spark 3.5 / Delta 3.2 の書き込み文法（platform-ref §39）がエンドツーエンドで実行可能です。

（テスター1名が、全く新しいインスタンスで最初の素の CREATE TABLE を実行した際に一時的なカタログ登録エラーが発生したと報告しましたが、新規インスタンスでは再現されませんでした。詳細は後述の「注意事項」を参照してください。）

次のような場合に使用

テーブル・ビュー・スキーマの作成 / 変更 / 削除
行の挿入 / 更新 / 削除 / マージ（upsert）
Delta テーブルの OPTIMIZE / VACUUM / タイムトラベル / RESTORE
スキーマの変更（スキーマ進化）
リキッドクラスタリング

以下には使用しないこと:

SELECT / 分析 → aidp-analyzing-data を使用
コントロールプレーンのカタログ / 接続登録 → aidp-table-management を使用

ミューテーションゲート（必須）

ここに記載されたすべてのステートメントは状態を変更します。 DML / DDL を実行する前に、以下の手順を必ず実施してください:

クラスターが RUNNING 状態であることを確認し（aidp-cluster-ops）、オブジェクトを完全修飾名で指定する（catalog.schema.table）。
正確な SQL を提示し、実行前に明示的な確認を取る — 特に DROP、DELETE、TRUNCATE、INSERT OVERWRITE、VACUUM に注意（VACUUM は古いファイルを永続的に削除するため、タイムトラベルが使用不能になります）。
ステートメントを references/payloads.md に従い .aidp/payloads/ に保存する。
可能な限りドライランを先に実行する: UPDATE / DELETE の前に SELECT count(*) … WHERE <predicate> で対象件数を確認する。

実行方法（analyzing-data と同じヘルパーを使用）

python "$PLUGIN_DIR/scripts/aidp_sql.py" \
  --region <region> --datalake <DATALAKE_OCID> --workspace <ws> --cluster <cluster-key> \
  --code "spark.sql('''<SQL>''')"

返却される JSON: {status, execution_count, outputs, spark_job_ids, error} MCP 不要 / AIDP_SESSION 不要。

クイックリファレンス（Spark 3.5 / Delta 3.2）

操作	SQL
マネージド Delta テーブルの作成	`CREATE TABLE c.s.t (id INT, v STRING) USING DELTA`
CTAS	`CREATE TABLE c.s.t USING DELTA AS SELECT …`
リキッドクラスタリング	`CREATE TABLE … CLUSTER BY (col)`（または `ALTER TABLE … CLUSTER BY`）
挿入	`INSERT INTO c.s.t VALUES (…)` · 全件再ロード: `INSERT OVERWRITE c.s.t SELECT …`
更新 / 削除	`UPDATE c.s.t SET v='x' WHERE …` · `DELETE FROM c.s.t WHERE …`
Upsert（MERGE）	`MERGE INTO c.s.t t USING src s ON t.id=s.id WHEN MATCHED THEN UPDATE SET * WHEN NOT MATCHED THEN INSERT *`
スキーマ変更	`ALTER TABLE c.s.t ADD COLUMNS (x INT)` · `… RENAME COLUMN` · `… DROP COLUMN`; または `mergeSchema` オプション付き書き込み
ファイル圧縮	`OPTIMIZE c.s.t [ZORDER BY (col)]`
ファイル回収	`VACUUM c.s.t RETAIN 168 HOURS` ※破壊的操作 — 要確認。168時間未満にするには `spark.databricks.delta.retentionDurationCheck.enabled=false` が必要
履歴確認	`DESCRIBE HISTORY c.s.t`
タイムトラベル	`SELECT * FROM c.s.t VERSION AS OF 3` · `… TIMESTAMP AS OF '2026-06-01'`
リストア	`RESTORE TABLE c.s.t TO VERSION AS OF 3`
ビュー	`CREATE VIEW c.s.v AS SELECT …` · `CREATE OR REPLACE VIEW …` · `DROP VIEW …`
スキーマ（名前空間）	`CREATE SCHEMA IF NOT EXISTS c.s` · `DROP SCHEMA c.s [CASCADE]`

注意事項 — 最初の `CREATE TABLE` で発生した一時的エラーの報告（再現不可）

あるテスターが、プロビジョニングしたばかりの DataLake で最初の素の CREATE TABLE … USING DELTA を実行した際に、 ArrayIndexOutOfBoundsException: Index 0 out of bounds for length 0 （カタログ登録のレースコンディションと推測され、SQL エラーではない）が発生したと報告しました。

このエラーは再現できませんでした。 実際に新たにプロビジョニングした DataLake + クラスターでは、初回の素の CREATE TABLE が正常に成功しました （2026-06-12 に新規インスタンスで確認済み — テーブル作成後、SHOW TABLES で確認。既存インスタンスでも問題なし）。

したがって、これはプロビジョニング直後のごく短い時間帯にのみ発生しうる 一時的な現象として扱ってください。決定的な挙動ではありません。

万が一このエラーに遭遇した場合は、DDL を繰り返し叩かないでください。代わりにライター（spark.createDataFrame(rows).write.saveAsTable('c.s.t')）または aidp-ingest-file-to-table（ingest → CTAS）でカタログをウォームアップしてから、素の CREATE TABLE を実行してください。

信頼性に関する注意

テーブル名・カラム名は絶対に推測で補完しないこと — .aidp/catalog.md または DESCRIBE / SHOW COLUMNS で必ず確認する。
エラー発生時はヘルパーの error フィールドを読み、カタログを根拠に修正してから 1回だけリトライする — 繰り返し推測しない。
MERGE は再実行可能なパイプライン向けの冪等 upsert パターンです（aidp-pipelines と組み合わせること）。
外部テーブル / Iceberg / oci:// 上の Delta テーブルに対する他ソースからの読み書きは、 …-spark-connectors plugin（aidp-iceberg、aidp-object-storage）に委譲してください。本スキルはレイクハウスネイティブな SQL 専用です。

参照

scripts/aidp_sql.py — Spark-SQL エグゼキューター
aidp-analyzing-data（SELECT）· aidp-table-management（コントロールプレーン CRUD）· aidp-cluster-ops（クラスターが RUNNING であること）
references/payloads.md — 変更前にステートメントを保存・確認すること

原文（English）を表示

`aidp-sql-ddl` — lakehouse write SQL (DDL / DML / Delta maintenance)

AIDP runs Spark 3.5 + Delta Lake 3.2 (platform-ref §39), so the full write grammar works through the bundled scripts/aidp_sql.py helper — the same engine aidp-analyzing-data uses for SELECT. This skill covers everything that changes data or schema. Live-verified on AIDP 2026-06-10 (USER cluster, via aidp_sql.py, all un-wrapped → status: ok): CREATE TABLE, INSERT, UPDATE, DELETE, MERGE, OPTIMIZE, VACUUM, DESCRIBE HISTORY, time travel (VERSION AS OF), DROP — the full Spark 3.5 / Delta 3.2 write grammar (platform-ref §39) executes end-to-end. (A tester once saw the first bare CREATE TABLE on a brand-new instance throw a transient catalog-registration error; it was not reproducible on a fresh instance — see Caveat below.)

When to use

Create/alter/drop a table, view, or schema · insert/update/delete/merge (upsert) rows · OPTIMIZE / VACUUM / time-travel / RESTORE a Delta table · evolve a schema · liquid clustering.
NOT for SELECT/analytics → aidp-analyzing-data. NOT for control-plane catalog/connection registration → aidp-table-management.

Mutation gate (required)

Every statement here changes state. Before running any DML/DDL:

Confirm the cluster is RUNNING (aidp-cluster-ops) and qualify objects fully (catalog.schema.table).
Show the exact SQL and get explicit confirmation before executing — especially DROP, DELETE, TRUNCATE, INSERT OVERWRITE, VACUUM (VACUUM permanently removes old files → breaks time travel).
Persist the statement(s) to .aidp/payloads/ per references/payloads.md.
Prefer a dry-run first: SELECT count(*) … WHERE <predicate> before the matching UPDATE/DELETE.

Execute (same helper as analyzing-data)

python "$PLUGIN_DIR/scripts/aidp_sql.py" \
  --region <region> --datalake <DATALAKE_OCID> --workspace <ws> --cluster <cluster-key> \
  --code "spark.sql('''<SQL>''')"

Returns JSON {status, execution_count, outputs, spark_job_ids, error}. No MCP / no AIDP_SESSION needed.

Quick reference (Spark 3.5 / Delta 3.2)

Need	SQL
Create managed Delta table	`CREATE TABLE c.s.t (id INT, v STRING) USING DELTA`
CTAS	`CREATE TABLE c.s.t USING DELTA AS SELECT …`
Liquid clustering	`CREATE TABLE … CLUSTER BY (col)` (or `ALTER TABLE … CLUSTER BY`)
Insert	`INSERT INTO c.s.t VALUES (…)` · full reload `INSERT OVERWRITE c.s.t SELECT …`
Update / Delete	`UPDATE c.s.t SET v='x' WHERE …` · `DELETE FROM c.s.t WHERE …`
Upsert (MERGE)	`MERGE INTO c.s.t t USING src s ON t.id=s.id WHEN MATCHED THEN UPDATE SET * WHEN NOT MATCHED THEN INSERT *`
Schema evolution	`ALTER TABLE c.s.t ADD COLUMNS (x INT)` · `… RENAME COLUMN` · `… DROP COLUMN`; or write with `mergeSchema`
Compact	`OPTIMIZE c.s.t [ZORDER BY (col)]`
Reclaim files	`VACUUM c.s.t RETAIN 168 HOURS` (destructive — confirm; <168h needs `spark.databricks.delta.retentionDurationCheck.enabled=false`)
History	`DESCRIBE HISTORY c.s.t`
Time travel	`SELECT * FROM c.s.t VERSION AS OF 3` · `… TIMESTAMP AS OF '2026-06-01'`
Restore	`RESTORE TABLE c.s.t TO VERSION AS OF 3`
View	`CREATE VIEW c.s.v AS SELECT …` · `CREATE OR REPLACE VIEW …` · `DROP VIEW …`
Schema (namespace)	`CREATE SCHEMA IF NOT EXISTS c.s` · `DROP SCHEMA c.s [CASCADE]`

Caveat — a transient first-`CREATE TABLE` report (NOT reproduced)

A tester once reported that the first bare CREATE TABLE … USING DELTA on a just-provisioned DataLake threw ArrayIndexOutOfBoundsException: Index 0 out of bounds for length 0 (a suspected catalog-registration race, not a SQL error). This could NOT be reproduced. On a genuinely freshly-provisioned DataLake + cluster, the very first bare CREATE TABLE succeeded (live-checked 2026-06-12 on a brand-new instance — table created, confirmed via SHOW TABLES; also fine on established instances). So treat it as a possible transient in a narrow post-provision window, not a deterministic behavior. If you ever do hit it, don't hammer the DDL — create the first table via the writer (spark.createDataFrame(rows).write.saveAsTable('c.s.t')) or ingest-then-CTAS (aidp-ingest-file-to-table) to warm the catalog, then bare CREATE TABLE works.

Reliability

Never fabricate table/column names — verify against .aidp/catalog.md or a DESCRIBE/SHOW COLUMNS cell.
On error, read the helper's error field, fix grounded in the catalog, retry once — don't guess repeatedly.
MERGE is the idempotent upsert pattern for re-runnable pipelines (pair with aidp-pipelines).
External/Iceberg/Delta-on-oci:// table reads/writes from other sources → delegate to the …-spark-connectors plugin (aidp-iceberg, aidp-object-storage); this skill is lakehouse-native SQL.

References

scripts/aidp_sql.py — the Spark-SQL executor
aidp-analyzing-data (SELECT) · aidp-table-management (control-plane CRUD) · aidp-cluster-ops (cluster must be RUNNING)
references/payloads.md — persist + confirm before mutating

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