ジョブの管理

BigQuery ジョブの送信後に、ジョブデータの表示、ジョブの一覧表示、ジョブのキャンセル、ジョブの再実行を行えます。

ジョブが送信されると、次の 3 つの状態のいずれかになります。

PENDING - スケジュール済み
RUNNING
DONE - SUCCESS または FAILURE（ジョブがエラーを伴って完了した場合）として報告

ジョブデータの表示

GCP Console、従来のウェブ UI、CLI、および API を使用して、ジョブデータおよびメタデータを表示できます。このデータには、ジョブタイプ、ジョブの状態、ジョブを実行したユーザーなどの詳細情報が含まれます。

必要な権限

ジョブデータとメタデータを取得するユーザーには、少なくとも bigquery.jobs.get 権限が付与されている必要があります。bigquery.jobs.get 権限は、次の事前定義された Cloud IAM 役割に含まれています。

bigquery.admin

アカウントに bigquery.admin 役割を付与すると、そのユーザーは誰がジョブを送信したかに関係なく、プロジェクト内のすべてのジョブデータを表示できます。

次の役割には、自己作成ジョブに対する bigquery.jobs.get 権限が付与されています。これらのユーザーは、自分が送信したジョブのジョブデータのみを表示できます。

bigquery.user
bigquery.jobUser

BigQuery での Cloud IAM 役割と権限については、アクセス制御をご覧ください。

ジョブに関する情報の表示

ジョブに関する情報を表示するには:

Console

ナビゲーションパネルで、[ジョブ履歴] をクリックするか、[クエリ履歴] をクリックして、クエリジョブに関する情報を表示します。
[個人履歴] をクリックして、ジョブの詳細を表示します。[プロジェクト履歴] をクリックして、プロジェクトで実行されたすべてのジョブに関する詳細を表示します。

従来の UI

ナビゲーションパネルで、[Job history] をクリックするか、[Query history] をクリックして、クエリジョブに関する情報を表示します。
[Recent Jobs] セクションで、詳細を表示するジョブをクリックします。クエリジョブの場合は、[Query history] タブをクリックして、クエリジョブの詳細を表示します。

CLI

-j フラグおよび job_id パラメータを指定して bq show コマンドを発行します。

ジョブ ID を指定するときは、完全修飾 ID を使用することも、短縮形を使用することもできます。たとえば、BigQuery ウェブ UI に一覧表示されているジョブ ID は完全修飾 ID であり、プロジェクトとロケーションが含まれています。

my-project-1234:US.bquijob_123x456_123y123z123c

コマンドラインツールのジョブ ID は短縮形で一覧表示されます。プロジェクト ID とロケーションは含まれません。

bquijob_123x456_123y123z123c

ジョブのロケーションを指定するには、--location フラグを指定し、その値を該当するロケーションに設定します。完全修飾ジョブ ID を使用する場合、このフラグの指定は任意です。--location フラグを指定した場合に、完全修飾ジョブ ID を使用すると、--location フラグは無視されます。

次のコマンドは、ジョブに関する情報をリクエストします。

bq --location=location show -j job_id

ここで

location は省略可能です。location は、ジョブが実行されるロケーションの名前です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
job_id はジョブの ID です。

例:

次のコマンドは、myproject で実行されているジョブ US.bquijob_123x456_123y123z123c の概要を取得します。

bq show -j myproject:US.bquijob_123x456_123y123z123c

出力は次のようになります。

 Job Type    State      Start Time      Duration      User Email       Bytes Processed   Bytes Billed   Billing Tier   Labels
 ---------- --------- ----------------- ---------- ------------------- ----------------- -------------- -------------- --------
 extract    SUCCESS   06 Jul 11:32:10   0:01:41    user@example.com

ジョブの詳細を表示するには、次のように入力します。

bq show --format=prettyjson -j myproject:US.bquijob_123x456_789y123z456c

出力は次のようになります。

{
  "configuration": {
    "extract": {
      "compression": "NONE",
      "destinationUri": "[URI removed]",
      "destinationUris": [
        "[URI removed]"
      ],
      "sourceTable": {
        "datasetId": "github_repos",
        "projectId": "bigquery-public-data",
        "tableId": "commits"
      }
    }
  },
  "etag": "\"[etag removed]\"",
  "id": "myproject:bquijob_123x456_789y123z456c",
  "jobReference": {
    "jobId": "bquijob_123x456_789y123z456c",
    "projectId": "[Project ID removed]"
  },
  "kind": "bigquery#job",
  "selfLink": "https://www.googleapis.com/bigquery/v2/projects/federated-testing/jobs/bquijob_123x456_789y123z456c",
  "statistics": {
    "creationTime": "1499365894527",
    "endTime": "1499365894702",
    "startTime": "1499365894702"
  },
  "status": {
    "errorResult": {
      "debugInfo": "[Information removed for readability]",
      "message": "Operation cannot be performed on a nested schema. Field: author",
      "reason": "invalid"
    },
    "errors": [
      {
        "message": "Operation cannot be performed on a nested schema. Field: author",
        "reason": "invalid"
      }
    ],
    "state": "DONE"
  },
  "user_email": "user@example.com"
}

API

jobs.get を呼び出して、jobId パラメータと projectId パラメータを渡します。（省略可）location パラメータを指定して、その値としてジョブを実行するロケーションを設定します。my-project-1234:US.bquijob_123x456_123y123z123c のように、ロケーションを含む完全修飾ジョブ ID を使用する場合、このパラメータは省略可能です。

Go

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

GitHub で表示フィードバック

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
job, err := client.JobFromID(ctx, jobID)
if err != nil {
	return err
}

status := job.LastStatus()
state := "Unknown"
switch status.State {
case bigquery.Pending:
	state = "Pending"
case bigquery.Running:
	state = "Running"
case bigquery.Done:
	state = "Done"
}
fmt.Printf("Job %s was created %v and is in state %s\n",
	jobID, status.Statistics.CreationTime, state)

Python

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

GitHub で表示フィードバック

# TODO(developer): Uncomment the lines below and replace with your values.
# from google.cloud import bigquery
# client = bigquery.Client()
# job_id = 'bq-job-123x456-123y123z123c'  # replace with your job ID
# location = 'us'                         # replace with your location

job = client.get_job(job_id, location=location)  # API request

# Print selected job properties
print("Details for job {} running in {}:".format(job_id, location))
print(
    "\tType: {}\n\tState: {}\n\tCreated: {}".format(
        job.job_type, job.state, job.created
    )
)

プロジェクト内のジョブの一覧表示

プロジェクトには、過去 6 か月間に作成されたすべてのジョブの履歴が保持されています。50 日以上経過したジョブの自動削除をリクエストするには、サポートにお問い合わせください。

BigQuery のジョブ履歴は、次の方法で表示できます。

Google Cloud Platform Console または従来のウェブ UI の使用
CLI の使用
jobs.list API メソッドの呼び出し
クライアントライブラリの使用

ジョブ履歴には、RUNNING 状態のジョブと、DONE になっているジョブが含まれます（これらは SUCCESS 状態または FAILURE 状態として報告されます）。

必要な権限

ジョブを一覧表示するユーザーには、少なくとも bigquery.jobs.list 権限が付与されている必要があります。bigquery.jobs.list 権限は、以下の事前定義された Cloud IAM 役割に含まれています。

bigquery.user
bigquery.admin

次の役割では、自己作成ジョブのみに対する bigquery.jobs.list 権限が付与されます。この役割を付与されたエンティティは、エンティティ自身が送信したジョブのみを一覧表示できます。

bigquery.jobUser

bigquery.jobs.list 権限が付与されている場合、プロジェクト内のすべてのジョブを一覧表示できますが、他のユーザーから送信されたジョブについては、詳細とメタデータが除去されます。bigquery.jobs.list 権限により、自己作成ジョブの詳細を確認できます。

他のユーザーが作成したジョブの詳細など、すべてのジョブを一覧表示するには、bigquery.jobs.listAll 権限が必要です。bigquery.jobs.listAll 権限があるのは bigquery.admin 役割だけです。

BigQuery での Cloud IAM 役割と権限については、アクセス制御をご覧ください。

ジョブの一覧表示

プロジェクトでジョブを一覧表示する際に、ロケーションを指定する必要はありません。現在のところ、すべてのロケーションのジョブが一覧表示されます。

プロジェクト内のジョブを一覧表示するには:

Console

ナビゲーションペインで [ジョブ履歴] をクリックします。
[個人履歴] セクションに、最新のジョブを先頭として作成日時順にジョブが一覧表示されます。この一覧では、現在のユーザーのジョブだけが表示されます。プロジェクトのすべてのジョブを表示するには、[プロジェクト履歴] をクリックします（プロジェクトオーナーでなければ、プロジェクトのすべてのジョブを表示する権限はありません）。

従来の UI

ナビゲーションペインで [Job History] をクリックします。
[Recent Jobs] セクションに、作成日時順にジョブが一覧表示され、最新のジョブが一番上に表示されます。この一覧では、現在のユーザーのジョブだけが表示されます。すべてのジョブを表示するには、コマンドラインツールまたは API を使用します。

CLI

次のいずれかのフラグを付けて bq ls コマンドを発行します。

-j は、一覧表示するリソースとしてジョブを識別するために使用されます。
--all または -a を指定すると、すべてのユーザーのジョブが一覧表示されます。すべてのジョブの完全な詳細を表示するには、bigquery.jobs.listAll 権限が必要です。
--min_creation_time を使用すると、タイムスタンプの値を指定して、そのタイムスタンプ以降のジョブを一覧表示できます。
--max_creation_time を使用すると、タイムスタンプの値を指定して、そのタイムスタンプ以前のジョブを一覧表示できます。
-n は結果を制限します。デフォルトでは、結果は 100,000 件に制限されています。

bq ls -j -a \
--min_creation_time integer1 \
--max_creation_time integer2 \
-n integer3 \
project_id

ここで

integer1 は、タイムスタンプを表す整数です。
integer2 は、タイムスタンプを表す整数です。
integer3 は、取得するジョブの数を指定する整数です。
project_id は、一覧表示するジョブが含まれているプロジェクトの ID です。デフォルトプロジェクトを設定している場合、project_id パラメータを指定する必要はありません。

例:

次のコマンドは、現在のユーザーのすべてのジョブを一覧表示します。このコマンドを実行するには、bigquery.jobs.list 権限が必要です。

bq ls -j myproject

次のコマンドは、すべてのユーザーのすべてのジョブを一覧表示します。このコマンドを実行するには、bigquery.jobs.listAll 権限が必要です。

bq ls -j -a myproject

次のコマンドは、myproject の最新の 10 個のジョブを一覧表示します。

bq ls -j -a -n 10 myproject

次のコマンドは、2018 年 10 月 18 日午後 4:04:53 より前に送信されたすべてのジョブを一覧表示します。このタイムスタンプ（ミリ秒数）に該当するのは、整数 1539903893000 です。

bq ls -j --max_creation_time 1539903893000

API

jobs.list を呼び出して、projectId パラメータを指定します。すべてのユーザーのジョブを一覧表示するには、allUsers パラメータを true に設定します。allUsers を true に設定するには、bigquery.jobs.listAll 権限が必要です。

Go

GitHub で表示フィードバック

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
it := client.Jobs(ctx)
for i := 0; i < 10; i++ {
	j, err := it.Next()
	if err == iterator.Done {
		break
	}
	if err != nil {
		return err
	}
	state := "Unknown"
	switch j.LastStatus().State {
	case bigquery.Pending:
		state = "Pending"
	case bigquery.Running:
		state = "Running"
	case bigquery.Done:
		state = "Done"
	}
	fmt.Printf("Job %s in state %s\n", j.ID(), state)
}

Java

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

GitHub で表示フィードバック

Page<Job> jobs = bigquery.listJobs(JobListOption.pageSize(100));
for (Job job : jobs.iterateAll()) {
  // do something with the job
}

Python

GitHub で表示フィードバック

# TODO(developer): Uncomment the lines below and replace with your values.
# from google.cloud import bigquery
# project = 'my_project'  # replace with your project ID
# client = bigquery.Client(project=project)
import datetime

# List the 10 most recent jobs in reverse chronological order.
# Omit the max_results parameter to list jobs from the past 6 months.
print("Last 10 jobs:")
for job in client.list_jobs(max_results=10):  # API request(s)
    print(job.job_id)

# The following are examples of additional optional parameters:

# Use min_creation_time and/or max_creation_time to specify a time window.
print("Jobs from the last ten minutes:")
ten_mins_ago = datetime.datetime.utcnow() - datetime.timedelta(minutes=10)
for job in client.list_jobs(min_creation_time=ten_mins_ago):
    print(job.job_id)

# Use all_users to include jobs run by all users in the project.
print("Last 10 jobs run by all users:")
for job in client.list_jobs(max_results=10, all_users=True):
    print("{} run by user: {}".format(job.job_id, job.user_email))

# Use state_filter to filter by job state.
print("Jobs currently running:")
for job in client.list_jobs(state_filter="RUNNING"):
    print(job.job_id)

ジョブのキャンセル

次の方法で、RUNNING または PENDING のジョブをキャンセルできます。

GCP Console または従来のウェブ UI の使用
CLI の使用
jobs.cancel API メソッドの呼び出し
クライアントライブラリの使用

すべてのジョブタイプをキャンセルできるわけではありません。ジョブをキャンセルできない場合は、エラーが返されます。

ジョブをキャンセルできる場合でも、キャンセルが成功する保証はありません。キャンセルリクエストが送信されるまでにジョブがすでに完了している場合や、ジョブがキャンセルできない段階に到達している場合などがあります。

必要な権限

ジョブをキャンセルするユーザーには、少なくとも bigquery.jobs.update 権限が付与されている必要があります。bigquery.jobs.update 権限は、次の事前定義された Cloud IAM 役割に含まれています。

bigquery.admin

アカウントに bigquery.admin 役割を付与すると、そのユーザーは誰がジョブを送信したかに関係なく、プロジェクト内のすべてのジョブデータをキャンセルできます。

次の役割では、自己作成ジョブをキャンセルできます。これらのユーザーは、自分が送信したジョブのみをキャンセルできます。

bigquery.user
bigquery.jobUser

BigQuery での Cloud IAM 役割と権限については、アクセス制御をご覧ください。

ジョブのキャンセル

ジョブをキャンセルするには:

Console

ナビゲーションペインで [ジョブ履歴] をクリックします。
[個人履歴] セクションで、キャンセルするジョブをクリックします。最新のジョブがリストの一番上に表示されます。
ジョブの詳細で [ジョブをキャンセル] をクリックします。

従来の UI

ナビゲーションペインで [Job History] をクリックします。
[Recent Jobs] セクションで、キャンセルするジョブをクリックします。最新のジョブがリストの一番上に表示されます。
ジョブの詳細で [Cancel Job] をクリックします。

CLI

job_id パラメータを指定して bq cancel コマンドを実行します。キャンセルをリクエストしてすぐに戻るには、--nosync フラグを使用します。デフォルトでは、キャンセルリクエストが完了するまで待機します。

my-project-1234:US.bquijob_123x456_123y123z123c

コマンドラインツールのジョブ ID は短縮形で一覧表示されます。プロジェクト ID とロケーションは含まれません。

bquijob_123x456_123y123z123c

次のコマンドはジョブのキャンセルをリクエストし、リクエストが完了するまで待機します。完全修飾ジョブ ID が指定されている場合、--location フラグは無視されます。

bq --location=location cancel job_id

次のコマンドはジョブのキャンセルをリクエストし、即時に戻ります。完全修飾ジョブ ID が指定されている場合、--location フラグは無視されます。

bq --location=location --nosync cancel job_id

ここで

location は省略可能です。location は、ジョブが実行されるロケーションの名前です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
job_id は、キャンセルするジョブの ID です。BigQuery ウェブ UI からジョブ ID をコピーする場合、ジョブ ID にはプロジェクト ID とロケーションが含まれます（例: my-project-1234:US.bquijob_123x456_123y123z123c）。

例:

次のコマンドは、US マルチリージョンロケーションの my-project-1234 で実行中のジョブ my-project-1234:US.bquijob_123x456_123y123z123c をキャンセルし、リクエストが完了するまで待機します。完全修飾ジョブ ID が使用されているため、location フラグは指定されていません。

bq cancel my-project-1234:US.bquijob_123x456_123y123z123c

次のコマンドは、US マルチリージョンロケーションの my-project-1234 で実行中のジョブ bquijob_123x456_123y123z123c をキャンセルし、リクエストが完了するまで待機します。短縮形のジョブ ID が使用されているため、--location フラグが指定されています。

bq --location=US cancel bquijob_123x456_123y123z123c

次のコマンドは、US マルチリージョンロケーションの my-project-1234 で実行中のジョブ bquijob_123x456_123y123z123c をキャンセルし、即時に戻ります。完全修飾ジョブ ID が使用されているため、--location フラグは指定されていません。

bq --nosync cancel my-project-1234:US.bquijob_123x456_123y123z123c

API

jobs.cancel を呼び出し、jobId パラメータと projectId パラメータを指定します。location パラメータを指定して、その値としてジョブを実行するロケーションを設定します。

Go

GitHub で表示フィードバック

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
job, err := client.JobFromID(ctx, jobID)
if err != nil {
	return nil
}
return job.Cancel(ctx)

Python

GitHub で表示フィードバック

# TODO(developer): Uncomment the lines below and replace with your values.
# from google.cloud import bigquery
# client = bigquery.Client()
# job_id = 'bq-job-123x456-123y123z123c'  # replace with your job ID
# location = 'us'                         # replace with your location

job = client.cancel_job(job_id, location=location)

ジョブの繰り返し

同じジョブ ID を使用してジョブを再実行することはできません。代わりに、同じ構成で新しいジョブを作成します。GCP Console、従来のウェブ UI、または CLI で新しいジョブを送信すると、新しいジョブ ID が割り当てられます。API またはクライアントライブラリを使用してジョブを送信する場合は、新しいジョブ ID を生成する必要があります。

必要な権限

ジョブを実行するには、少なくとも bigquery.jobs.create 権限を付与されている必要があります。bigquery.jobs.create 権限は、以下の事前定義された Cloud IAM 役割に含まれています。

bigquery.user
bigquery.jobUser
bigquery.admin

BigQuery での Cloud IAM 役割と権限については、アクセス制御をご覧ください。

ジョブの再実行

ジョブを繰り返すには:

Console

クエリジョブを繰り返すには:

ナビゲーションペインで [クエリ履歴] をクリックします。
[個人履歴] または [プロジェクト履歴] のセクションで、再実行するクエリをクリックし、[クエリをエディタで開く] をクリックします。
[実行] をクリックします。

読み込みジョブを繰り返すには:

ナビゲーションペインで [ジョブ履歴] をクリックします。
[個人履歴] または [プロジェクト履歴] のセクションで、繰り返したいジョブをクリックします。最新のジョブがリストの一番上に表示されます。
ジョブの詳細で、[読み込みジョブを繰り返す] をクリックします。

注: エクスポートジョブやコピージョブは、GCP Console を使用して繰り返すことはできません。

従来の UI

クエリジョブを繰り返すには:

ナビゲーションペインで [Query History] をクリックします。
クエリの右側にある [Queries] セクションで、[Open Query] をクリックします。
[Run Query] をクリックします。

読み込みジョブを繰り返すには:

ナビゲーションペインで [Job History] をクリックします。
[Recent Jobs] セクションで、繰り返すジョブをクリックします。最新のジョブがリストの一番上に表示されます。
ジョブの詳細で、[Repeat Load Job] をクリックします。

注: エクスポートジョブやコピージョブは、ウェブ UI を使用して繰り返すことはできません。

CLI

コマンドをもう一度実行すると、BigQuery が自動的にジョブを生成し、新しいジョブ ID が割り当てられます。

API

ジョブを繰り返す単一の呼び出しメソッドはありません。特定のジョブを繰り返すには、次のようにします。

jobs.get を呼び出して、繰り返すジョブのリソースを取得します。
id、status、statistics の各フィールドを削除します。クライアントコードによって生成された新しいジョブ ID を、jobId フィールドに設定します。必要に応じて他のフィールドを変更します。
変更したリソースと新しいジョブ ID を使用して jobs.insert を呼び出し、新しいジョブを開始します。

ジョブデータの表示

必要な権限

ジョブに関する情報の表示

Console

従来の UI

CLI

API

Go

Python

プロジェクト内のジョブの一覧表示

必要な権限

ジョブの一覧表示

Console

従来の UI

CLI

API

Go

Java

Python

ジョブのキャンセル

必要な権限

ジョブのキャンセル

Console

従来の UI

CLI

API

Go

Python

ジョブの繰り返し

必要な権限

ジョブの再実行

Console

従来の UI

CLI

API

フィードバックを送信...