クエリのスケジューリング
このページでは、BigQuery で定期的なクエリをスケジュールする方法について説明します。
クエリを定期的に実行するようにスケジュールできます。スケジュールするクエリは、標準 SQL で作成する必要があります。このクエリには、データ定義言語(DDL)とデータ操作言語(DML)のステートメントを含めることができます。クエリ文字列と宛先テーブルはパラメータ化が可能で、クエリ結果を日付と時刻で整理できます。
クエリのスケジュールを作成または更新すると、クエリのスケジュールされた時間は、ローカル時間から UTC に変換されます。UTC は夏時間の影響を受けません。
始める前に
- スケジュールされたクエリは、BigQuery Data Transfer Service の機能を使用します。BigQuery Data Transfer Service を有効にするために必要なすべての操作が完了していることを確認します。
- このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management(IAM)のロールを付与します。
必要な権限
クエリのスケジュールを設定するには、次の IAM 権限が必要です。
転送を作成するには、
bigquery.transfers.update
権限、またはbigquery.jobs.create
権限とbigquery.transfers.get
権限の両方を付与されている必要があります。スケジュール設定されたクエリを実行するには、ターゲット データセットに対する
bigquery.jobs.create
権限とbigquery.datasets.update
権限を付与されている必要があります。
スケジュールされたクエリを変更するには、次の IAM 権限が必要です。
bigquery.jobs.create
bigquery.transfers.update
スケジュールされたクエリを削除するには、次の IAM 権限が必要です。
bigquery.transfers.update
IAM 事前定義ロールの roles/bigquery.admin
には、クエリをスケジュールまたは変更するために必要な権限が含まれています。
BigQuery での IAM のロールの詳細については、事前定義ロールと権限をご覧ください。
サービス アカウントによって実行されるスケジュール設定済みのクエリを作成または更新するには、そのサービス アカウントへのアクセス権が必要です。ユーザーにサービス アカウントのロールを付与する方法については、サービス アカウントのユーザーロールをご覧ください。Cloud Console のスケジュールされたクエリ UI でサービス アカウントを選択するには、次の IAM 権限が必要です。
iam.serviceAccounts.list
設定オプション
クエリ文字列
クエリ文字列は、標準 SQL で記述された有効なものでなければなりません。スケジュールされたクエリは、実行のたびに以下のクエリ パラメータを受け取ることができます。
クエリをスケジュールする前に @run_time
パラメータと @run_date
パラメータを使用してクエリ文字列を手動でテストするには、bq
コマンドライン ツールを使用します。
利用可能なパラメータ
パラメータ | 標準 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 クエリを使用している場合は、Cloud Console で [処理を行うロケーション] またはリージョンを選択します。処理を行うロケーションは、宛先テーブルを作成する DDL または DML クエリに必要です。
宛先テーブルが存在する場合、BigQuery はクエリ結果に基づいて宛先テーブルのスキーマを更新します。ただし、ALLOW_FIELD_ADDITION
を使用して列を追加するか、ALLOW_FIELD_RELAXATION
を使用して列のモードを REQUIRED
から NULLABLE
に緩和する必要があります。そうしないと、実行の間にテーブルのスキーマが変更された場合にスケジュールされたクエリが失敗します。
クエリは、さまざまなプロジェクトやデータセットからテーブルを参照できます。スケジュールされたクエリを構成するときは、テーブル名に宛先データセットを含める必要はありません。宛先データセットは別に指定します。
スケジュール設定されたクエリの宛先データセットとテーブルは、スケジュール設定されたクエリと同じプロジェクト内に存在する必要があります。
書き込み設定
選択した書き込み設定によって、クエリ結果が既存の宛先テーブルに書き込まれる方法が決まります。
WRITE_TRUNCATE
: テーブルが存在する場合、BigQuery によってテーブルのデータが上書きされます。WRITE_APPEND
: テーブルが存在する場合、BigQuery によってデータがテーブルに追加されます。
DDL または DML クエリを使用している場合は、書き込み設定オプションを使用できません。
BigQuery がクエリを正常に完了できる場合にのみ、宛先テーブルの作成、切り捨て、追加が行われます。作成、切り捨て、追加アクションは、ジョブ完了時に 1 つのアトミック更新として発生します。
クラスタリング
スケジュールされたクエリは、DDL CREATE TABLE AS SELECT
ステートメントでテーブルが作成された場合にのみ、新しいテーブルでクラスタリングを作成できます。データ定義言語ステートメントの使用ページのクエリ結果からクラスタ化テーブルを作成するをご覧ください。
パーティショニングのオプション
スケジュールされたクエリでは、分割または非分割の宛先テーブルを作成できます。パーティショニングは、Cloud Console、bq
コマンドライン ツール、API 設定メソッドで使用できます。パーティショニングで DDL または DML クエリを使用する場合は、[Destination table partitioning field] を空白のままにします。
BigQuery には次の 2 種類のテーブル分割があります。
- 取り込み時間パーティション分割テーブル: スケジュールされたクエリの実行時間を基準にして分割されたテーブル。
- 列で分割されたテーブル:
TIMESTAMP
またはDATE
列に基づいて分割されたテーブル。
列で分割されたテーブルの場合は、Cloud Console でスケジュールされたクエリを設定するときに、[Destination table partitioning field] に列名を指定します。
取り込み時間パーティション分割テーブルの場合は、[Destination table partitioning field] を空白のままにして、宛先テーブル名の日付でパーティショニングを行うことを指定します。詳細については、パラメータ テンプレートの構文をご覧ください。
パーティショニングの例
- パーティショニングなしのテーブル
- 宛先テーブル:
mytable
- Partitioning field: 空白のまま
- 宛先テーブル:
- 取り込み時間パーティション分割テーブル
- 宛先テーブル:
mytable_{run_date}
- 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 パラメータの日付(たとえば、2018-01-01 )。この形式は、取り込み時間分割テーブルと互換性があります。 |
テンプレート システム
スケジュールされたクエリは、テンプレート構文で宛先テーブル名におけるランタイム パラメータをサポートします。
パラメータ テンプレート構文
テンプレート構文は、基本的な文字列のテンプレートと時間オフセットをサポートします。パラメータは、次の形式で参照されます。
{run_date}
{run_time[+\-offset]|"time_format"}
パラメータ | 目的 |
---|---|
run_date |
このパラメータは、YYYYMMDD 形式の日付に置き換えられます。 |
run_time |
このパラメータは、次のプロパティをサポートします。
|
- 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+97s|"%H%M%S"} | 20180215_mytable_000137 |
サービス アカウントの使用
サービス アカウントとして認証を行うために、スケジュールされたクエリを設定できます。サービス アカウントは、Google Cloud プロジェクトに関連付けられた Google アカウントです。サービス アカウントは、エンドユーザーの認証情報ではなく、独自のサービス認証情報に関連付けられたジョブを実行できます。たとえば、バッチ処理パイプライン、スケジュールされたクエリなどを実行できます。
サービス アカウントの認証の詳細については、認証の概要をご覧ください。
高度なオプションを使用して、サービス アカウントでスケジュールされたクエリを設定できます。
bq
コマンドライン ツールを使用して、サービス アカウントの認証情報で既存のスケジュールされたクエリを更新できます。詳細については、スケジュールされたクエリの認証情報を更新するをご覧ください。現時点で Cloud Console では、サービス アカウントの認証情報を使用してスケジュールされたクエリを更新できません。
スケジュールされたクエリを設定する
スケジュールの構文の説明については、schedule の書式をご覧ください。
Console
Cloud Console で [BigQuery] ページを開きます。
関心のあるクエリを実行します。結果に問題がなければ、[スケジュール]、[スケジュールされたクエリを新規作成] の順にクリックします。
スケジュールされたクエリのオプションが [新たにスケジュールされたクエリ] パネルに表示されます。
[新たにスケジュールされたクエリ] パネルで次の操作を行います。
- [スケジュールされたクエリの名前] に、クエリの名前(
My scheduled query
など)を入力します。スケジュールされたクエリの名前は、後でクエリの変更が必要になった場合に識別できる任意の名前にできます。 (省略可)デフォルトでは、クエリは毎日実行されます。デフォルトのスケジュール オプションは、次のように変更できます。
- 頻度を変更するには、[繰り返し] オプションを [毎日] から目的の頻度に変更します。カスタム頻度を指定するには、[カスタム] を選択し、[カスタム スケジュール] に Cron と同様の時間指定を入力します(例:
every 3 hours
)。最短許容時間は 15 分です。有効な値の説明については、TransferConfig
のschedule
フィールドをご覧ください。 開始時間を変更するには、[開始時間を選択] オプションを選択し、希望する開始日時を入力して保存します。
終了時間を指定するには、[終了時間を選択] オプションを選択し、希望する終了日時を入力して保存します。
クエリをスケジュールなしで保存して、後でオンデマンドで実行できるようにするには、[繰り返し] オプションとして [オンデマンド] を選択します。
- 頻度を変更するには、[繰り返し] オプションを [毎日] から目的の頻度に変更します。カスタム頻度を指定するには、[カスタム] を選択し、[カスタム スケジュール] に Cron と同様の時間指定を入力します(例:
- [スケジュールされたクエリの名前] に、クエリの名前(
標準 SQL
SELECT
クエリを使用する場合は、[クエリ結果の宛先テーブルを設定する] オプションを選択し、宛先データセットに関する次の情報を入力します。- [データセット名] で、適切な宛先データセットを選択します。
- [テーブル名] に、宛先テーブルの名前を入力します。
- [宛先テーブルの書き込み設定] で、[テーブルに追加する] を選択してデータをテーブルに追加するか、[テーブルを上書きする] を選択して宛先テーブルを上書きします。
DDL クエリと DML クエリの場合は、[処理を行うロケーション](またはリージョン)を選択します。
詳細オプション:
(省略可)CMEK: 顧客管理の暗号鍵を使用する場合は、[詳細オプション] で [顧客管理の暗号鍵] を選択します。使用可能な CMEK のリストが表示され、ここから選択できます。
(省略可)サービス アカウントとして認証: Google Cloud プロジェクトに 1 つ以上のサービス アカウントが関連付けられている場合は、ユーザーの認証情報を使用する代わりに、スケジュールされたクエリをサービス アカウントに関連付けることができます。[スケジュールされたクエリの認証情報] でメニューをクリックすると、利用可能なサービス アカウントの一覧が表示されます。
その他の構成:
(省略可)[メール通知を送信する] をオンにして、転送実行失敗のメール通知を許可します。
(省略可)[Pub/Sub トピック] に、Pub/Sub トピックの名前(例:
projects/myproject/topics/mytopic
)を入力します。
[スケジュール] ボタンをクリックします。
bq
オプション 1: bq query
コマンドを使用する。
スケジュールされたクエリを作成するには、オプション destination_table
(または target_dataset
)、--schedule
、--display_name
を bq query
コマンドに追加します。
bq query \ --display_name=name \ --destination_table=table \ --schedule=interval
以下を置き換えます。
name
。スケジュールされたクエリの表示名。表示名は、後でクエリの変更が必要になった場合に識別できる任意の名前にすることができます。table
。クエリ結果の宛先テーブル。--target_dataset
は、DDL および DML クエリで使用される場合に、クエリ結果のターゲット データセットに名前を付ける代替の方法です。--destination_table
と--target_dataset
のいずれかを使用します。両方を使用することはできません。
interval
。bq query
と使用すると、クエリを定期的に実行するようスケジュールできます。クエリを実行する頻度を指定する必要があります。例:--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' \
--schedule='every 24 hours' \
--replace=true \
'SELECT
1
FROM
mydataset.test'
オプション 2: bq mk
コマンドを使用する。
スケジュールされたクエリは一種の転送です。クエリをスケジュールするには、bq
コマンドライン ツールを使用して転送構成を作成します。
クエリをスケジュールするには、標準 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 \ --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
パラメータは顧客管理の暗号鍵用です。
- スケジュールされたクエリでは、
data_source
。データソース:scheduled_query
。- (省略可)
--service_account_name
パラメータは、個々のユーザー アカウントではなく、サービス アカウントで認証を行う場合に使用します。
たとえば、次のコマンドは、単純なクエリ 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"}' \
--data_source=scheduled_query \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com
コマンドの初回実行時に、次のようなメッセージが表示されます。
[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
リソースのインスタンスを指定します。
Java
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Python
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
サービス アカウントを使用してスケジュールされたクエリを設定する
Java
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Python
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
スケジュールされたクエリのステータスを表示する
Console
スケジュールされたクエリのステータスを確認するには、ナビゲーション ペインで [スケジュールされたクエリ] をクリックします。ページを更新すると、スケジュールされたクエリの最新のステータスが表示されます。詳細を確認するには、スケジュールされたクエリをクリックします。
bq
スケジュールされたクエリは一種の転送です。スケジュールされたクエリの詳細を表示するには、まず bq
コマンドライン ツールを使用して転送構成を一覧表示します。
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
リソースのインスタンスを指定します。
Java
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Python
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
スケジュールされたクエリを更新する
Console
スケジュールされたクエリを更新するには、次の手順を行います。
- ナビゲーション ペインで [スケジュールされたクエリ] をクリックします。
- スケジュールされたクエリのリストで、変更するクエリの名前をクリックします。
- [スケジュールされたクエリの詳細] ページが表示されたら、[編集] をクリックします。
- (省略可)クエリ編集ペインでクエリテキストを変更します。
- [スケジュールされたクエリ] をクリックし、[スケジュールされたクエリを更新] を選択します。
- (省略可)クエリの他のスケジュール オプションを変更します。
- [更新] をクリックします。
bq
スケジュールされたクエリは一種の転送です。スケジュール設定されたクエリを更新するには、bq
コマンドライン ツールを使用して転送構成を作成します。
bq update
コマンドを入力し、次の必須フラグを指定します。
--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 update \ --transfer_config \ --target_dataset=dataset \ --display_name=name \ --params='parameters'
以下を置き換えます。
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
パラメータは、個々のユーザー アカウントではなく、サービス アカウントで認証を行う場合に使用します。
たとえば、次のコマンドは、単純なクエリ SELECT 1
from mydataset.test
を使用して、My Scheduled Query
という名前のスケジュールされたクエリ転送構成を更新します。宛先テーブル mytable
は書き込みごとに切り詰められます。抽出先データセットは mydataset
です。
bq update \
--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
API
projects.transferConfigs.patch
メソッドを使用して、transferConfig.name
パラメータで転送構成のリソース名を指定します。転送のリソース名が不明の場合は、bq ls --transfer_config --transfer_location=location
コマンドを使用してすべての転送を一覧表示するか、projects.locations.transferConfigs.list
メソッドを呼び出して、parent
パラメータでプロジェクト ID を指定します。
Java
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Python
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
スケジュールされたクエリの認証情報を更新する
既存のクエリをスケジュールする場合は、クエリのユーザー認証情報の更新が必要になることがあります。新たにスケジュールされたクエリでは、認証情報が自動的に最新の状態になります。
認証情報の更新が必要になる可能性がある状況としては、次のようなものがあります。
- スケジュールされたクエリでドライブデータをクエリする。
クエリをスケジュールしようとすると、INVALID_USER エラーが発生する。
Error code 5 : Authentication failure: User Id not found. Error code: INVALID_USERID
Console
スケジュールされたクエリの認証情報を更新するには:
[展開] ボタンをクリックして、[認証情報を更新] を選択します。
変更が有効になるまで 10~20 分かかります。ブラウザのキャッシュのクリアが必要になる場合もあります。
bq
スケジュールされたクエリは一種の転送です。スケジュールされたクエリの認証情報を更新するには、bq
コマンドライン ツールを使用して転送構成を更新します。
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 \
Java
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Python
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
過去の日付に基づく手動実行を設定する
今後実行するクエリをスケジュールできるだけでなく、手動でクエリの即時実行をトリガーすることもできます。クエリで 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 日の 06:00(UTC)、つまり太平洋時間での 2019 年 1 月 1 日の 23:00
- 2019 年 1 月 3 日の 06:00(UTC)、つまり太平洋時間での 2019 年 1 月 2 日の 23:00
- 2019 年 1 月 4 日の 06:00(UTC)、つまり太平洋時間での 2019 年 1 月 3 日の 23:00
手動実行を設定した後、ページを更新して、実行リストで手動実行を確認します。
bq
手動で過去の期間でクエリを実行するには:
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
詳細については、bq mk --transfer_run
をご覧ください。
API
projects.locations.transferConfigs.scheduleRun メソッドを使用し、TransferConfig リソースのパスを指定します。
Java
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Python
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
スケジュールされたクエリを削除する
Console
Console で、スケジュールされたクエリを削除するには:
ナビゲーション ペインで [スケジュールされたクエリ] をクリックします。
スケジュール設定されたクエリのリストで、削除するスケジュール設定されたクエリの名前をクリックします。
[スケジュールされたクエリの詳細] ページが表示されたら、[編集] をクリックします。
Java
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Python
BigQuery 用のクライアント ライブラリをインストールして使用する方法については、BigQuery クライアント ライブラリをご覧ください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
割り当て
自分でクエリを実行しているかのように、作成者の認証情報とプロジェクトを使用してスケジュールされたクエリが実行されます。
スケジュールされたクエリは、BigQuery Data Transfer Service の機能を使用しますが、転送ではなく、読み込みジョブの割り当ての対象ではありません。スケジュールされたクエリには、手動クエリと同じ BigQuery の割り当てと上限が適用されます。
料金
スケジュールされたクエリは、手動の BigQuery クエリと同じ料金です。
サポートされるリージョン
スケジュールされたクエリは、次のロケーションでサポートされています。
地域
次の表は、BigQuery が利用可能な南北アメリカのリージョンを示したものです。リージョンの説明 | リージョン名 | 詳細 |
---|---|---|
アイオワ | us-central1 |
|
ラスベガス | us-west4 |
|
ロサンゼルス | us-west2 |
|
モントリオール | northamerica-northeast1 |
|
北バージニア | us-east4 |
|
オレゴン | us-west1 |
|
ソルトレイクシティ | us-west3 |
|
サンパウロ | southamerica-east1 |
|
サンティアゴ | southamerica-west1 |
|
サウスカロライナ | us-east1 |
|
トロント | northamerica-northeast2 |
|
リージョンの説明 | リージョン名 | 詳細 |
---|---|---|
デリー | asia-south2 |
|
香港 | asia-east2 |
|
ジャカルタ | asia-southeast2 |
|
メルボルン | australia-southeast2 |
|
ムンバイ | asia-south1 |
|
大阪 | asia-northeast2 |
|
ソウル | asia-northeast3 |
|
シンガポール | asia-southeast1 |
|
シドニー | australia-southeast1 |
|
台湾 | asia-east1 |
|
東京 | asia-northeast1 |
リージョンの説明 | リージョン名 | 詳細 |
---|---|---|
ベルギー | europe-west1 |
|
フィンランド | europe-north1 |
|
フランクフルト | europe-west3 |
|
ロンドン | europe-west2 |
|
オランダ | europe-west4 |
|
ワルシャワ | europe-central2 |
|
チューリッヒ | europe-west6 |
|
マルチリージョン
次の表に、BigQuery を利用可能なマルチリージョンを示します。マルチリージョンの説明 | マルチリージョン名 |
---|---|
欧州連合の加盟国内のデータセンター1 | EU |
米国内のデータセンター | US |
1 EU
マルチリージョン内のデータは europe-west2
(ロンドン)や europe-west6
(チューリッヒ)のデータセンターには保存されません。
次のステップ
- サービス アカウントを使用し、
@run_date
パラメータと@run_time
パラメータを含むスケジュールされたクエリの例については、スケジュールされたクエリによるテーブル スナップショットの作成をご覧ください。