---
articleId: f56971e0-29ec-4df6-bc9b-7e4b9e3fefec
slug: custom-variables
title: カスタム変数について
parentCategoryId: 3e88a521-8be7-4f6e-b507-e21f53098f01
languageCode: ja
---
## 概要

カスタム変数とは、転送設定・データマート定義・dbtジョブ設定などの設定項目に埋め込むことができる変数です。
カスタム変数の値は、**ジョブの実行時に展開されます**。

## 利用例

たとえば、以下のような目的で利用されます。

- 転送元側のSQL文に埋め込みます。
  ジョブ実行日時が展開されることで、転送対象の行をフィルタリングできます。
  ![image](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/custom-variables-2024-08-29-15-1-0.png){height="" width="500"}
- 転送先テーブル名にsuffixの形で埋め込みます。
  ジョブ実行日時が展開されることで、シャーディングテーブルを作成できます。
  ![image](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/custom-variables-2024-08-29-15-1-1.png){height="" width="500"}

:::(Info) (カスタム変数ループ実行)

ワークフロー定義では、カスタム変数が埋め込まれたタスクに対して複数の値を順次展開することで、擬似的にループ処理をさせることができます。
詳しくは、[カスタム変数ループ実行](/docs/loop-using-custom-variables)を参照ください。
:::

:::(Warning) (転送設定にカスタム変数を埋め込む際の注意事項)

- **転送元**側で定義したカスタム変数は、**転送先**側の設定項目には埋め込めません。同様に、**転送先**側で定義したカスタム変数は、**転送元**側の設定項目には埋め込めません。
- **転送元**側と**転送先**側で同名のカスタム変数が定義された場合、以下のケースにおいて**転送先**側のカスタム変数が優先されます。この場合、**転送先**側のカスタム変数の展開値が、**転送元**側のカスタム変数にも展開されます。
  - ワークフローのループ実行時
  - 転送設定STEP2のカラム定義の**デフォルト値**
  - TROCCO APIを利用したジョブの実行
  - **変数ごとに値を指定**したジョブの実行
:::

## カスタム変数の種類

### 文字列のカスタム変数

ジョブの実行時に文字列を展開できます。
定義する際には、固定の文字列を設定します。

:::(Info) (固定の文字列が利用されるケース)

文字列のカスタム変数は、ジョブ実行時に値が展開（上書き）されず、固定の文字列がそのまま用いられるケースがあります。
たとえば、以下のケースにおいて固定の文字列が利用されます。

- ジョブ実行時に選択する**カスタム変数展開方法**にて、**現在時刻を基準に展開**または**指定日時を基準に展開**を選択した場合
- ジョブがスケジュール実行された場合
- ワークフロータスクの**カスタム変数でループ実行**にて、**期間(相対指定)でループ**が選択されている場合
:::

### 日付・時刻のカスタム変数

カスタム変数に値を展開する際の[基準日時](/docs/custom-variables#基準日時について)に対して、**相対的な時間**を展開できます。
なお、ここで指定した**タイムゾーン**に基づいて展開される日時は定まり、指定した**日付フォーマット**で値が展開されます。
たとえば、以下のケースで基準日時が「2024年04月01日00時00分00秒（日本時間）」となった場合、`2024-03-31 00:00:00`という値が展開されます。

![image](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/custom-variables-2024-08-29-15-1-2.png){height="" width="500"}

なお、**時刻・日付 (キューイング時)** と**時刻・日付 (実行時)** は、カスタム変数に値を展開する際の**基準日時**に違いがあります。
詳しくは、後述の[基準日時について](/docs/custom-variables#基準日時について)を参照ください。

#### 日付・時刻のフォーマット

基準日時が「2024年04月01日00時00分00秒（日本時間）」の場合、以下のように展開されます。

| 形式 | 日付フォーマット | 展開結果 |
| --- | --- | --- |
| `%Y%m%d` | 日付 | 20240401 |
| `%Y/%m/%d` | 日付 | 2024/04/01 |
| `%Y-%m-%d` | 日付 | 2024-04-01 |
| `%Y-%m-%d %H:%M:%S` | 日時 |2024-04-01 00:00:00 |
| `%Y-%m-%dT%H:%M:%S%:z` | 日時+タイムスタンプ | 2024-04-01T00:00:00+09:00 |
| `%s` | UNIX時間 | 1711897200 |

上記例以外にもRuby言語の`strftime`メソッドのフォーマットが利用可能です。
詳しくは、[Rubyリファレンスマニュアル](https://docs.ruby-lang.org/ja/latest/method/Time/i/strftime.html)を参照ください。

## カスタム変数の展開方法

ジョブを実行するときに、以下の3つより選択できます。

- **現在時刻を基準に展開**：ジョブの実行開始時間を基準日時とします。
- **指定日時を基準に展開**：基準日時を手動で定義できます。
- **変数ごとに値を指定**：カスタム変数に展開する値を手動で定義できます。

なお、スケジュール設定によってジョブが実行された場合は、ジョブの実行開始時間が基準日時となります。

## 仕様に関する補足情報

### 基準日時について

**時刻・日付 (キューイング時)** と**時刻・日付 (実行時)** は、カスタム変数に値を展開する際の**基準日時**に違いがあります。

- **時刻・日付 (実行時)** の場合：
  - **該当ジョブの開始日時**を基準に、値が展開されます。
- **時刻・日付 (キューイング時)** の場合：
  - **該当ジョブの実行がトリガーされた日時**を基準に、値が展開されます。

:::(Info) (ワークフロージョブにおける、両者の基準となる日時の違い)

**時刻・日付 (キューイング時)** と**時刻・日付 (実行時)** における**基準日時**の差異は、ワークフロージョブの実行時において顕著となります。

- **時刻・日付 (キューイング時)**
  - ワークフロー定義内に存在する**時刻・日付 (キューイング時)** が埋め込まれたタスク（子ワークフロー内に定義されたタスクも含む）がある場合、それらの基準日時はすべて**ワークフロージョブが初回実行を開始した日時**となります。
  - また、ワークフロージョブが自動リトライされた結果実行されるタスクの基準日時も、**ワークフロージョブが初回実行を開始した日時**となります。
- **時刻・日付 (実行時)**
  - 一方、ワークフロー定義に**時刻・日付 (実行時)** が埋め込まれたタスクがある場合、それらの基準日時は**該当タスクのジョブが実際に実行を開始した日時となります**。

なお、スケジュール設定を用いてジョブを実行する運用の場合、**時刻・日付 (キューイング時)** の利用を推奨しています。
万一ジョブが失敗して翌日以降に再実行する場合に、前回のジョブの基準日時でカスタム変数に値を展開できるためです。
:::

### ワークフロージョブにおけるカスタム変数の展開仕様

#### カスタム変数ループ実行を設定している場合

[カスタム変数ループ実行](/docs/loop-using-custom-variables)でループ対象となったカスタム変数には、**ループ実行側の設定に基づいて値が展開されます**。
すなわち、ワークフロージョブの実行時に選択したカスタム変数の展開方法は、ループ実行側の値の展開設定によって上書きされます。

#### ワークフロー定義内にワークフロー定義を組み込んだ場合

前者を親ワークフロー、後者を子ワークフローと定義します。
子ワークフローをカスタム変数でループ実行した場合、ループ対象となったカスタム変数の展開値は、子ワークフロー実行時に引き継がれます。
すなわち、カスタム変数の展開値が子ワークフロータスク内にある同名のカスタム変数に展開されます。