【Google Cloud】スケジュールされたクエリをパラメータを用いて動的に作ってみた

## 記事作成のきっかけ
特定条件で絞り込みを行ったデータを定期的に確認したいと思い、SQLを日次スケジュールで実行する「スケジュールされたクエリ」を用いたいと考えたことがきっかけとなります。

## 記事の対象者
+ 定期的に特定のSQLを実行されていて自動化させたい方
+ 「スケジュールされたクエリ」を利用してシステム日付を条件に実行させたい方

## 結論
+ 単純なSQLを定期的に実行して結果を収集したい方には「スケジュールされたクエリ」のご利用はオススメ。
+ 「スケジュールされたクエリ」では、使用できるパラメータが決まっているため、複雑な条件を実行するタイミングごとに変更することは出来ない機能となっております。
<table>
  <caption>【使用可能なパラメータ】</caption>
  <thead>
    <tr>
      <th>名前</th> <th>説明</th> <th>具体例</th>
    </tr>
  </thead>
  <tr>
    <td> @run_date </td> <td>論理カレンダー日</td> <td>2023-11-29</td>
  </tr>
  <tr>
    <td> @run_time </td> <td>実行予定時刻</td> <td>2023-11-29 05:50:50 UTC</td>
  </tr>
</table>

## 目次
1. スケジュールされたクエリとは
1. 必要な権限
1. 成功したときの挙動
3.1. 固定のクエリ文を定期的に実行するケース
3.2. パラメータを用いたクエリ文を定期的に実行するケース
1. 失敗したときの確認方法
1. おわりに

## １．スケジュールされたクエリとは
自身で作成したクエリを定期的に実行するようにスケジュール設定をしてくれる機能になります。
また、実行した結果を特定のテーブルへ書き込むことができ、定期的な調査や分析に使用することも可能となります。

以下BiQqueryの赤枠から設定することが可能です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/bf96dc41-b27f-2e25-2ac5-05dcfb98ce18.png)

## ２．必要な権限
スケジュールされたクエリを実行するために、以下の権限が必要となります。

〇スケジュールされたクエリを実行するために必要な権限
+ bigquery.transfers.update
bigquery.datasets.get

もしくは
+ bigquery.jobs.create
bigquery.transfers.get
bigquery.datasets.get

〇スケジュールされたクエリを変更または削除するために必要な権限
+ bigquery.transfers.update
bigquery.jobs.create
スケジュールされたクエリの所有権

## 3．成功したときの挙動
いくつか試してみたケース毎に設定内容を記載していきたいと思います。

### 3.1. 固定のクエリ文を定期的に実行するケース
前提条件を定義します。
・実行頻度：毎日実行する
・実行クエリ：固定
・結果の格納先テーブル：未作成

１．初めに、定期的に実行したいクエリをご用意します。
下図のようにクエリを用意後、赤枠のスケジュールを押下します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/8b58ddc9-457f-ae6a-c4cb-c00154524ef6.png)
※プロジェクトID、データセット、テーブルはご自身の所持しているものに置き換えてください。

２．各種必須項目「*」となっている項目を記載します。
以下の設定だと、2023年11月20日以降2050年12月31日の間で毎日22:00 UTCにて実行されます。
※繰り返し頻度と実行期間はそれぞれタイムゾーンが異なるため、ご注意ください。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/44408de4-f791-f0d2-554d-43795f0312ee.png)

<table>
  <caption>【繰り返し頻度の種類】</caption>
  <thead>
    <tr>
      <th>頻度</th> <th>説明</th> <th>備考</th>
    </tr>
  </thead>
  <tr>
    <td>分</td> <td>分単位の実行</td> <td>最低15分間隔</td>
  </tr>
  <tr>
    <td>時間</td> <td>時間単位の実行</td> <td>最低1時間間隔</td>
  </tr>
  <tr>
    <td>日</td> <td>日次単位の実行</td> <td>特になし</td>
  </tr>
  <tr>
    <td>週</td> <td>週次単位の実行</td> <td>最低曜日を1種類以上指定</td>
  </tr>
  <tr>
    <td>月</td> <td>月次単位の実行</td> <td>最低月を1種類以上指定</td>
  </tr>
</table>

３．実行した結果を格納するテーブルを指定します。
この時に、データを追加するか上書きをするか選択をしてください。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/d22b589f-481c-2e62-5145-72d745cdfdcc.png)

必要な情報を入力後、保存するとスケジュールされたクエリが作成されます。
次の実行の予定日の日付となったら自動的に実行してくれます。
（以下は実行後の画面となります。）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/38a72349-9a0b-f525-2675-6c32a0270c0a.png)

### 3.2. パラメータを用いたクエリ文を定期的に実行するケース
前提条件を定義します。
・実行頻度：毎日実行する
・実行クエリ：変動パラメータを含む
・結果の格納先テーブル：未作成

１．初めに、定期的に実行したいクエリをご用意します。
赤下線部にて記載されているように日付情報を条件とするWHERE句を作成が可能となります。
画像の例だと更新日が実行日以降のデータのみ対象となるため、最新データの取得を毎日実施することが可能となります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/c19e4410-e4be-3a4f-d57c-cef2b8a8c267.png)

これ以降の設定は[3.1. 固定のクエリ文を定期的に実行するケース](#31-固定のクエリ文を定期的に実行するケース) と同様になります。

## ４．失敗したときの確認方法
設定したスケジュールが失敗したかを確認する方法はいくつかございます。
### 4.1.作成したスケジュール詳細を確認する方法
ナビゲーションメニューのBigQuery > スケジュールされたクエリを確認すると失敗しているか確認することが出来ます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/5fde3424-bc08-b01b-e1eb-bcb99e499585.png)
どんなエラーか確認するには「表示名」(例:schedule)を選択して詳しい詳細を見ることが可能です。
また、エラーを確認して再試行することも可能となります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/ecfce13c-d1c0-ea72-c135-197d92b7af9c.png)
### 4.2.設定した通知メールから確認する方法
スケジュール設定を行う際に、「メール通知を送信する」にチェックを入れることで、クエリ実行が失敗したときにメール通知をしてくれます。
※ただし、通知するのは当該スケジュールのオーナーにのみメール通知が送られます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3538663/7cd59173-81fe-4a89-73ec-b15095ae36a5.png)

メールの通知があれば、当該スケジュールの詳細を確認します。

## ５．おわりに
Google Cloudにてクエリのスケジュール化、動的パラメータ設定をまとめさせていただきました。
間違いやご指摘等あれば、コメント頂けると大変助かります。
本記事が、どなたかの役に立てたのであれば幸いです。
ご覧頂き、ありがとうございました。

##
株式会社ジールはMicrosoft Azure やAWS（Amazon Web Services）、Google Cloud Platform（GCP）、Oracle Cloud Infrastructure（OCI）など、多彩なクラウドプラットフォーム構築・運用の知見を有しています。そのため、複数のクラウドサービスを組み合わせるマルチクラウド環境においても、ベンダーロックインを回避し、お客様のご要望に応じた最適なクラウドプラットフォームの構築・運用への対応が可能です。
https://www.zdh.co.jp/products-services/cloud-data/