carto-create-workflow

carto-create-workflow

CARTO Workflows は、データウェアハウスの SQL にコンパイルされる、ビジュアルな DAG 作成アプリです。各ワークフローは接続されたデータウェアハウス内で実行され、実行時に CARTO のコンピューティングリソースは使用されません。このスキルでは、DAG の構築（このファイルの大部分）、CLI による操作（CRUD、スケジュール）、プロファイル間コピー（dev → prod の昇格、carto workflows copy による顧客ごとに分離されたワークスペース）まで、ライフサイクル全体を扱います。詳しくは以下のリファレンスをご覧ください。

Workflows と Builder — 別々のアプリです。 このスキルの対象は Workflows（CARTO の DAG／オーケストレーションアプリ。URL は /workflows/<id>）です。Builder は別のマップ作成アプリ（/builder/<id>）です。このスキルで「Workflows のキャンバス」「Workflows 内」「DAG ビュー」と表現しているものは、Builder を指すことはありません。これらは組織と接続を共有するだけで、それ以外は異なる製品です。ワークフローの出力（ジオメトリを含む結果テーブル）は通常、その後 Builder で可視化します。この点のみが、2 つのアプリの接点です。

単発のアドホックな SQL には、carto-query-datawarehouse を使用してください。ワークフローは、繰り返し実行するスケジュール済みの複数ステップ DAG 向けです。

アクセス経路の振り分け。 対話的なライフサイクルは、OAuth 認証済み MCP セッション上の MCP ツールに対応しています。create_workflow、update_workflow（method=update|share|unshare|publish|unpublish）、validate_workflow（method=validate|verify|to_sql）、read_workflows（method=list|get|list_mcp_tools|get_mcp_tool）、run_workflow（method=run|status|results）、schedule_workflow（method=add|update|remove）、および read_workflow_components（method=list|get — コンポーネントカタログ）です。以下のフェーズは、どちらの経路でも適用されます。手順に carto workflows コマンドが記載されている場合は、対応する MCP ツールに置き換えてください（例：verify-remote → validate_workflow method=verify）。スクリプト作成／CI、バンドルスキーマのイントロスペクション（carto workflows schema — MCP に同等の機能はありません）、プロファイル間コピー（carto workflows copy — CLI 専用）、使用状況ログの監査（carto activity query — CLI 専用）には、CLI を使用してください。サーバーが接続されていない場合、または MCP セッションが token 認証の場合は CLI に切り替えてください。この場合、作成／管理ツールは非表示になり、run_workflow と validate_workflow のみが使用できます。判定の手掛かりについては、carto-basics/references/access-paths.md を参照してください。

バンドル構造、コンポーネントスキーマ、入力形式、注意点はすべて、CLI（carto workflows schema／components）、または MCP 経路では read_workflow_components（method=list|get）を通じてライブで提供されます。決してハードコードしたり、推測したりしないでください。 ライブイントロスペクションが信頼できる唯一の情報源です。

ライブイントロスペクションは、リファレンスファイルを参照する前に使用してください。MCP では read_workflow_components（method=list|get）でコンポーネントの情報を確認できます。バンドル／DAG の schema セクションは CLI 専用です。

コマンド	提供される内容
carto workflows schema	すべてのバンドル／DAG スキーマセクションのインデックス
carto workflows schema bundle	最上位のバンドル構造（id、title、connectionId、config、privacy、tags）。privacy は $ref です。構造を取得するには carto workflows schema privacy を実行してください。有効な最小形式は "privacy": { "privacy": "private" } です（内側の文字列は単なる "private" ではありません。内側のフィールドで許可されている値は enums に記載されています）。
carto workflows schema config	DAG 設定全体（schemaVersion、connectionProvider enum、nodes、edges、variables、viewport、useCache、executionSettings、schedule）
carto workflows schema node[.source|.customsql]	汎用ノードの構造（data.version、data.title と data.label の違い）。.source は data.id == data.inputs[0].value の不変条件を追加し、.customsql は customsql の仕様全体を追加します
carto workflows schema customsql	コピーして使用できる customsql ノードのテンプレート（version: "2.0.0" を含む）
carto workflows schema edge / schema handles	エッジの構造と、エッジハンドルの命名リファレンス（ノードタイプ、演算子、コンポーネント別の sourceHandle／targetHandle。有効なエッジに不可欠です）
carto workflows schema variable	変数（パラメーター）の構造 — { order, name, type, value, public }
carto workflows schema schedule / schema enums	宣言型のスケジュールメタデータと、有効な enum（ノードタイプ、プロバイダー、プライバシー、スケジュール頻度）
carto workflows components list | get <names> --connection <conn> --json	コンポーネントカタログ。コンポーネントごとの inputs、outputs、notes が含まれます。get に --input-formats を追加すると、入力タイプの format、examples、pitfalls を取得できます。MCP：read_workflow_components。
carto workflows --help	エンジン別のスケジュール式の構文を含む、コマンドの全リファレンス

参照資料（ライブイントロスペクションで取得できない情報に限る）：

• references/canvas-notes.md — type: "note" ノードを使ったキャンバスのドキュメント化。ノードを囲むセクションコンテナーも含みます。ライブイントロスペクションではノートのスキーマを取得できません。また、表示されるカードのサイズは data.width／data.height です（ノードレベルの幅／高さは data + 160／+ 128 です）。これを逆にすると、すべてのカードが小さく表示されます。
• references/providers/ — ウェアハウス別の詳細情報（BigQuery、Snowflake、Databricks）：識別子の引用符、列の大文字・小文字、AT パス。
• references/scheduling.md — add と update のセマンティクス、バンドルレベルのスケジュールに関する警告、アクティビティログによる確認。
• references/mcp-and-api-publish.md — ワークフローを MCP ツールまたは呼び出し可能な API エンドポイントとして公開する方法（MCP：update_workflow method=publish）：バンドルの要件（native.mcptooloutput + スコープ付き変数 + 下書きの説明）、{{@var}} と @var の置換構文、Number → FLOAT64 の LIMIT に関する注意点、公開後の確認。
• references/cross-profile-copy.md — workflows copy の仕組み（CLI のみ）、接続のマッピング、--skip-source-validation、コピーが常に新しいワークフローになる理由。
• references/schedule-readd.md — workflows copy ではスケジュールは引き継がれません。再追加の方法（コピー元とコピー先のエンジンが異なる場合の構文変換を含む）。

connectionProvider は接続と一致している必要があります。 config.connectionProvider（schema enums の enum）は、接続の実際のプロバイダーと一致している必要があります。一致しない場合、誤った SQL 方言が生成され、実行時にエラーが発生します。carto connections list --search <name> --json（CLI）または MCP 経由の explore_data（method=list_connections|get_connection）で確認してください。

---

開発プロセス

すべてのワークフローのリクエストで、この6つのフェーズを順番に実行してください。 省略したり、順序を入れ替えたりしないでください。

フェーズ 1 — 情報を収集する

1. データソースを特定します。 ユーザーがテーブルを指定している場合は、それを書き留めます。指定がない場合は、利用可能なものを確認します。CLI carto connections list / carto connections describe <connection> "<fqn>"、または MCP explore_data（method=list_connections|list_resources|describe）を使用します。

2. 目的を明確にします。 どのような変換を行いますか？ 出力は何ですか？ フィルターや条件はありますか？

3. 接続を特定し、その provider（bigquery / snowflake / databricks）を書き留めます。 次の手順で必要になります。CLI carto connections list、または MCP explore_data method=list_connections を使用します。

4. プロバイダーのリファレンスを読みます。

   いずれかのノードを作成する前に、必ず `references/providers/.md`（例：`references/providers/bigquery.md`）を開いて、最後まで読む必要があります。これは必須です。

   このファイルには、識別子の引用符付けルール、列の大文字・小文字の扱い、Analytics Toolbox のパス、スケジュール式の構文、および customsql の $a/$b プレースホルダー要件が記載されています。これらは validate では検出できません。後になって verify-remote の失敗や実行時の SQL エラーとして表面化し、手戻りの最も一般的な原因になります。

   次のフェーズが具体的に見えるからといって、この手順を省略しないでください。前回の実行時の記憶に頼らないでください。プロバイダーファイルは変更されることがあります。

5. コンポーネントカタログを取得します — carto workflows components list --connection <connection> --json（CLI）または read_workflow_components method=list（MCP）を使用します。コンポーネント名の唯一の信頼できる情報源です。

フェーズ 2 — アプローチを設計する

1. 取得したカタログからコンポーネントを選択します。
2. 使用するすべてのコンポーネントのスキーマを取得します。CLI carto workflows components get <name1>,<name2> --connection <connection> --json（または MCP read_workflow_components method=get）を実行すると、inputs、outputs、notes が返されます。notes 配列には注意事項が含まれているため、よく読んでください。
3. 入力形式を取得します。 CLI carto workflows components get <component1>,<component2> --connection <connection> --input-formats --json を実行すると、各入出力タイプの format、examples、pitfalls が返されます。入力タイプ名ではなく、コンポーネント名（例：native.buffer）を指定します。
4. 設計原則：
   • 識別子列と空間列を全工程で保持します。
   • native.customsql よりネイティブコンポーネントを優先します。これは単なる推奨ではありません。 ネイティブ優先ルールを参照してください。
   • H3/Quadbin 列は、ジオメトリを抽出しなくても可視化に使用できます。
   • 可視化には標準名 geom、h3、quadbin を使用します。

フェーズ 3 — 計画を提示し、不足事項を明らかにして確認する

ワークフローの計画（コンポーネント、データフロー、判断事項）を提示します。その後、構築を始める前に、不足している項目をすべて明示的に列挙します。

• 未確定のパラメーター — しきい値、半径、フィルター値、時間範囲、k-NN の k、集計列、出力テーブル名など。
• ユーザーに委ねられる分析上の判断 — 有意水準、距離指標、結合タイプ、NULL の処理、重複排除キー、CRS、H3/quadbin の解像度。
• 依頼内容の曖昧さ — 意図を推測する必要があった箇所。

不足している項目ごとに、妥当なデフォルト値とその根拠を提示し（例：「p 値のしきい値：慣例的な有意水準である 0.05 を提案します」、「バッファー距離：入力の街区スケールに合う 1000m を提案します」）、ユーザーに確認または変更を依頼します。ユーザー向けの分析パラメーターを、ユーザーに知らせずに決めてはいけません。構築を始める前に、必ず確認を待ってください。

フェーズ 4 — ワークフローを構築する

1. ワークフローファイルを作成します。carto workflows schema [section] からバンドル／ノード／エッジ／変数の構造を取得します（bundle から始め、次に node、node.source、node.customsql、edge、handles の順に確認します）。customsql ノードには、carto workflows schema customsql のテンプレートをコピーして使用します。 最上位に任意の privacy を設定する場合、文字列ではなくオブジェクトにする必要があります。"privacy": { "privacy": "private" } のようにします（フィールド名を入れ子にします）。不要であればフィールド全体を省略してください。"privacy": "private" は validate で失敗します。

   ソースノード（type: "source"）— ReadTable は他のコンポーネントと同様に扱います。carto workflows components get ReadTable --connection <conn> --json で仕様を取得し、正規の inputs[*].title と inputs[*].description を確認してください。（ReadTable は __internal グループに属するため components list には表示されませんが、get では通常どおり取得できます。）get では確認できない、schema node.source にあるソース専用のルールが2つあります。

   • キャンバス上の表示名は data.title ではなく data.label に設定します。汎用ノードでは title、ソースノードでは label を使います。
   • data.id と data.inputs[0].value は同じ FQN でなければなりません。

   キャンバスのレイアウトと命名 — すべてのノード、すべてのワークフローに適用してください。 これらは実行には影響しませんが、ユーザーは Workflows で DAG を開くため、雑なキャンバスは品質の低さにつながります。数値は小さく、安定しています。必ず適用してください。

   • スナップグリッドは16 pxです。 すべての x と y は % 16 == 0 にする必要があります。グリッドから外れた値は、ユーザーが動かした他の要素の横で微妙にずれて見えます。
   • ノードタイプごとのカード幅： ソースノードは 192 px（12セル）、汎用コンポーネントは 64 px（4セル）です。高さは固定です： すべてのカードは高さ 80 px（5セル）で、その下に 16 px のラベルが表示されます（ラベルはカード内ではなく、次のカードまでの間隔に配置されます）。
   • カード間の標準間隔（右端 → 次の左端）： 直線的な配置では80 px（5セル）、ファンイン（別の行からのエッジを収める必要がある結合の左入力）では128 px（8セル）です。一定なのは間隔で、左端同士の Δx はカード幅によって異なります。汎用→汎用の直線配置 = Δx 144（9セル）、ソース→汎用 = Δx 272（17セル）、汎用→汎用のファンイン = Δx 192（12セル）です。
   • 垂直方向の標準間隔（カード本体の下端 → 次のカード本体の上端）： 80 px（5セル）＝ラベル16 px ＋余白64 pxです。縦に積み重ねる場合、上端から上端までの Δy = 160 px（10セル）です。
   • レイアウト。 ソースノードは最も左の列に、同じ x で縦に並べ、Δy = 144 px（9セル）にします。メインパイプラインはソース行の中央の高さに配置します（ソースが y=80 と y=224 の場合、パイプラインは y=160）。これにより、結合ノードに両方の入力が対称に届きます。
   • data.title と data.label は別のフィールドです — 同じ値を重複して設定しないでください。title は、このノードが行う処理を表す短いインスタンス固有の動詞（15文字以内）にします（"Rank"、"Join to score"、"To H3" など）。label は、新規にドロップしたときのコンポーネントの正規の型名にします（"Join"、"Create Column" など）。components get <name> --json の components[0].title を確認してください。ソースノードでは data.label のみが表示されるため、テーブルの短い別名（"Candidates"、"Score grid C" など）を設定します。

2. ファイルを書き込むたびに validate を実行します。オフラインで高速に実行でき、構造上のエラーをすぐに検出できます — CLI では carto workflows validate workflow.json --json、MCP では validate_workflow method=validate を使います。

   carto workflows validate workflow.json --json
   

   validate に合格していない保存は、すべて不備があるものとして扱ってください。次のノードやエッジに進む前に修正します。

   validate が最終的な判断基準です。 components get で取得したコンポーネントスキーマと、validate が受け入れる内容が異なる場合は、validate に従い、バンドルを調整してください。すでに検証に合格しているバンドルを、スキーマに合わせるために「修正」してはいけません。

3. 分岐の境界で verify を実行します。保存のたびに実行する必要はありません。ウェアハウスにアクセスするため（時間がかかり、認証も必要です）、構造の検証に合格したサブDAG全体に対して一度、さらに提示前の最後に一度だけ実行します — CLI では verify-remote、MCP では validate_workflow method=verify を使います。

   carto workflows verify-remote workflow.json --connection <connection-name> --json
   

   verify は、列の型の不一致、テーブルの不足、AT の解決など、validate では確認できない問題を検出します。 レスポンスの読み方。 まず deep.errors を確認してください。ここに何かあれば、実行を妨げます。deep.warnings はより詳細な情報を示します。COMPONENT_INVALID 項目は実行時の懸念事項（エンジンが認識しないオプション、失敗する可能性がある列参照など）を示します。SCHEMA_TRACE_SKIPPED と VERIFY_SKIPPED は診断情報です（このノードで静的チェッカーが処理を見送ったのであって、壊れているという意味ではありません）。トップレベルの valid はエラーと警告を集約するため、ワークフローのアップロードが成功していても false になることがあります（deep.errors が空で deep.valid: true の場合）。アップロードの判断には deep.errors が空であることを基準にし、トップレベルの valid: false は「詳しく確認する必要はありますが、問題を妨げるものではない可能性が高い」と捉えてください。

4. エラーはユーザーに実装の詳細を見せずに修正してください。

5. 完了するまで繰り返し、validate と最後の verify の両方で問題がない状態にしてください。

フェーズ 5 — 結果の提示

作成した内容を要約してください。検証が成功したことを確認してください。ユーザーの確認を待ってください。

フェーズ 6 — CARTO へのアップロード

1. アップロードするかどうかをユーザーに尋ねてください。
2. アップロードして URL を提示します。CLI の carto workflows create、または MCP の create_workflow を使用してください。

   carto workflows create --file workflow.json --verify
   

   接続情報はバンドル内の connectionId から取得するため、ここでは --connection フラグを指定しません。
3. アップロード時に入力が暗黙に削除されていないことを確認してください。 作成直後に、保存されたワークフロー（carto workflows get <id> --json または read_workflows method=get）を読み込み、config.nodes[*].data.inputs をアップロードしたバンドルと比較してください。入力の検証に失敗すると、エンジンは保存時に値を暗黙に拒否します（最もよくあるのは、Selection 入力にワイヤー値ではなく表示ラベルを渡した場合です。「コンポーネントと入力情報の取得」の「表示ラベルとワイヤー値」を参照してください）。この場合、validate、verify（deep.valid: true で deep.warnings のみの場合）、および create はすべて成功を報告しますが、Workflows を初めて開くと、ノードに赤いエラーインジケーターが表示されます。ローカルでは存在してサーバー上では欠落している value があれば、暗黙に拒否されています。元のバンドルを修正して再アップロードしてください（サーバー上で編集しようとしないでください）。
4. 明示的に要求されない限り、自動実行しないでください。

---

ネイティブ優先のルール

native.customsql は最初に使うものではなく、最後の手段です。カスタムSQLノードを書く前に、まずネイティブの組み合わせを試してください。次のいずれかに当てはまる場合に限り、カスタムSQLに切り替えてください。

• 同じロジックを表現するのに、ネイティブの組み合わせでは 約4～5個を超えるノードが必要になる。
• 特定の操作に ネイティブ相当のものがまったくない（carto workflows components list で確認済み）。
• 式でウェアハウスの生SQLが本当に必要になる（例：ST_UNION_AGG、LOGICAL_OR、ML.PREDICT、直近N件のウィンドウ処理）。

よく使う操作と対応するネイティブ機能です。まずはこちらを試してください。

次のようなSQLを書く場合…	ネイティブ機能を使う
WHERE x = … ／複数条件のフィルター	native.where（述語）、native.wheresimplified（フォーム形式のフィルターUI）、native.spatialfilter（ジオメトリに基づく一致／不一致の振り分け）、native.select（列の射影）
SELECT a, b, c FROM t（複数列の射影／名前変更／複数の式）	native.select（自由形式のSELECT本体を1つのノードで指定）
SELECT ..., expr AS c FROM t（計算列を 1つ追加）	native.selectexpression（1ノードにつき1列と1式）
GROUP BY k, SUM(x), AVG(y), COUNT(*)（キーが1つ）	native.groupby — groupby の入力は単一の Column で、複数列には対応していません。キーが複数の場合は native.customsql を使ってください。
JOIN ... ON a.k = b.k（結合の種類を問わず）	native.joinv2
JOIN ... ON ST_INTERSECTS / ST_CONTAINS / ST_WITHIN	native.spatialjoin
2つのテーブル間の MIN(ST_DISTANCE(a.geom, b.geom))	native.distance（メインテーブルをその場で拡張し、nearest_id と nearest_distance を追加します。2つの参照テーブルに対して native.distance ノードを2つ連結する場合は、参照元ごとにこれらの名前を変更してください）
ST_BUFFER(geom, d)	native.buffer
H3ビニング／境界／中心／ポリフィル	native.h3frompoint、native.h3boundary（出力ジオメトリ列の名前は <h3col>_geo です。例：index_geo — geom ではありません）、native.h3center、native.h3polyfill
ORDER BY ... LIMIT n	native.orderby + native.limit
Zスコア／標準化	native.normalize
重み付き複合スコア	native.spatialcompositeunsupervised（重み付け／PCA）、native.spatialcompositesupervised（ターゲット駆動）
Getis-Ord Gi*、GWR、等値線	native.getisord、native.gwr、native.isolines
最終ノードをテーブルに保存	native.saveastable

カスタムSQLに切り替えるのが早すぎる兆候です。いったん止めて、代わりにネイティブの組み合わせを探してください。

• カスタムSQLが単なる WHERE 句、単一の JOIN、集計が1つか2つの GROUP BY、または列の射影にすぎない。
• 専用のネイティブ機能があるウェアハウス関数（ST_BUFFER、H3_FROMGEOGPOINT など）を1つだけラップしている。
• 目的が列の射影／名前変更／型の再キャストだけである — 複数列の場合は native.select（自由形式のSELECT本体、1ノード）を使ってください。native.selectexpression は計算列を1つ追加する場合に使います。
• カスタムSQLの出力を、さらにカスタムSQLノードへ連結している — 代わりにネイティブ機能を連結してください。

カスタムSQLが本当に適切な場合、ウェアハウスごとのSQL方言に関する注意点は、対応する references/providers/*.md に記載されています（BigQueryのバッククォート、Snowflakeの大文字・小文字、Databricksの識別子）。

カスタムSQLのスキーマトレースの連鎖 — 誤解を招く「Table X used but not provided」エラー。 sourcea ／ sourceb が明らかに接続されているカスタムSQLノードに対して、verify-remote が Table "X" used in statement but not provided を報告する場合、根本原因はほとんどの場合、上流ノードでスキーマトレースに失敗していることです。上流ノードの警告レベルの COMPONENT_INVALID でさえ、連鎖を壊し、下流のカスタムSQLにエラーを表面化させるのに十分です。まず上流ノードを修正してください。そうすれば下流のエラーは解消されます。上流が正常になるまでは、SQLを書き直したり、バッククォートを入れ替えたり、エイリアスを試したりするのに 時間を費やさないでください。

---

コンポーネントと入力情報の取得

記憶しているコンポーネントスキーマや入力形式に頼らないでください。 必ず最新情報を取得してください — carto workflows components list | get <names> [--input-formats] --connection <conn> --json（CLI）、または MCP 経由で read_workflow_components（method=list|get）を使用します（上記のイントロスペクション表を参照）。

レスポンスで確認する項目：

• コンポーネントの notes — 注意すべき点を示す文字列：自明でない動作、非推奨の状態、出力列の命名。
• 入力の format — 想定される値の形式を説明する文章。
• 入力の examples — 正しい使用方法を示す具体的な JSON スニペット。
• 入力の pitfalls — よくある間違い、評価順序、形式に関する注意点。
• コンポーネントの version — 作成するノードの data.version（文字列）にそのままコピーします。これがない汎用ノードは Workflows で OUTDATED として扱われます。
• 入力の options（Selection / Enum） — エンジンは値を完全一致で照合します。各オプション文字列をそのままコピーしてください — 大文字・小文字を保持し、言い換えたり Title Case に変換したりしないでください（例：spatialjoin の jointype が受け付けるのは "inner" であり、"Inner" ではありません）。
• 表示ラベルとワイヤー値。 コンポーネントによっては（例：native.isolines.mode）、人が読むためのラベルを別の optionsText フィールドに持っており、components get --json では、その表示ラベルが options キーの下に表示される場合があります。verify-remote が「そのままコピーした」値を拒否し、Valid options: <list> に大文字・小文字が逆の値を表示した場合、CLI が表示ラベルを返したことになります。既知の正常なワークフローを carto workflows get <id> --json で参照し、実際のワイヤー値を確認してください。小文字または snake_case 形式（walk、public_transport）は v2 コンポーネントで一般的です。
• verify-remote は複数のコンポーネントバージョンを同時に実行する場合があります。 同じ入力について、エラーと警告に矛盾する「有効なオプション」（例：一方は "Walk"、もう一方は "walk" を受け付ける）が表示される場合、エンジンはノードに対して v1 と v2 の両方のバリデーターを実行した可能性があります。components get からコピーしたバージョンを信頼し、単一ノードのテストワークフローをアップロードして確認してください。

コンポーネントのバージョン、バンドル／設定のデフォルト、列挙型オプションの一覧など、時間の経過とともに変わる可能性がある値については、CLI の components get／schema 出力を唯一の信頼できる情報源として扱ってください。独自のテンプレートに値をハードコードしないでください。特に：

• config.schemaVersion — 現在のデフォルト値は carto workflows schema config --json → properties.schemaVersion.default から取得してください。現在は "1.0.0"（文字列）ですが、今後の更新でスキルの更新が不要になるよう、作成時に値を解決してください。

---

プロバイダー固有の注意事項

データウェアハウスごとに SQL の方言、テーブルの命名規則、列名の大文字・小文字の規則が異なります — 必ず該当するプロバイダーガイド（bigquery、snowflake、databricks）を確認してください。入力型の形式（Table、Column、ColumnsForJoin、SelectColumnAggregation など）と、コンポーネントごとの注意点（「AT コンポーネントには validate ではなく verify が必要」という規則を含む）は、ライブイントロスペクションから取得します — コンポーネントと入力情報の取得を参照してください。

---

ワークフローの運用（構築後）

CARTO にワークフローが作成されると、どちらの方法でも CRUD、実行、スケジュール管理を利用できます。MCP：read_workflows（list|get）、update_workflow（update|share|unshare|publish|unpublish）、run_workflow（run|status|results）、schedule_workflow（add|update|remove）、delete kind=workflow。CLI クイックリファレンス：

carto workflows list --json                                   # list / inspect
carto workflows get <id>
carto workflows update <id> --file workflow.json              # update (replaces whole DAG)
carto workflows schedule add <id> --expression "every day 08:00"
carto workflows schedule remove <id>

常に適用されるガイダンス：

• ワークフローは接続先のデータウェアハウスで実行されます。 BigQuery 接続を使用するワークフローでは、Snowflake 固有の SQL は使用できません。
• スケジュール式の構文はエンジンによって異なります — BQ／CARTO DW では自然言語（"every day 08:00"）、Snowflake／Postgres では cron（"0 8 * * *"）、Databricks では Quartz cron（"0 0 8 * * ?"）を使用します。references/scheduling.md を参照してください。誤った構文を選ぶと、スケジュールの追加時に失敗します。
• プロファイル間でのワークフローのコピー（dev → prod、顧客ごとに分離されたワークスペース）は CLI でのみ行えます — references/cross-profile-copy.md を参照してください。スケジュールは引き継がれません — references/schedule-readd.md を参照してください。
• ワークフローを削除しても、その出力は削除されません。 ワークフローがデータウェアハウスに作成したテーブル／ビューは残ります。必要に応じて carto sql job（または MCP の execute_query）で削除してください。
• update は DAG 全体を置き換えます。 ノード単位のパッチ機能はありません。必ず先に get し、編集してから update してください。
• ワークフローの実行ステータスはアクティビティログに記録されます（イベントタイプは WorkflowRun、WorkflowExecutionComplete）。スケジュールされたワークフローの稼働状態を監視するには、carto-query-datawarehouse 経由でこのログをクエリしてください — そのスキルの references/activity-queries.md を参照してください。