---
articleId: dc4455f0-b664-46c8-bf19-e1b63780d291
slug: loop-using-custom-variables
title: カスタム変数ループ実行
parentCategoryId: 6f2c2c28-57a2-4d93-a35f-b96f0a65affd
languageCode: ja
---
## 概要

カスタム変数ループ実行とは、カスタム変数を埋め込んだ転送設定・データマート定義を、ワークフロー定義上に組み込んだときに設定できる機能です。
本ページでは、カスタム変数ループ実行の概要、および設定内容について、ユースケースを交えてご紹介します。

## カスタム変数ループ実行とは

カスタム変数ループ実行では、タスクに埋め込んだカスタム変数に対して、**複数の値を展開**するよう設定できます。
この設定を施したタスクがワークフロージョブ内で実行されると、「カスタム変数に値を展開し、それを踏まえた形でジョブを実行する」という処理が順番に繰り返されます。
結果的に、**1回のタスク実行で複数のジョブを実行**できます。

:::(Info) (カスタム変数・ワークフロー定義について)
それぞれの概要および設定方法について、詳しくは下記を参照ください。
- [カスタム変数について](/docs/custom-variables)
- [ワークフロー定義について](/docs/about-workflow)
:::

## ユースケース

カスタム変数ループ実行の代表的なユースケースについてご紹介します。

### 転送元広告系コネクタから、複数のアカウントIDのデータをまとめて転送する

広告系コネクタで広告アカウントIDを複数利用している場合に、複数の広告アカウントIDのデータをまとめて転送できます。

#### 設定例

転送設定を作成するときに、**広告アカウントID**にカスタム変数を埋め込みます。
上記の転送設定をワークフロー定義に組み込み、**転送対象の広告アカウントID一覧**をカスタム変数に展開するように設定します。

### 転送元ファイル・ストレージ系コネクタから、特定日時のファイルを転送する

ファイル名のプレフィックスまたはサフィックスに日時が含まれている場合に、指定した日時を含むファイルをまとめて転送できます。
同様に、特定の日時を含むフォルダ配下のファイルもまとめて転送できます。

#### 設定例

転送設定を作成するときに、**パスプレフィックス**にカスタム変数を埋め込みます。
上記の転送設定をワークフロー定義に組み込み、**転送対象の日時一覧**をカスタム変数に展開するように設定します。

### 転送元データベース系コネクタから、大容量ファイルを分割して転送する

データベース系コネクタから大容量のデータを転送したい場合に、ファイルを分割して転送できます。
ジョブを分割して転送することで、1回のジョブにまとめて転送する場合よりも、短い時間で転送を終えられる可能性があります。

#### 設定手順

転送設定を作成するときに、**クエリ**内にカスタム変数を埋め込みます。
たとえば、timestamp型のカラムを基準に分割する場合は、クエリ内に以下のようなWHERE句を記述します。
```
WHERE column_timestamp BETWEEN "$start_date$" AND "$end_date$"
```
上記の転送設定をワークフロー定義に組み込み、任意の回数にジョブが分割されるようにカスタム変数に展開する日付を設定します。

### 転送元データベース系コネクタから、同一スキーマのテーブルをまとめて転送する

データベース系コネクタに同一スキーマのテーブルが複数ある場合に、複数のテーブルをまとめて転送できます。

#### 設定手順

転送設定を作成するときに、**クエリ**内のFROM句にカスタム変数を埋め込みます。
上記の転送設定をワークフロー定義に組み込み、**転送対象のテーブル名一覧**をカスタム変数に展開するように設定します。

### Google Analytics 4から転送するデータがサンプリングされないようにする

Google Analytics 4のAPI側の仕様により、転送元Google Analytics 4で取得対象のデータサイズが一定以上大きくなると、サンプリングが発生します。
取得対象のデータを分割することで、サンプリング取得を回避できます。

#### 設定手順

転送設定を作成するときに、**データ取得期間**の開始日・終了日にカスタム変数を埋め込みます。
上記の転送設定をワークフロー定義に組み込み、サンプリングされない程度に細かくジョブを分割されるよう、カスタム変数に展開する日付を設定します。（例：1日単位で分割）

### データマート定義を用いて、特定カラムをキーにテーブルを分割する

テーブルに含まれる特定のカラムをキーに、テーブルを分割できます。
たとえば、`A社`、`B社`、`C社`...といった値を持つカラム`company_id`を含むテーブルがあったときに、テーブルを各社に分けて作成できます。

#### 設定手順
データマート定義を作成するときに、**クエリ**および**出力先テーブル**にカスタム変数を埋め込みます。

以下は、クエリおよび出力先テーブルの例です。
- クエリの例
```
SELECT *
FROM
  <元テーブル>
WHERE
  company_id == $companyId$
```

- 出力先テーブルの例
```
$date$_$companyId$
```
上記のデータマート定義をワークフロー定義に組み込み、**キーとなるカラムに含まれる値の一覧**をカスタム変数に展開するように設定します。

---
上記の他にも、カスタム変数ループ実行にはさまざまなユースケースがあります。
詳細について、カスタマーサクセスまでお問い合わせください。

## 設定手順

1. 転送設定・データマート定義を作成します。このとき、適宜カスタム変数を埋め込みます。    
    ![image.png](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/loop-using-custom-variables-2024-08-29-7-5-0.png){height="" width="500"}
:::(Warning) (文字列型のカスタム変数の値)
文字列型のカスタム変数を埋め込む場合、**値**を入力します。この値は、ループ実行時に展開される値によって上書きされます。
したがって、**この値はループ実行時には用いられません。ご注意ください。**
:::

2. ワークフロー定義を作成します。

3. フロー編集画面にて、カスタム変数を埋め込んだタスク（転送設定・データマート定義）を組み込みます。
    ![image.png](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/loop-using-custom-variables-2024-08-29-7-5-1.png){height="" width="500"}

4. タスク右側の三点リーダー＞鉛筆アイコンをクリックします。タスク編集画面が表示されます。
![image.png](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/loop-using-custom-variables-2024-08-29-7-5-2.png){height="" width="500"}

5. タスク編集画面にて、**カスタム変数でループ実行**を有効化し、**ループの種類**を選択します。
    ![image.png](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/loop-using-custom-variables-2024-08-29-7-5-3.png)

6. **対象カスタム変数**を選択し、それぞれ適宜設定します。
    各設定項目について、詳しくは後述の「ループの種類ごとの設定項目」を参照ください。

7. ワークフロージョブを実行します。
    **カスタム変数でループ実行**が有効のタスクジョブは、カスタム変数に順番に値が展開される形でループ実行されます。
    以下は、ループ実行されたタスクジョブの実行ログです。
    ![image.png](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/loop-using-custom-variables-2024-08-29-7-5-4.png){height="" width="500"}

### ループの種類ごとの設定項目

#### 文字列展開でループ

カスタム変数に展開したい文字列を入力します。
展開したい文字列を追加したい場合は、**ループを追加**をクリックしてください。
なお、ループ実行の際は、入力した順に文字列が展開されます。
![image.png](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/loop-using-custom-variables-2024-08-29-7-5-5.png){height="" width="500"}

:::(Info) (コピー・アンド・ペーストによる一括入力)
以下のようなテキストをコピー・アンド・ペーストすることで、一括入力できます。
```
hoge
fuga
piyo
```
:::

#### 期間(相対指定)でループ

期間、ループ間隔、展開設定を適宜設定します。
なお、ループ実行の際は、**カスタム変数出力イメージ**の順に日付が展開されます。

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

#### クエリ結果でループ

DWH上でクエリを実行し、その結果の値をカスタム変数に展開できます。
**クエリ結果でループ**は、以下のDWHにて対応しています。
- Amazon Redshift
- Google BigQuery
- Snowflake
- Databricks

以下の画面キャプチャは「BigQueryのクエリ結果でループ」の例です。

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

### エラーハンドリング

ループ実行中にいずれかのループでエラーが発生した場合の挙動を、次の3種類から選択できます。

- **エラー発生時に処理を停止**：1件でもエラーになった時点でループを停止し、以降のループは起動しません。
- **すべてのエラーをスキップ**：エラーが出ても無視し、残りのループタスクを最後まで実行します。
- **上限回数までエラーをスキップ**：エラーが指定した上限の回数以下ならスキップして続行し、上限回数を超えた時点でループを停止します。

:::(Info) (エラーハンドリングとタスクの成否)

エラーハンドリングでは、ループタスクが失敗した場合に、残りのループタスクを実行する条件を設定する機能です。
エラーハンドリングによらず、タスク自体は1つでもループタスクが失敗した場合は失敗となります。

:::

### 並列実行

ループタスクを1件ずつ順に実行するか、同時に複数起動して進めるかを切り替えられます。

- **OFF（逐次実行）**：ループタスクを1件ずつ順に実行します。前のループタスクの結果を確認してから次を起動します。
- **ON（並列実行）**：ワークフロー全体の「タスク同時実行上限数」の範囲で、ループタスクをまとめて並列に実行します。

並列実行時も、エラーハンドリングの設定に従い、エラーが条件を超えた時点で新しいループの起動は停止します。