> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core.sprocket.bz/llms.txt
> Use this file to discover all available pages before exploring further.

# 自動処理（ワークフロー）：実行タイミングと変数

> ワークフローの実行順序、トリガー（手動・スケジュール・アセット）、取りこぼしの追い実行、実行時変数の設定方法を説明します。

> この記事は Spumote のソースコードから生成した試験出力です。内容は確認中のため、正式な仕様は担当者に確認してください。

## この機能でできること

ワークフローを「いつ」「どの順番で」「どんな値で」動かすかを決める設定です。

* ステップ同士の依存関係（前後関係）で、実行の順番を決める
* トリガー（起動のきっかけ）を、手動・スケジュール・アセット（データの到着）から選ぶ
* 停止中などで実行されなかった回を、後からまとめて追い実行する
* 日付などの「実行時変数」を使い、毎回変わる値（対象日など）を SQL やパスに差し込む

## 画面の場所

データ › 自動処理（ワークフロー）› 処理一覧 › （ワークフローを開く）› 設定

「設定」画面には「モード」「トリガー」「変数」「実行制御」の 4 つのタブがあります。トリガー・変数・実行制御は「下書き保存」で保存され、公開すると実行に反映されます。

## 依存関係とつなぎ方

* キャンバス上でステップを線でつなぐと、その順番で実行されます。線の上の ⊕ に新しいステップを落とすと間に挟まり、末端の ⊕ に落とすと後ろに続きます。
* ステップ設定の「前後関係」›「依存ステップ」で、そのステップより前のステップから「完了を待つステップ」を複数選べます。選んだステップがすべて完了してから実行されます。未選択の場合は直前のステップに依存します。
* 条件分岐ステップを使うと、結果によって進む先を変えられます（「02-3-2 ステップの種類」参照）。

## トリガー

「設定」›「トリガー」でトリガーを追加します。1 つのワークフローに複数のトリガーを持てます。

| タイプ（画面表示） | 起動のきっかけ |
| - | - |
| 手動 | 「今すぐ実行」などで人が起動 |
| スケジュール | 決めた日時・間隔で自動起動（cron） |
| Asset | 必要なアセット（データ）がすべて揃ったら自動起動 |

共通の設定は「トリガー名」「タイプ」「有効」と、使う「変数セット」です。トリガーの「有効」のチェックも、トリガーの「保存」のあと「下書き保存」で保存され、公開すると実行に反映されます。

### スケジュール

スケジュールは「インターバル（一定間隔）」か「定時実行（毎日 / 毎週 / 毎月の時刻）」で選べ、「詳細設定（cron式）」で直接書くこともできます。次回実行日時も確認できます。

**取りこぼし分の追い実行（Catchup）**

「Catchup（追いつき実行）」にチェックを入れると、停止や遅延で実行されなかった回を、次の評価時に古い順にまとめて実行します。

| 項目 | 内容 |
| - | - |
| 1 回の評価で実行する最大回数 | 1〜100（既定 24）。超えた古い分はバックフィルで埋めます |
| パーティション変数名（任意） | 各回に「いつの分として実行するか」の時刻を渡す変数名（例: BATCH\_HOUR） |
| 値フォーマット（JST） | 渡す時刻の書式（既定 \{YYYY}-\{MM}-\{DD}T\{HH}:\{mm}） |

パーティション変数名は Catchup を使わない通常のスケジュール実行でも渡されます。

### アセット駆動（Asset トリガー）

「アセット」は、ワークフローの出力や外部から届いたデータ（BigQuery テーブル・ファイルなど）に付けた名前です。Asset トリガーは、上流のワークフローやデータ到着チェック（センサー）がアセットを「できた」と記録したタイミングで起動します。

1. タイプで「Asset」を選びます。
2. 「Asset Explorer」で起動条件に使うアセットにチェックを入れるか、「必要なアセット」で「アセットを追加」し、アセットキーを検索・入力します（新しいキーも直接入力可）。
3. アセットごとに「待機条件」を選びます。

| 待機条件 | 意味 |
| - | - |
| 同じ partition を待つ | 全アセットで同じ区切り（例: 同じ日付）が揃ったら起動 |
| 最新到着でよい | 直近に届いていれば区切りを問わず起動 |

4. 「partition を渡す変数」を指定すると、届いたデータの区切り（日付など）が変数としてワークフローに渡ります。「partition key から派生変数を作る」で、区切りを分解して日付・時刻などの追加変数（最大 4 件）も作れます。サンプルを入れてプレビューできます。

エディタ上部の「起動条件の充足状況」で、直近の区切りごとに必要なアセットが揃っているかを確認できます。

## 実行時変数

SQL・パス・テーブル名などに `${変数名}` と書いておくと、実行時に値が差し込まれます。値の決め方は 3 種類あります。

| 種類 | 設定場所 | 用途 |
| - | - | - |
| 変数セット | 設定 › 変数 › 変数セット | 「本番用」「テスト用」など、名前付きの値の組。既定のセットを選べます |
| 実行時変数（テンプレート） | 設定 › 変数 › 実行時変数 | 実行するたびに日付を自動計算（例: JST の 3 日前） |
| 実行時に指定する変数 | 「変数を指定して実行」、バックフィル、トリガー | その実行だけの上書き |

**優先順位**: 変数セット ＜ 実行時変数 ＜ トリガーで明示した変数（後ろほど優先）。バックフィルで渡す区切り値は明示扱いで最優先です。

実行時変数は実行開始時に 1 回だけ計算され、全ステップが同じ値を使います。入力欄の下に「いまトリガーすると: 2026-…」のプレビューが表示されます。

## 活用例

* **前日分の売上集計**: 実行時変数で BATCH\_DATE = JST の前日 を定義し、SQL の WHERE に `${BATCH_DATE}` を使う。毎朝のスケジュール実行でも、日付を指定した再実行でも同じ定義で動きます。
* **複数ファイルが揃ったら集計**: 「注文」「会員」の 2 つのアセットを「同じ partition を待つ」で指定し、両方の同じ日付分が揃ったときだけ集計を起動。
* **時間別ファイルの取りこぼし防止**: 毎時スケジュールに Catchup を付け、停止明けに取りこぼした時間帯を自動で追い実行。

## 注意点・制限

* Asset トリガーは、トリガーを保存する前に届いた実体化は再配信されません。センサーや上流より先にトリガーを用意してください（取りこぼしはバックフィルで埋められます）。
* 一時停止中・無効なトリガーでは起動しません。一時停止期間に届いた分は「pause 期間の取りこぼしから提案」でバックフィルできます。
* 変数を設定し忘れて `${変数名}` が残ったままのステップは、実行せず失敗として扱われます（既定）。
* 実行時変数の名前は英数字と「\_」のみ。RUN\_ID / WORKFLOW\_RUN\_ID は予約済みで定義できません。テンプレートの誤りは保存時にエラーになります。
* 失敗ステップからの再実行では、日付などの変数は再計算されず、元の実行の値が使われます。
* 派生変数のパターンに使えるのは \{YYYY} \{MM} \{DD} \{HH} のみです。

## 詳しい設定（データ担当者向け）

実行時変数のテンプレートは BigQuery Data Transfer Service 互換です。

| 書き方 | 結果の例 |
| - | - |
| `{run_time}` | 2026-08-05T01:30:00Z（UTC） |
| `{run_time+9h-72h\|"%Y-%m-%d"}` | 2026-08-02（JST の 3 日前） |
| `{run_time+9h-2h\|"%Y%m%d%H"}` | 時間 partition 用 |
| `{run_date}` | 20260805 |
| `{run_date-3d\|"%Y-%m-%d"}` | 2026-08-02 |

* `run_time` の加減算は d / h / m、`run_date` は d のみ。書式は %Y %m %d %H %M %S のみ使えます。
* `run_time` は UTC 基準です。JST の日付列に使うときは `+9h` を付けます（付けずに日付書式を使うと「UTC 暦日になります」と注意が出ます）。TIMESTAMP 列や取り込み時刻で区切るテーブルは UTC の日で区切られるため `+9h` は付けません。
* 日付境界の前後 30 分にあるスケジュールは、起動の遅れで日付が進むことがあります。

## 関連ページ

* [02-3-1 自動処理（ワークフロー）：基本と作り方](/dsv2/workflow-basics)
* [02-3-4 自動処理（ワークフロー）：失敗への備えと運用](/dsv2/workflow-failure-and-operations)
* [02-5 生成データ（アセット）](/dsv2/assets)
* [02-6 データ到着チェック（センサー）](/dsv2/sensors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.