ae-dataops

ae-dataops

スキル間の連携

残作業がこのスキルの範囲外である場合、または別の能力が必要な前提条件がある場合は、連携プロトコルに従ってください。この実行で利用できるスキルから能力に応じて選択し、検証済みのコンテキストを保持して、残りのタスクを続行してください。このプロトコルがすでに読み込まれている場合は、再利用してください。

重要 — このスキルは単独で完結しています。 以下の Global AE CLI Rules を使用してください。DataOps 側のタスクで別の共有スキルを必要としないでください。

まずユーザーが望む結果を確認し、以下から該当するリファレンスだけを読んでください。これらはこのスキル内のファイルであり、個別にインストールされたスキルではありません。正確なフラグは、インストール済みコマンドの --help を使用して確認してください。リファレンスと異なる場合は、別名を推測せず、バージョンの不一致を報告してください。

---

Global AE CLI Rules

DataOps タスクでは ae-cli と以下のリファレンスを使用してください。ワークフロー全体を通じて、明示的に選択されたホストとスペースを維持してください。

グローバルパラメーター：

パラメーター	説明
--format <json|table>	出力形式です。デフォルトは JSON です。
--jq <expr>	ラップする前のコマンドペイロードに対する jq です。.data.flowInstance.status ではなく .flowInstance.status を使用してください。デフォルトの CLI JSON に外部 jq を適用すると .data が含まれます。
--host <url>	アクティブな AE ホストを上書きします。すべてのコマンドで使用でき、サブコマンドの後に指定することもできます。例：ae-cli dataops_ide +<command> --host <url>。

出力とエラー：

• JSON の結果には外側の ok と data が含まれます。コマンドエラーは、標準エラー出力に ok:false と error.type/message/hint を返し、ゼロ以外の終了コードで終了します。両方のストリームを確認してください。
• ok:true は業務上の完了を示すものではありません。 レガシーコマンドは data 内に REJECTED、FAILED、CHECK_FAILED を返すことがあります。続行する前に、リファレンスで説明されている個別の結果フィールドを確認してください。失敗したタスクのステータスを正常に読み取ることと、そのタスクの実行に成功することは別です。
• 非同期処理では、返された ID を保持し、同じ操作を照会してください。送信は完了を意味しません。処理中であることを理由に再送信しないでください。上限を設けたバックオフ付きポーリングを使用します。待機時間の上限に達した場合は、成功したと主張したり作業を再開したりせず、ID と現在の状態を報告してください。
• 実際の _notice.host_compat または明示的なバージョン互換性警告がある場合は、その旨を簡潔に伝え、提示されたアップグレードコマンドを正確に引用してください。無関係な標準エラー出力はバージョン警告ではありません。

プレビューの意味：

• テーブルフィールドの変更とエンティティのリサイクル／削除では、サーバー側の意味的な --dry-run を使用してください。返されたブロッカーと予定されている変更を確認してください。
• それ以外の現在の DataOps --dry-run 実装が表示するのは、ローカルのリクエストのみです。サーバーの権限、接続、SQL、業務状態は検証されません。フローのリリース差分を確認するには +preview_release_flow を使用してください。
• 現在の DataOps コマンドは、グローバルな --validate によるサーバー検証を実装していません。その案内応答を検証成功として扱わないでください。

安全上の制約：

• 必要な ID と参照を確認した後は、読み取りコマンドを直接実行できます。
• 通常の write コマンドは --yes なしで実行します。--yes は、ユーザーの明示的な確認を得た後に限り、high-risk-write コマンドに使用してください。
• すでに提供されている信頼できる ID とコンテキストを再利用してください。それ以外の場合は、該当するリファレンスに従って正確なリソースを特定します。検索条件を絞り込むか、ページネーションを使用してください。省略された一覧から、リソースが存在しないとは証明できません。対象または重大な選択肢が依然として曖昧な場合に限り、確認してください。
• 既存のリソースについて、ID、フィールド、パラメーター値を捏造しないでください。作成時は新しい名前が必要です。依頼された名前を使用するか、名前を提案し、重複がないか確認してください。その名前が存在しないことをブロッカーと誤認しないでください。
• 依頼された結果に達した時点で停止してください。DEV の保存はリリースを許可するものではなく、リリースは手動実行を許可するものではなく、リサイクルは完全削除を許可するものではありません。対応していない、より限定的な依頼を、より広範な操作で代替しないでください。

DataOps のドメイン：dataops_repo、dataops_datatable、dataops_flow、dataops_operations、dataops_ide、dataops_integration

---

Core Concepts and Rules

使用する前に、以下の重要な概念を理解しておく必要があります。理解していない場合、エラーが発生する可能性が非常に高くなります。

Environment and Defaults

シナリオ	デフォルト環境	説明
テーブルの作成／フィールドの編集およびワークフロー定義	DEV	依頼された場合は、別途リリースしてください。
dataops_datatable +entity_recycle / +recycle_bin_delete	既存の DEV および PRODUCT マッピング	エンティティのライフサイクル操作です。リリース待ちの DEV 限定編集ではありません。
フローの手動実行、オペレーション、バックフィル	PROD	対象のフロー／ジョブ／インスタンスを確認してください。
SQL クエリ	SQL で特定されたテーブルによって決まります	サンプルクエリだけを根拠に DEV または PROD を選択しないでください。

責任範囲

操作	適切なツール	禁止事項
SELECT クエリを実行する	dataops_ide	—
テーブル／ビューを作成する、またはテーブルのフィールドを変更する	dataops_datatable	dataops_ide
テーブル／ビューをリサイクルする、または完全に削除する	dataops_datatable +entity_recycle / +recycle_bin_delete	dataops_ide

フローのライフサイクル

Create DEV Flow → Configure Parameters/Tasks/Dependencies/Schedule → Preview and Release to PROD when requested → Manual Execution / Operations Troubleshooting when requested

カスタムフローパラメーター：dataops_flow の +get_flow_params、+create_flow_param、+update_flow_param、+delete_flow_param を使用してください。詳しくはフローのリファレンスを参照してください。書き込み操作では DEV の定義を設定し、DEV のデバッグ実行が停止する場合があります。値、型、名前の変更と削除を PROD に反映するにはリリースが必要です。名前を変更せずに備考を更新した場合は、既存の PROD パラメーターの備考も同期されます。

バックフィルのライフサイクル：対象となる PROD フローを特定する → DRAFT ジョブを作成する、またはすべて更新する → 明示的に実行する → プランを検索／確認する → ジョブ全体を停止または再実行する。削除は対象を確認した後に限ります

---

シナリオ別のルーティング

ユーザーの意図	コマンドグループ	リファレンス	完了条件
スペースを特定または選択する	dataops_repo	スペースの特定	対象の spaceCode を特定し、信頼できるコンテキストを再利用する
テーブル／ビューを作成する、またはフィールドの型／コメントを変更する	dataops_datatable	テーブルのワークフロー	DEV の状態を確認し、要求があった場合に限り公開する
テーブル／ビューを削除する、またはリサイクルビンのエントリを確認／空にする	dataops_datatable	エンティティのライフサイクル	通常の削除はリサイクルまでにとどめます。完全削除には個別の承認が必要です
フローを作成／設定する、タスクやパラメーターを追加／更新／削除する、スケジュールまたはリリースする	dataops_flow	フローの設定	要求された DEV または PROD の定義を読み戻し、手動実行を追加しない
実行を開始、確認、停止する、または失敗した処理をトラブルシューティングする	dataops_flow、dataops_operations	実行とモニタリング	対象のインスタンスを正確に特定する。フロー全体の実行は失敗ノードの再試行ではありません
複数の過去の業務日付分のデータを補完する	dataops_operations	バックフィルジョブ	DRAFT の作成、ジョブの開始、完了済みプランはそれぞれ異なる結果です
データソースを作成／テストする、または同期を設定／実行する	dataops_integration	データ統合	要求に応じて、保存済みの設定または対象の実行を確認する
同期をスケジュールし、今すぐ実行せずに公開する	dataops_integration、dataops_flow	データ統合、続いてフローの設定	PROD のノードとスケジュールを確認し、手動実行しない
スキーマ／テーブルを閲覧する、またはデータに関する質問に回答する	dataops_datatable、dataops_ide	クエリのワークフロー	ダウンロードタスク ID を返すだけでなく、実際の結果を読み取り、質問に回答する

---

1. スペースの特定

dataops_repo が公開する読み取りコマンドは 1 つだけです。spaceCode を必要とする DataOps コマンドを呼び出す前に、これを使って有効な spaceCode を特定してください。戻り値には createTime、spaceCode、spaceDisplayName が含まれます。

• ユーザーが信頼できる spaceCode をすでに指定している場合は、それを再利用してください。
• spaceCode が不明な場合は、最初に +list_spaces を実行してください。
• スペースが 1 つだけ返された場合は、その spaceCode を使用してください。
• 複数のスペースが返され、ユーザーの意図から対象を特定できない場合は、どのスペースを使用するかユーザーに確認してください。推測しないでください。

# List spaces accessible to the current user
ae-cli dataops_repo +list_spaces

---

2. データテーブルとビューの管理

詳細なワークフロー、コマンドフラグ、例、パラメーターに関する注意事項は、references/dataops-table.md をご覧ください。

主な制約：

• 表示可能な DataOps カタログを確認するには、まず dataops_datatable +dict_search_tables を使用します。
• 生のエンジンメタデータの確認に限り dataops_ide +search_tables を使用し、既知のカタログ／スキーマの参照に限り dataops_ide +ide_list_tables を使用します。
• テーブル／ビューは dataops_ide ではなく dataops_datatable で作成します。作成できるのは DEV のみです。公開が求められた場合は +publish_entity を使用します。
• DEV では通常のテーブルフィールドを一度に 1 つずつ追加、変更、または削除します。最初にプレビューし、パーティションフィールドは変更せず、PROD への公開は別途行います。
• 通常の「テーブル／ビューを削除してほしい」という依頼では、dataops_datatable +entity_recycle を使ったリサイクルのみを行います。完全削除は別のワークフローで、+recycle_bin_list と +recycle_bin_delete を使用します。どちらのワークフローを実行する場合も、事前にテーブルのリファレンスを読みます。どちらの書き込みも DEV と PRODUCT に影響し、正確なエンティティ ID と名前、意味を確認できる --dry-run、および --yes の前の明示的な確認が必要です。RECYCLE_NAME_CONFLICT を回避するために、同じ名前の古いリサイクル済みエンティティを自動的に削除してはいけません。
• 実際のリサイクルが確認された後、エージェントはエンティティを完全削除するか尋ねてもかまいません。その場合、取り消しできず、内部テーブルデータが削除される可能性があることを警告します。新たな明示的確認が得られるまで停止します。これはエージェントの返信であり、CLI プロンプトや JSON フィールドではありません。プレビュー、FAILED、PARTIAL、または未検証の状態では、この提案をしてはいけません。まず同じエンティティ ID の状態を照合します。
• DDL は Trino の構文に従います。現在のスペースのビュー DDL では、リテラルの ${env} プレースホルダーをそのまま保持してください。

---

3. フローのオーケストレーション

フローのリファレンスでは、作成と設定、実行と監視、バックフィルジョブを扱います。

ライフサイクル：DEV での設定 → 要求されたリリース → 要求された実行またはトラブルシューティング。ユーザーの指定した範囲を超えて進めないでください。

作成／設定コマンドの詳細は、references/dataops-flow-create.md をご覧ください。実行、監視、操作インスタンス、タスクログ、停止コマンドの詳細は、references/dataops-flow-monitor.md をご覧ください。複数の日付にわたる永続的なバックフィルジョブについては、references/dataops-backfill.md をご覧ください。

主な制約：

• タスクは DEV で作成および更新し、PROD で実行する前にプレビュー／リリースします。
• カスタム flowParams と各タスクの dag.tasks[].taskParams には +get_flow_overview を使用します。DEV がデフォルトで、PROD もサポートされています。どちらの場合も dwWorkflowEdit が必要です。定義では式のテキストと、コードから解析された参照が保持されます。参照元／値のフィールドは null または省略されている場合があります。
• インスタンスの詳細を確認するには dwOMInstanceView が必要です。過去の値は、flowInstance.instanceParamMap または --includeLog true を指定した場合のタスクの log.params で確認します。
• +delete_task は高リスク操作として扱います。+get_flow_overview で対象を確認し、--dry-run でプレビューしてから、ユーザーの明示的な確認を得た場合に限り --yes を使用します。削除は DEV に影響します。PROD に反映するにはフローをリリースします。
• +execute_flow は常に PROD で実行されます。早期停止に使う executeId が返されます。
• 安定した確認とトラブルシューティングには、オペレーション検索で取得した flowInstanceId を優先します。
• バックフィルジョブは複数の基準日をまとめて処理する永続的なジョブです。+execute_flow のループで代用してはいけません。
• +create_backfill_job でドラフトを作成し、別の手順として実行します。+rerun_backfill_job は失敗したプランだけでなく、ジョブ全体を再実行します。
• +update_backfill_job は DRAFT ジョブの設定全体を置き換えます。まずジョブを確認し、部分的なパッチとして扱ってはいけません。+delete_backfill_job は高リスク操作として扱い、確認の前に --dry-run でプレビューします。
• タスク SQL でフローまたはワークスペースのパラメーターを参照する場合は ${paramKey} を使用します。リリース前に、概要でパラメーターの取得元を確認してください。

4. IDE SQL クエリ

詳細なメタデータの参照、SQL クエリ、非同期ダウンロード、キャンセルのワークフローについては、references/dataops-query.md を参照してください。

主な制約：

• IDE はクエリ専用です。テーブルの作成・変更や、エンティティのリサイクル・削除には dataops_datatable を使用してください。
• 生のエンジンメタデータやスキーマの参照が必要な場合を除き、テーブルの検索には dataops_datatable +dict_search_tables を優先してください。
• 読み取り専用の SQL クエリをちょうど 1 つ送信してください。クエリによってプラットフォームの上限が適用されるダウンロードタスクが作成されます。行はインラインで返されず、結果は無制限のエクスポートでも全件エクスポートでもありません。

---

5. データ統合

データソース、メタデータの参照、同期ソリューション、実行、監視の詳細なワークフローについては、references/dataops-integration.md を参照してください。

主な制約：

• sourceConfig、sinkConfig、channelConfig、fieldsMapping は参照テンプレートから生成してください。キーを独自に作成しないでください。
• MySQL Source の読み取りパーティショニングには sourceConfig.splitColumn を使用します。fieldsMapping.shardingKey は列メタデータであり、読み取りパーティショニングには使用しないでください。
• +save_sync_solution は部分パッチではありません。現在の +get_sync_detail --withParams true が返すのは、概要と使用済みパラメーターであり、編集可能な設定一式ではありません。不足している設定をそこから再構築しないでください。更新時の制約については、統合リファレンスを参照してください。syncName は互換性のために受け付けられますが、無視されます。
• プリセットのリポジトリ同期では te_etl@TASK_ENGINE_TRINO を使用します。サーバーは選択したスペースに基づいてゲートウェイのルーティングを設定します。サンプルの会社 ID やスペース ID を設定にコピーしないでください。
• 実行中の同期を停止する前に、+list_sync_runs を使用して taskId を取得してください。

---

リファレンスドキュメント

コマンドのフラグと使用方法の詳細については、references/ ディレクトリ内のコマンドドキュメントを参照してください。