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

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

概要

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

始める前に

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

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

必要な権限

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

転送を作成するユーザーに、BigQuery で必要な次の権限が付与されていることを確認します。
- 転送を作成するための bigquery.jobs.create 権限または bigquery.transfers.update 権限。
- bigquery.datasets.update（抽出先データセットに対する権限）
bigquery.jobs.create 権限は、事前定義された Cloud IAM のロール bigquery.jobUser に含まれています。BigQuery での Cloud IAM のロールについては、事前定義されたロールと権限をご覧ください。

スケジュールされたクエリを変更する前に、次の項目を行います。

スケジュールされたクエリを変更するユーザーに、BigQuery の次のいずれかの権限があることを確認します。
- bigquery.jobs.create 権限（スケジュールの作成者である必要があります）。
- bigquery.transfers.update 権限。

構成オプション

クエリ文字列

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

クエリをスケジュールする前に @run_time パラメータと @run_date パラメータを使用してクエリ文字列を手動でテストするには、コマンドラインインターフェースを使用します。

利用可能なパラメータ

パラメータ	標準 SQL 型	値
`@run_time`	タイムスタンプ	UTC 時間で表されます。定期的に実行するようスケジュールされたクエリの場合、`run_time` は実行予定時刻を表します。たとえば、スケジュールされたクエリが「24 時間ごと」に設定されている場合、実際の実行時間が多少異なる場合でも、連続する 2 つのクエリ間の `run_time` の差は、ちょうど 24 時間になります。
`@run_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 クエリを使用している場合:

Cloud Console で、[処理を行うロケーション] または [リージョン] を選択します。処理を行うロケーションは、宛先テーブルを作成する DDL または DML クエリに必要です。
従来の BigQuery ウェブ UI では、[Destination table] を空白のままにします。

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

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

書き込み設定

選択した書き込み設定によって、クエリ結果が既存の宛先テーブルに書き込まれる方法が決まります。

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

DDL または DML クエリを使用している場合:

Cloud Console に書き込み設定オプションは表示されません。
従来の BigQuery ウェブ UI では、[Write preference] を空白のままにします。

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

クラスタリング

スケジュールされたクエリは、DDL CREATE TABLE AS SELECT ステートメントでテーブルが作成された場合にのみ、新しいテーブルでクラスタリングを作成できます。データ定義言語ステートメントの使用ページのクエリ結果からクラスタ化テーブルを作成するをご覧ください。

パーティショニングのオプション

スケジュールされたクエリでは、分割または非分割の宛先テーブルを作成できます。Cloud Console ではパーティショニングを使用できませんが、従来の BigQuery ウェブ UI、CLI、API 設定メソッドでは使用できます。パーティショニングで DDL または DML クエリを使用している場合は、[Partitioning field] を空白のままにします。

BigQuery には次の 2 種類のテーブル分割があります。

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

列で分割されたテーブルの場合:

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

取り込み時間パーティション分割テーブルの場合:

宛先テーブルの名前に日付のパーティショニングを示します。下記のテーブル名テンプレートの構文をご覧ください。

パーティショニングの例

パーティショニングなしのテーブル
- 宛先テーブル - mytable
- [Partitioning field] - 空白のまま
取り込み時間パーティション分割テーブル
- 宛先テーブル - mytable$YYYYMMDD
- [Partitioning field] - 空白のまま
列パーティション分割テーブル
- 宛先テーブル - 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_date`	このパラメータは、`YYYYMMDD` 形式の日付に置き換えられます。
`run_time`	このパラメータは、次のプロパティをサポートします。 `offset` タイムオフセットは、時間（h）、分（m）、秒（s）の順序で表されます。日（d）はサポートされていません。小数は使用できます（`1.5h` など）。 `time_format` フォーマット文字列。最も一般的なパラメータの形式は、年（%Y）、月（%m）、日（%d）です。パーティション分割テーブルの場合、YYYYMMDD は必須の接尾辞です。これは「%Y%m%d」と同等です。詳しくは DATETIME でサポートされる形式設定要素をご覧ください。

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_{`run_time+25h\|"%Y%m%d"`}	mytable_20180216
2018-02-15 00:00:00	mytable_{`run_time-1h\|"%Y%m%d"`}	mytable_20180214
2018-02-15 00:00:00	mytable_{`run_time+1.5h\|"%Y%m%d;%H`"} または mytable_{`run_time+90m\|"%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

サービスアカウントの使用

サービスアカウントの認証を行うために、スケジュールされたクエリを設定できます。サービスアカウントは、GCP プロジェクトに関連付けられた Google アカウントです。サービスアカウントは、エンドユーザーの認証情報ではなく、独自のサービス認証情報に関連付けられたジョブを実行できます。たとえば、バッチ処理パイプライン、スケジュールされたクエリなどを実行できます。

サービスアカウントの認証の詳細については、認証の概要をご覧ください。

スケジュールされたクエリの設定の詳細オプションで、サービスアカウントを使用してスケジュールされたクエリを設定するオプションについて説明します。
コマンドラインインターフェース（CLI）で、サービスアカウントの認証情報を使用して、スケジュールされた既存のクエリを更新できます。スケジュールされたクエリの認証情報の更新をご覧ください。
BigQuery ウェブ UI では、サービスアカウントの認証情報を使用してスケジュールされたクエリを更新できません。
従来のウェブ UI では、サービスアカウントを使用してスケジュールされたクエリを作成または更新できません。

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

Console

Cloud Console で BigQuery ウェブ UI を開きます。

Cloud Console に移動する
関心のあるクエリを実行します。結果に問題がなければ、[クエリのスケジュール]、[スケジュールされたクエリを新規作成] の順にクリックします。
スケジュールされたクエリのオプションが [新たにスケジュールされたクエリ] パネルに表示されます。
[新たにスケジュールされたクエリ] パネルで次の操作を行います。
- [スケジュールされたクエリの名前] に、クエリの名前（My scheduled query など）を入力します。スケジュールされたクエリの名前には、後で修正が必要になった場合に簡単に識別できるよう、任意の値を使用できます。
- （省略可）[スケジュールオプション] は、デフォルト値の [毎日]（作成時間に基づいて 24 時間ごと）のままにするか、[開始時刻をスケジュール] をクリックして時間を変更します。間隔を [毎週]、[毎月]、[カスタム] に変更することもできます。[カスタム] を選択すると、every 3 hours のような Cron と同様の時間を指定するよう求められます。最短許容時間は 15 分です。その他の有効な API 値については、TransferConfig の schedule フィールドをご覧ください。
標準 SQL SELECT クエリでは、宛先データセットに関する情報を入力します。
- [データセット名] で、適切な宛先データセットを選択します。
- [テーブル名] に、宛先テーブルの名前を入力します。
  - DDL / DML クエリでは、このオプションは表示されません。
- [宛先テーブルの書き込み設定] で、宛先テーブルを上書きする WRITE_TRUNCATE、または宛先テーブルにデータを追加する WRITE_APPEND のどちらかを選択します。
  - DDL / DML クエリでは、このオプションは表示されません。
（省略可）詳細オプション:
- （省略可）CMEK: 顧客管理の暗号鍵を使用する場合は、[詳細オプション] で [顧客管理の暗号鍵] を選択します。利用できる CMEK のリストが表示され、そこから選択できます。
- （省略可）サービスアカウントを使用した認証: GCP プロジェクトにサービスアカウントが関連付けられている場合、ユーザーの認証情報ではなく、スケジュールされたクエリに関連付けることができます。[スケジュールされたクエリの認証情報] でメニューをクリックすると、利用可能なサービスアカウントの一覧が表示されます。
その他の構成:
- （省略可）[メール通知を送信する] をオンにして、転送実行失敗のメール通知を許可します。
- DDL / DML クエリでは、[処理を行うロケーション] または [リージョン] を選択します。
- （省略可）[Pub/Sub トピック] に、Pub/Sub トピックの名前（例: projects/myproject/topics/mytopic）を入力します。
[スケジュール] ボタンをクリックします。

従来の UI

従来の BigQuery ウェブ UI に移動します。

従来の BigQuery ウェブ UI に移動
関心のあるクエリを実行します。
結果に問題がなければ、[Schedule Query] をクリックします。スケジュールされたクエリのオプションは、クエリボックスの下に表示されます。
[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 クエリの場合、このフィールドを空白のままにします。
- （省略可）顧客管理の暗号鍵を使用する場合は、[Destination table KMS key] に顧客管理の暗号鍵を入力します。
- （省略可）[Schedule] では、デフォルト値の [Daily]（作成時間に基づいて 24 時間ごと）のままにするか、[Edit] をクリックして時間を変更します。間隔を [Weekly]、[Monthly]、[Custom] に変更することもできます。[Custom] を選択すると、every 3 hours のような Cron と同様の時間を指定するよう求められます。最短許容時間は 15 分です。その他の有効な API 値については、TransferConfig の schedule フィールドをご覧ください。
- （省略可）[Advanced] セクションを展開し、[notifications] を構成します。
  - [Pub/Sub topic] に、Pub/Sub トピックの名前（例: projects/myproject/topics/mytopic）を入力します。
  - [Send email notifications] をオンにして、転送実行失敗のメール通知を許可します。
[Add] をクリックします。

CLI

オプション 1: bq queryコマンドを使用する。

この方法では、フラグ destination_table（または target_dataset）、--schedule、--display_name を bq query コマンドに追加して、スケジュールされたクエリを作成します。

bq query \
--display_name=name \
--destination_table=table \
--schedule=interval

ここで

name は、スケジュールされたクエリの表示名です。表示名には、後で修正が必要になった場合にスケジュールされたクエリを簡単に識別できるよう、任意の値を使用できます。
table は、クエリ結果の宛先テーブルです。
- DDL / DML クエリでは、--target_dataset を使ってクエリ結果の抽出先データセットに名前を付けることもできます。
- --destination_table と --target_dataset のいずれかを使用します。両方を使用することはできません。
bq query で interval を使用すると、クエリを定期的に実行するようスケジュールできます。クエリを実行する頻度を指定する必要があります。例:
- --schedule='every 24 hours'
- --schedule='every 3 hours'

オプションフラグ:

--project_id はプロジェクト ID です。--project_id を指定しない場合は、デフォルトのプロジェクトが使用されます。
--replace は、宛先テーブルを切り詰め、スケジュールされたクエリの実行ごとに新しい結果を書き込みます。
--append_table は、結果を宛先テーブルに追加します。

たとえば、次のコマンドは、単純なクエリ SELECT 1 from mydataset.test を使用して、My Scheduled Query という名前のスケジュールされたクエリを作成します。宛先テーブルは、mydataset データセットの mytable です。スケジュールされたクエリは、デフォルトのプロジェクトで作成されます。

    bq query \
    --use_legacy_sql=false \
    --destination_table=mydataset.mytable \
    --display_name='My Scheduled Query' \
    --replace=true \
    'SELECT
      1
    FROM
      mydataset.test'

オプション 2: bq mk コマンドを使用する。

スケジュールされたクエリは一種の転送です。クエリをスケジュールするには、BigQuery Data Transfer Service CLI を使用して転送構成を作成します。

クエリをスケジュールするには、標準 SQL 言語にする必要があります。

bq mk コマンドを入力して、転送作成フラグ --transfer_config を指定します。次のフラグも必要です。

--data_source
--target_dataset（DDL / DML クエリの場合はオプション）
--display_name
--params

オプションフラグ:

--project_id はプロジェクト ID です。--project_id を指定しない場合は、デフォルトのプロジェクトが使用されます。
--schedule は、クエリを実行する頻度です。--schedule が指定されていない場合、デフォルトでは「24 時間ごと」に作成されます。
DDL / DML クエリの場合、--location フラグを指定して、処理する特定のリージョンを指定することもできます。--location が指定されていない場合は、グローバルの Google Cloud のロケーションが使用されます。
--service_account_name は、個々のユーザーアカウントではなく、サービスアカウントを使用してスケジュールされたクエリの認証を行う場合に使用します。注: スケジュールされたクエリでのサービスアカウントの使用はベータ版です。

bq mk \
--transfer_config \
--project_id=project_id \
--target_dataset=dataset \
--display_name=name \
--params='parameters' \
--data_source=data_source

ここで

dataset は、転送構成の抽出先データセットです。
DDL / DML クエリでは、このパラメータはオプションです。他のすべてのクエリでは必須です。

name は、転送構成の表示名です。表示名には、後で修正が必要になった場合にスケジュールされたクエリ（転送）を簡単に識別できるよう、任意の値を使用できます。

parameters には、作成される転送構成のパラメータを JSON 形式で指定します。例: --params='{"param":"param_value"}'

スケジュールされたクエリでは、query パラメータを指定する必要があります。
destination_table_name_template パラメータは、宛先テーブルの名前です。
- DDL / DML クエリでは、このパラメータはオプションです。他のすべてのクエリでは必須です。
write_disposition パラメータには、宛先テーブルを切り詰める（上書きする）WRITE_TRUNCATE、または宛先テーブルにクエリ結果を追加する WRITE_APPEND を選択します。
- DDL / DML クエリでは、このパラメータはオプションです。他のすべてのクエリでは必須です。
（省略可）destination_table_kms_key パラメータは顧客管理の暗号鍵用です。
（省略可）--service_account_name パラメータは、個々のユーザーアカウントではなく、サービスアカウントで認証を行う場合に使用します。

data_source は、データソース scheduled_query です。

たとえば、次のコマンドは、単純なクエリ SELECT 1 from mydataset.test を使用して、My Scheduled Query という名前のスケジュールされたクエリ転送構成を作成します。宛先テーブル mytable は書き込みごとに切り詰められます。抽出先データセットは mydataset です。スケジュールされたクエリはデフォルトプロジェクトに作成され、サービスアカウントで認証されます。

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE","service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com"}' \
--data_source=scheduled_query

コマンドの初回実行時に、次のようなメッセージが表示されます。

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

メッセージの指示に従って、認証コードをコマンドラインに貼り付けます。

API

projects.locations.transferConfigs.create メソッドを使用して、TransferConfig リソースのインスタンスを指定します。

Python

このサンプルを試す前に、BigQuery クイックスタート: クライアントライブラリの使用の Python の設定手順を実施してください。詳細については、BigQuery Python API のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

from google.cloud import bigquery_datatransfer_v1
import google.protobuf.json_format

client = bigquery_datatransfer_v1.DataTransferServiceClient()

# TODO(developer): Set the project_id to the project that contains the
#                  destination dataset.
# project_id = "your-project-id"

# TODO(developer): Set the destination dataset. The authorized user must
#                  have owner permissions on the dataset.
# dataset_id = "your_dataset_id"

# TODO(developer): The first time you run this sample, set the
# authorization code to a value from the URL:
# https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?client_id=433065040935-hav5fqnc9p9cht3rqneus9115ias2kn1.apps.googleusercontent.com&scope=https://www.googleapis.com/auth/bigquery%20https://www.googleapis.com/auth/drive&redirect_uri=urn:ietf:wg:oauth:2.0:oob
#
# authorization_code = "_4/ABCD-EFGHIJKLMNOP-QRSTUVWXYZ"
#
# You can use an empty string for authorization_code in subsequent runs of
# this code sample with the same credentials.
#
# authorization_code = ""

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = client.project_path(project_id)

transfer_config = google.protobuf.json_format.ParseDict(
    {
        "destination_dataset_id": dataset_id,
        "display_name": "Your Scheduled Query Name",
        "data_source_id": "scheduled_query",
        "params": {
            "query": query_string,
            "destination_table_name_template": "your_table_{run_date}",
            "write_disposition": "WRITE_TRUNCATE",
            "partitioning_field": "",
        },
        "schedule": "every 24 hours",
    },
    bigquery_datatransfer_v1.types.TransferConfig(),
)

response = client.create_transfer_config(
    parent, transfer_config, authorization_code=authorization_code
)

print("Created scheduled query '{}'".format(response.name))

スケジュールされたクエリのステータスの表示

ウェブ UI

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

スケジュールされたクエリを一覧表示します。

従来の UI

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

スケジュールされたクエリを一覧表示します。

CLI

スケジュールされたクエリは一種の転送です。スケジュールされたクエリの詳細を表示するには、BigQuery Data Transfer Service CLI を使用して転送構成のリストを取得します。

bq ls コマンドを入力して、転送フラグ --transfer_config を指定します。次のフラグも必要です。

--transfer_location

例:

bq ls \
--transfer_config \
--transfer_location=us \

スケジュールされた単純なクエリの詳細を表示するには、bq show コマンドを入力し、transfer_path スケジュールされたクエリまたは転送構成のパスを指定します。

例:

bq show \
--transfer_config \
projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38 \

API

projects.locations.transferConfigs.list メソッドを使用して、TransferConfig リソースのインスタンスを指定します。

スケジュールされたクエリの認証情報を更新する

ウェブ UI

スケジュールされたクエリの認証情報を更新するには:

スケジュールされたクエリのステータスを確認します。
[展開] ボタンをクリックして、[認証情報を更新] を選択します。

現在ウェブ UI では、スケジュールされたクエリで使用される認証情報をサービスアカウントに変更することはできません。

従来の UI

スケジュールされたクエリのステータスを確認します。
リストで、スケジュールされたクエリをクリックします。スケジュールされたクエリの詳細の下に [Update credentials] ボタンが表示されます。

CLI

スケジュールされたクエリは一種の転送です。スケジュールされたクエリの認証情報を更新するには、BigQuery Data Transfer Service CLI を使用して転送構成を更新します。

bq update コマンドを入力して、転送フラグ --transfer_config を指定します。次のフラグも必要です。

--update_credentials

オプションフラグ:

--service_account_name は、個々のユーザーアカウントではなく、サービスアカウントを使用してスケジュールされたクエリの認証を行う場合に使用します。

たとえば、次のコマンドは、サービスアカウントで認証を行うように、スケジュールされたクエリの転送構成を更新します。

bq update \
--transfer_config \
--update_credentials \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38 \

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

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

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

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

Console

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

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

過去の日付を設定する

例 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

CLI

手動で過去の期間でクエリを実行するには:

bq mk コマンドを入力して、転送実行フラグ --transfer_run を指定します。次のフラグも必要です。

--start_time
--end_time

bq mk \
--transfer_run \
--start_time='start_time' \
--end_time='end_time' \
resource_name

ここで

start_time と end_time は、Z で終わるタイムスタンプか、有効なタイムゾーンのオフセットを含むタイムスタンプです。例:
- 2017-08-19T12:11:35.00Z
- 2017-05-25T00:00:00+00:00
resource_name は、スケジュールされたクエリ（または転送）のリソース名です。リソース名は、転送構成とも呼ばれます。

たとえば、コマンド projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7 は、スケジュールされたクエリリソース（または転送構成）のバックフィルをスケジュールします。

  bq mk \
  --transfer_run \
  --start_time 2017-05-25T00:00:00Z \
  --end_time 2017-05-25T00:00:00Z \
  projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

projects.locations.transferConfigs.scheduleRun メソッドを使用し、TransferConfig リソースのパスを指定します。

割り当て

自分でクエリを実行しているかのように、作成者の認証情報とプロジェクトを使用してスケジュールされたクエリが実行されます。スケジュールされたクエリには、手動クエリと同じ BigQuery の割り当てと上限が適用されます。

料金

スケジュールされたクエリは、手動の BigQuery クエリと同じ料金です。

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

リージョン

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

Google ドライブ

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

認証情報の更新

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

概要

始める前に

必要な権限

構成オプション

クエリ文字列

利用可能なパラメータ

例

宛先テーブル

書き込み設定

クラスタリング

パーティショニングのオプション

パーティショニングの例

利用可能なパラメータ

テンプレート システム

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

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

サービス アカウントの使用

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

Console

従来の UI

CLI

API

Python

スケジュールされたクエリのステータスの表示

ウェブ UI

従来の UI

CLI

API

スケジュールされたクエリの認証情報を更新する

ウェブ UI

従来の UI

CLI

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

Console

従来の UI

CLI

API

割り当て

料金

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

リージョン

Google ドライブ

テンプレートシステム

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

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

サービスアカウントの使用