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

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

は、

ベータ版 です。

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

概要

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

始める前に

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

• スケジュールされたクエリは、BigQuery Data Transfer Service の機能を使用します。BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。
• 次の必要な権限があることを確認します。
  • BigQuery: スケジュールされた転送を作成するための bigquery.transfers.update 権限。bigquery.transfers.update 権限は、bigquery.admin で事前定義されたプロジェクト レベルの IAM 役割に含まれています。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

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

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] に変更することもできます。[Custom] を選択したときは、Cron と同様の時間指定（例: every 3 hours）が求められます。最短許容時間は 3 時間です。有効な追加 API 値については、TransferConfig の schedule フィールドをご覧ください。

     

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

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

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

       

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

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

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

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

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