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

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

は、

ベータ版 です。

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

概要

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

始める前に

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

• スケジュールされたクエリは、BigQuery Data Transfer Service の機能を使用します。BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。
• 次の必要な権限が付与されていることを確認します。
  • BigQuery: スケジュールされた転送を作成するための bigquery.transfers.update 権限。bigquery.transfers.update 権限は、事前定義されたプロジェクト レベルの IAM 役割 bigquery.admin に含まれています。BigQuery での IAM 役割の詳細については、アクセス制御をご覧ください。
• 権限ウィンドウが表示されるように、bigquery.cloud.google.com からのポップアップをブラウザで許可します。スケジュールされたクエリを管理する権限を、BigQuery Data Transfer Service に付与する必要があります。

構成オプション

クエリ文字列

クエリ文字列が有効で、標準 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. [スケジュール] をクリックします。

従来の 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] には、projects/myproject/topics/mytopic のような Cloud Pub/Sub トピック名を入力します。

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

       

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

マニュアル実行を過去の日付に設定する

将来実行するクエリのスケジューリングだけでなく、指定した期間内の過去のデータに対してクエリが実行されるように設定することもできます。指定した期間内で、スケジュールされたクエリの作成時に指定したのと同じ時刻にクエリが実行されます。

スケジュールされたクエリを設定した後、過去の期間内でクエリを実行できます。

Console

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

開始時刻と終了時刻を設定して期間をさらに絞り込むことも、時刻フィールドを 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

従来の 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 分かかります。ブラウザのキャッシュのクリアが必要になる場合もあります。新たにスケジュールされたクエリでは、認証情報が自動的に最新の状態になります。