クエリのスケジューリング

このページでは、BigQuery で定期的なクエリをスケジュールする方法について説明します。

は、

ベータ版 です。

これは、BigQuery でのクエリのスケジュール設定 のベータ版リリースです。 このプロダクトは下位互換性のない方法で変更される可能性があり、と は、SLA または非推奨ポリシーの対象ではありません。

概要

クエリを定期的に実行するようにスケジュールできます。スケジュールされたクエリは、標準 SQL で作成する必要があります。このクエリには、データ定義言語（DDL）およびデータ操作言語（DML）のステートメントを含めることができます。クエリ文字列と宛先テーブルはパラメータ化が可能で、クエリ結果を日付と時刻で整理できます。

始める前に

スケジュールされたクエリを作成する前に、以下を行います。

• スケジュールされたクエリは、BigQuery Data Transfer Service の機能を使用します。BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。

• 従来の BigQuery ウェブ UI を使用してスケジュールされたクエリを作成する場合は、ブラウザで bigquery.cloud.google.com からのポップアップを許可して権限ウィンドウが表示されるようにします。BigQuery Data Transfer Service に、スケジュールされたクエリを管理する権限を付与する必要があります。

必要な権限

クエリをスケジュールする前に:

• 転送を作成するユーザーに、BigQuery で必要な次の権限が付与されていることを確認します。

  • 転送を作成するための bigquery.transfers.update 権限。
  • ターゲット データセットに対する bigquery.datasets.update 権限

  事前定義されたプロジェクト レベルの IAM 役割である bigquery.admin には、bigquery.transfers.update 権限と bigquery.datasets.update 権限が含まれています。BigQuery での IAM 役割の詳細については、アクセス制御をご覧ください。

構成オプション

クエリ文字列

クエリ文字列は、標準 SQL で記述された有効なものでなければなりません。スケジュールされたクエリは、実行のたびに以下のクエリ パラメータを受け取ることができます。

利用可能なパラメータ

パラメータ	標準 SQL 型	値
@run_time	TIMESTAMP	UTC 時間で表されます。定期的にスケジュールされたクエリの場合、run_time は実行予定時刻を表します。たとえば、スケジュールされたクエリが「24 時間ごと」に設定されている場合、実際の実行時間が多少異なる場合でも、連続する 2 つのクエリ間の run_time 差はちょうど 24 時間になります。
@run_date	DATE	論理カレンダー日を表します。

例

この例では、クエリ文字列に @run_time パラメータを含めて、hacker_news.stories という名前の一般公開データセットに対してクエリを実行します。

SELECT @run_time AS time,
  title,
  author,
  text
FROM `bigquery-public-data.hacker_news.stories`
LIMIT
  1000

宛先テーブル

スケジュール指定があるクエリの設定時にクエリ結果の宛先テーブルが存在しない場合は、BigQuery によってテーブルが作成されます。DDL / DML クエリを使用する場合は、宛先テーブルを空白のままにします。

ターゲット テーブルが存在する場合、スキーマに列を追加する（ALLOW_FIELD_ADDITION）か、列のモードを REQUIRED から NULLABLE に緩和する（ALLOW_FIELD_RELAXATION）と、クエリ結果に基づいて宛先テーブルのスキーマが更新される可能性があります。これ以外の場合は、実行の間にテーブルのスキーマが変更されると、スケジュールされたクエリが失敗します。

クエリは、さまざまなプロジェクトやデータセットからテーブルを参照できます。スケジュールされたクエリを構成するときは、テーブル名に宛先データセットを含める必要はありません。宛先データセットは別に指定します。

書き込み設定

選択した書き込み設定によって、クエリ結果が既存の宛先テーブルに書き込まれる方法が決まります。DDL / DML クエリを使用する場合は、書き込み設定を空白のままにします。

• WRITE_TRUNCATE: テーブルがすでに存在する場合、BigQuery によってテーブルのデータが上書きされます。
• WRITE_APPEND: テーブルがすでに存在する場合、BigQuery によってデータがテーブルに追加されます。

宛先テーブルの作成、切り捨て、追加が行われるのは、BigQuery がクエリを正常に完了できた場合のみです。作成、切り捨て、追加アクションは、ジョブ完了時に 1 つのアトミック更新として発生します。

分割のオプション

スケジュール指定があるクエリでは、分割または非分割の宛先テーブルを作成できます。DDL / DML クエリを使用する場合は、分割フィールドを空白のままにします。BigQuery には次の 2 種類のテーブル分割があります。

• 取り込み時間分割テーブル: スケジュールされたクエリの実行時間を基準にして分割されたテーブル。
• 分割テーブル: TIMESTAMP 列または DATE 列を基準にして分割されたテーブル。

宛先テーブルが列で分割される場合は、スケジュールされたクエリを設定するときに列名を指定します。取り込み時間分割テーブルと分割されていないテーブルの [Partitioning field] は空白のままにします。

分割テーブルの詳細については、分割テーブルの概要をご覧ください。

分割の例

• 分割なしのテーブル
  • [Destination table] - mytable
  • [Partitioning field] - 空白のまま
• 取り込み時間分割テーブル
  • [Destination table] - mytable$YYYYMMDD
  • [Partitioning field] - 空白のまま
• 列分割テーブル
  • [Destination table] - mytable
  • [Partitioning field] - テーブル分割に使用される TIMESTAMP 列または DATE 列の名前

利用可能なパラメータ

スケジュールされたクエリを設定するときに、ランタイム パラメータを使用して宛先テーブルをどのように分割するかを指定できます。

パラメータ	テンプレートの種類	値
run_time	フォーマットされたタイムスタンプ	スケジュールごとに UTC 時間で設定されます。定期的にスケジュールされたクエリの場合、run_time は実行予定時刻を表します。たとえば、スケジュールされたクエリが「24 時間ごと」に設定されている場合、実際の実行時間が多少異なる場合でも、連続する 2 つのクエリ間の run_time 差はちょうど 24 時間になります。 TransferRun.runTime をご覧ください。
run_date	日付文字列	%Y%m%d 形式の run_time パラメータの日付になります。たとえば、20180101 となります。この形式は、取り込み時間分割テーブルと互換性があります。

テンプレート システム

スケジュールされたクエリは、テンプレート構文で宛先テーブル名におけるランタイム パラメータをサポートします。

パラメータ テンプレート構文

テンプレート構文は、基本的な文字列のテンプレートと時間オフセットをサポートします。パラメータは、次の形式で参照されます。

• {run_date}
• {run_time[+\-offset]|"time_format"}

パラメータ	目的
run_date	このパラメータは、YYYYMMDD 形式の日付に置き換えられます。
run_time	このパラメータは、次のプロパティをサポートします。 offset 時間オフセットは、時間（h）、分（m）、秒（s）の順序で表されます。 日（d）はサポートされていません。 小数を指定できます。たとえば 1.5h です。 time_format フォーマット文字列。最も一般的なパラメータの形式は、年（%Y）、月（%m）、日（%d）です。 分割テーブルの場合、YYYYMMDD は必須の接尾辞です。これは「%Y%m%d」と同等です。 詳しくは datetime エレメントのフォーマット設定をご覧ください。

使用上の注意:

• run_time、offset、time 形式の間に空白文字は使用できません。
• 文字列にリテラル中かっこを含めるには、‘\{‘ and ‘\}’ としてエスケープできます。
• time_format に “YYYY|MM|DD” などのリテラル引用符や縦線を含めるには、‘\”’ や ‘\|’ のフォーマット文字列でエスケープできます。

パラメータ テンプレートの例

以下の例は、異なる時刻形式の宛先テーブル名を指定し、実行時間をオフセットする方法を示しています。

run_time（UTC）	テンプレート パラメータ	出力宛先テーブル名
2018-02-15 00:00:00	mytable	mytable
2018-02-15 00:00:00	mytable_{run_time|"%Y%m%d"}	mytable_20180215
2018-02-15 00:00:00	mytable_+25h{run_time|"%Y%m%d"}	mytable_20180216
2018-02-15 00:00:00	mytable_-1h{run_time|"%Y%m%d"}	mytable_20180214
2018-02-15 00:00:00	mytable_+1.5h{run_time|"%Y%m%d;%H"} または mytable_+90m{run_time|"%Y%m%d;%H"}	mytable_2018021501
2018-02-15 00:00:00	{run_time+97s|"%Y%m%d"}_mytable_{run_time|"%H%M%s"}	20180215_mytable_000137

スケジュールされたクエリの設定

Console

1. GCP Console で BigQuery ウェブ UI を開きます。

   BigQuery ウェブ UI に移動

2. 関心のあるクエリを実行します。結果に問題がなければ、[クエリのスケジュール]、[スケジュールされたクエリを新規作成] の順にクリックします。

   

3. スケジュールされたクエリのオプションが [新たにスケジュールされたクエリ] パネルに表示されます。

4. [新たにスケジュールされたクエリ] パネルで次の操作を行います。

   • [スケジュールされたクエリの名前] に、クエリの名前（My scheduled query など）を入力します。スケジュールされたクエリの名前には、後で修正が必要になった場合に簡単に識別できるよう、任意の値を使用できます。
   • （省略可）[スケジュール オプション] は、デフォルト値の [毎日]（作成時間に基づいて 24 時間ごと）のままにするか、[開始時刻をスケジュール] をクリックして時間を変更します。間隔を [毎週]、[毎月]、[カスタム] に変更することもできます。[カスタム] を選択すると、every 3 hours のような Cron と同様の時間を指定するよう求められます。最短許容時間は 15 分です。他の有効な API 値については、TransferConfig の schedule フィールドをご覧ください。
   • [データセット名] で、適切な宛先データセットを選択します。
   • [宛先テーブル] は、以下のように設定します。
     • 標準 SQL クエリの場合、宛先テーブルの名前を入力します。
     • DDL / DML クエリの場合、このフィールドを空白のままにします。
   • [宛先テーブルの書き込み設定] で、宛先テーブルを上書きする WRITE_TRUNCATE、または宛先テーブルにデータを追加する WRITE_APPEND のどちらかを選択します。DDL / DML クエリでは、このオプションは使用できません。

   • （省略可）[メール通知を送信する] をオンにして、転送実行失敗のメール通知を許可します。

     

5. [スケジュール] をクリックします。

6. スケジュールされたクエリのステータスを確認するには、ナビゲーション ペインで [スケジュールされたクエリ] をクリックします。ページを更新すると、スケジュールされたクエリの最新のステータスが表示されます。個々のスケジュールされたクエリをクリックすると、詳細を確認できます。

   

従来の UI

1. BigQuery ウェブ UI に移動します。

   BigQuery ウェブ UI に移動

2. 関心のあるクエリを実行します。結果に問題がなければ、[Schedule Query] をクリックします。

   

3. スケジュールされたクエリのオプションは、クエリボックスの下に表示されます。

4. [New Scheduled Query] ページで次の操作を行います。

   • [Destination Dataset] で、該当するデータセットを選択します。
   • [Display Name] に、スケジュールされたクエリの名前（My scheduled query など）を入力します。スケジュールされたクエリの名前には、後で修正が必要になった場合に簡単に識別できるよう、任意の値を使用できます。
   • [Destination Table] は、以下のように設定します。
     • 標準 SQL クエリの場合、宛先テーブルの名前を入力します。
     • DDL / DML クエリの場合、このフィールドを空白のままにします。
   • [Write Preference] は、以下のように設定します。
     • 標準 SQL クエリの場合、宛先テーブルを上書きする WRITE_TRUNCATE、または宛先テーブルにデータを追加する WRITE_APPEND のどちらかを選択します。
     • DDL / DML クエリの場合、[Unspecified] を選択します。

   • （省略可）[Partitioning field] は、以下のように設定します。

     • 標準 SQL クエリの場合、宛先テーブルが列分割テーブルであれば、テーブルを分割する列の名前を入力します。取り込み時間分割テーブルと分割なしのテーブルでは、このフィールドを空白のままにします。

     • DDL / DML クエリの場合、このフィールドを空白のままにします。

       

   • （省略可）[Schedule] では、デフォルト値の [Daily]（作成時間に基づいて 24 時間ごと）のままにするか、[Edit] をクリックして時間を変更します。間隔を [Weekly]、[Monthly]、[Custom] に変更することもできます。[カスタム] を選択すると、every 3 hours のような Cron と同様の時間を指定するよう求められます。最短許容時間は 15 分です。他の有効な API 値については、TransferConfig の schedule フィールドをご覧ください。

     

   • （省略可）[Advanced] セクションを展開し、転送の実行通知を構成します。転送実行通知は、現時点ではアルファ版です。

     • [Cloud Pub/Sub topic] に、Cloud Pub/Sub トピックの名前（例: projects/myproject/topics/mytopic）を入力します。

     • [Send email notifications] をオンにして、転送実行失敗のメール通知を許可します。

       

5. [Add] をクリックします。

6. スケジュールされたクエリのステータスを確認するには、ナビゲーション ペインで [Scheduled queries] をクリックします。ページを更新すると、スケジュールされたクエリの最新のステータスが表示されます。個々のスケジュールされたクエリをクリックすると、詳細を確認できます。

   

過去の日付に基づく手動実行を設定する

今後実行するクエリをスケジュールできるだけでなく、手動でクエリの即時実行をトリガーすることもできます。クエリで run_date パラメータを使用していて、前回の実行中に問題が発生した場合は、即時実行をトリガーする必要があります。

たとえば、毎日 09:00 に、抽出元テーブルに対して現在の日付と一致する行をクエリするとします。しかし、過去 3 日間、抽出元テーブルにデータが追加されていないことがわかりました。このような場合、指定した日付範囲内の過去のデータに対してクエリが実行されるように設定できます。このように設定したクエリは、スケジュールされたクエリで構成されている日付に対応する run_date と run-time の組み合わせに従って実行されます。

スケジュールされたクエリを設定した後、過去の日付範囲を使用してクエリを実行する方法を以下に説明します。

Console

[スケジュール] をクリックしてスケジュールされたクエリを保存した後、[スケジュールされたクエリ] ボタンをクリックします。これにより、現在スケジュールされているクエリのリストが表示されます。表示名をクリックすると、そのクエリのスケジュールの詳細が表示されます。ページの右上にある [バックフィルをスケジュール] をクリックし、過去の日付範囲を指定します。

選択されている実行時間は、日付範囲として選択した開始日から終了日の前日まで適用されます。

日付範囲は UTC 形式で指定しますが、クエリのスケジュールはローカル タイムゾーンで表示されます（この問題に対処する方法については、下記の例 2 をご覧ください）。

従来の BigQuery UI を使用すると、このタイムゾーンの不一致を回避できるだけでなく、きめ細かな時間制限を設定できます。

例 1

スケジュールされたクエリは、太平洋時間の every day 09:00 に実行されるように設定されています。1 月 1 日、1 月 2 日、1 月 3 日のデータがないため、次のように過去の日付範囲を選択します。

Start Time = 1/1/19
End Time = 1/4/19

この場合、次の時間に対応する run_date パラメータと run_time パラメータを使用してクエリが実行されます。

• 2019 年 1 月 1 日の 09:00（太平洋時間）
• 2019 年 1 月 2 日の 09:00（太平洋時間）
• 2019 年 1 月 3 日の 09:00（太平洋時間）

例 2

スケジュールされたクエリは、太平洋時間の every day 23:00 に実行されるように設定されています。1 月 1 日、1 月 2 日、1 月 3 日のデータがないため、次のように過去の日付範囲を選択します（前の例よりも後の日付を選択している理由は、UTC では太平洋時間の 23:00 には日付が変わっているためです）。

Start Time = 1/2/19
End Time = 1/5/19

この場合、次の時間に対応する run_date パラメータと run_time パラメータを使用してクエリが実行されます。

• 2019 年 1 月 2 日の 09:00（UTC）、つまり太平洋時間での 2019 年 1 月 1 日の 23:00
• 2019 年 1 月 3 日の 09:00（UTC）、つまり太平洋時間での 2019 年 1 月 2 日の 23:00
• 2019 年 1 月 4 日の 09:00（UTC）、つまり太平洋時間での 2019 年 1 月 3 日の 23:00

手動実行を設定した後、ページを更新して、実行リストで手動実行を確認します。

従来の UI

[Add] をクリックしてスケジュールされたクエリを保存すると、スケジュールされたクエリの詳細が表示されます。詳細の下にある [Start manual runs] ボタンをクリックし、過去の期間を指定します。

開始時刻と終了時刻を設定して期間をさらに絞り込むことも、時刻フィールドを 00:00:00 のままにしておくこともできます。

例 1

スケジュールされたクエリが every day 14:00 に実行されるように設定され、次の過去の期間を適用するとします。

Start Time = 2/21/2018 00:00:00 AM
End Time = 2/24/2018 00:00:00 AM

クエリは次の時間に実行されます。

• 2/21/2018 14:00:00
• 2/22/2018 14:00:00
• 2/23/2018 14:00:00

例 2

スケジュールされたクエリが every fri at 01:05 に実行されるように設定され、次の過去の期間を適用するとします。

Start Time = 2/1/2018 00:00:00（木曜日）
End Time = 2/24/2018 00:00:00 AM（これも木曜日）

クエリは次の時間に実行されます。

• 2/2/2018 01:05:00
• 2/9/2018 01:05:00

割り当て

スケジュールされたクエリの実行には、作成者自身がクエリを実行しているかのように、作成者の認証情報とプロジェクトが使用されます。スケジュールされたクエリには、クエリジョブに対する BigQuery の割り当てと制限がすべて適用されます。

報告されている問題と制限事項

リージョン

クロスリージョン クエリはサポートされておらず、スケジュールされたクエリの宛先テーブルは、クエリの対象データと同じリージョン内に存在している必要があります。リージョンとマルチリージョンの詳細については、データセットのロケーションをご覧ください。

Google ドライブ

スケジュールされたクエリでは Google ドライブのデータに対してクエリを実行できます。既存のクエリをスケジュールする場合は、スケジュールされたクエリの詳細画面で [Update credentials] のクリックが必要になる場合があります。変更が有効になるまで 10 分から 20 分かかります。ブラウザのキャッシュのクリアが必要になる場合もあります。新たにスケジュールされたクエリでは、認証情報が自動的に最新の状態になります。