管理作业

提交 BigQuery 作业之后，您可以查看作业数据、列出作业、取消作业或重新运行作业。

作业提交后，可能处于以下三种状态之一：

PENDING：已安排
RUNNING
DONE：报告为 SUCCESS 或 FAILURE（如果作业已完成，但发生错误）

查看作业数据

您可以使用 Cloud Console、经典版网页界面、命令行界面和 API 查看作业数据和元数据。此类数据包括作业类型、作业状态和运行作业的用户等详细信息。

所需权限

如需获取作业数据和元数据，您至少必须具有 bigquery.jobs.get 权限。以下预定义的 Cloud IAM 角色可提供 bigquery.jobs.get 权限：

bigquery.admin

如果您向某个帐号授予 bigquery.admin 角色，则该用户可以查看项目中的所有作业数据，无论作业的提交者是谁。

以下角色仅对自己创建的作业具有 bigquery.jobs.get 权限。此类用户只能查看自己提交的作业的数据：

bigquery.user
bigquery.jobUser

如需详细了解 BigQuery 中的 Cloud IAM 角色和权限，请参阅访问权限控制。

查看有关作业的信息

要查看有关作业的信息，请执行以下操作：

控制台

在导航窗格中，点击作业记录，或点击查询记录以查看有关查询作业的信息。
点击个人记录以查看有关作业的详细信息。点击项目记录以查看有关项目中运行的所有作业的详细信息。

经典版界面

在导航窗格中，点击 Job History，或点击 Query history 以查看有关查询作业的信息。
在 Recent Jobs 部分，点击作业以查看详细信息。对于查询作业，点击 Query history 标签页以查看查询作业详细信息。

bq

发出带有 -j 标志和作业 ID 参数的 bq show 命令。

提供作业 ID 时，您可以使用完全限定的 ID 或者简写形式。例如，BigQuery 网页界面中列出的作业 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 为可选项。位置是运行作业的位置的名称。例如，如果您在东京区域使用 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 参数并将值设置为运行作业的位置。如果使用的是包含位置的完全限定作业 ID（例如 my-project-1234:US.bquijob_123x456_123y123z123c），则此参数为可选项。

Go

在尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 BigQuery Go API 参考文档。

在 GitHub 上查看反馈

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// getJobInfo demonstrates retrieval of a job, which can be used to monitor
// completion or print metadata about the job.
func getJobInfo(w io.Writer, projectID, jobID string) error {
	// projectID := "my-project-id"
	// jobID := "my-job-id"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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.Fprintf(w, "Job %s was created %v and is in state %s\n",
		jobID, status.Statistics.CreationTime, state)
	return nil
}

Node.js

在尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

在 GitHub 上查看反馈

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getJob() {
  // Get job properties.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const jobId = "existing-job-id";

  // Create a job reference
  const job = bigquery.job(jobId);

  // Retrieve job
  const [jobResult] = await job.get();

  console.log(jobResult.metadata.jobReference);
}

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 Console 或经典版网页界面
使用命令行界面
调用 jobs.list API 方法
使用客户端库

此作业记录包含状态为 RUNNING 和 DONE（通过报告状态为 SUCCESS 或 FAILURE 来表示）的作业。

所需权限

如需列出作业，您至少必须具有 bigquery.jobs.list 权限。以下预定义的 Cloud IAM 角色具有 bigquery.jobs.list 权限：

bigquery.user
bigquery.admin

以下角色仅对自己创建的作业具有 bigquery.jobs.list 权限。获得此角色的实体只能列出他们提交的作业：

bigquery.jobUser

获得 bigquery.jobs.list 权限后，您可以列出项目中的所有作业，但系统会遮盖其他用户提交的作业的详细信息和元数据。您可以通过 bigquery.jobs.list 权限查看自己创建的作业的全部详细信息。

要列出所有作业（包括其他用户创建的作业的详细信息），您必须具有 bigquery.jobs.listAll 权限。只有 bigquery.admin 角色具有 bigquery.jobs.listAll 权限。

如需详细了解 BigQuery 中的 Cloud IAM 角色和权限，请参阅预定义的角色和权限。

列出作业

列出项目中的作业时，无需提供位置信息。目前，系统会列出所有位置的作业。

要列出项目中的作业，请执行以下操作：

控制台

在导航窗格中，点击作业记录。
在个人记录部分中，作业按创建时间列出，最新作业位于顶部。该列表仅包含当前用户的作业。要查看项目的所有作业，请点击项目记录。（如果您不是项目所有者，则可能无权查看项目的所有作业）。

经典版界面

在导航窗格中，点击 Job History。
在 Recent Jobs 部分，您的作业将按创建时间列出，最新作业位于顶部。该列表仅包含当前用户的作业。要查看所有作业，请使用命令行工具或 API。

bq

发出带有以下标志之一的 bq ls 命令：

-j：用于将作业标识为要列出的资源。
--all 或 -a：用于列出来自所有用户的作业。要查看所有作业的全部（未遮盖）详细信息，您必须具有 bigquery.jobs.listAll 权限。
--min_creation_time：用于列出在提供的时间戳值之后提交的作业。
--max_creation_time：用于列出在提供的时间戳值之前提交的作业。
-n：用于限制结果。默认情况下，结果数上限为 10 万个。

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

在尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 BigQuery Go API 参考文档。

在 GitHub 上查看反馈

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// listJobs demonstrates iterating through the BigQuery jobs collection.
func listJobs(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	// jobID := "my-job-id"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	it := client.Jobs(ctx)
	// List up to 10 jobs to demonstrate iteration.
	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.Fprintf(w, "Job %s in state %s\n", j.ID(), state)
	}
	return nil
}

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
}

Node.js

在尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

在 GitHub 上查看反馈

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function listJobs() {
  // Lists all jobs in current GCP project.

  // List the 10 most recent jobs in reverse chronological order.
  //  Omit the max_results parameter to list jobs from the past 6 months.
  const options = {maxResults: 10};
  const [jobs] = await bigquery.getJobs(options);

  console.log('Jobs:');
  jobs.forEach(job => console.log(job.id));
}

Python

在尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 BigQuery Python API 参考文档。

在 GitHub 上查看反馈


from google.cloud import bigquery

import datetime

# Construct a BigQuery client object.
client = bigquery.Client()

# 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("{}".format(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("{}".format(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("Last 10 jobs done:")
for job in client.list_jobs(max_results=10, state_filter="DONE"):
    print("{}".format(job.job_id))

取消作业

可通过以下方式取消 RUNNING 或 PENDING 作业：

使用 Cloud Console 或经典版网页界面
使用命令行界面
通过调用 jobs.cancel API 方法
使用客户端库

请注意，并非所有作业类型都可以取消。如果作业无法取消，将返回一个错误。

即使作业可以取消，也不保证操作一定成功。作业可能在提交取消请求之前就已完成，或者作业可能处于无法取消的阶段。

所需权限

如需取消作业，您至少必须具有 bigquery.jobs.update 权限。以下预定义的 Cloud IAM 角色可提供 bigquery.jobs.update 权限：

bigquery.admin

如果您向某个帐号授予 bigquery.admin 角色，则该用户可以取消任何符合条件的作业，无论作业的提交者是谁。

以下角色可以取消自己创建的作业。此类用户只能取消自己提交的作业：

bigquery.user
bigquery.jobUser

如需详细了解 BigQuery 中的 Cloud IAM 角色和权限，请参阅预定义的角色和权限。

取消作业

要取消作业，请执行以下操作：

控制台

在导航窗格中，点击作业记录。
在个人记录部分中，点击要取消的作业。最新作业显示在列表顶部。
在作业详细信息中，点击取消作业。

经典版界面

在导航窗格中，点击 Job History。
在 Recent Jobs 部分中，点击要取消的作业。最新作业显示在列表顶部。
在作业详细信息中，点击 Cancel Job。

bq

发出带 job_id 参数的 bq cancel 命令。您可以使用 --nosync 标志请求取消后立即返回。默认情况下，系统将等待取消请求完成。

提供作业 ID 时，您可以使用完全限定的 ID 或者简写形式。例如，BigQuery 网页界面中列出的作业 ID 为完全限定格式，即其中包含项目和位置：

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 为可选项。位置是运行作业的位置的名称。例如，如果您在东京区域使用 BigQuery，请将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置该位置的默认值。
job_id 是要取消作业的 ID。如果您从 BigQuery 网页界面中复制作业 ID，则作业 ID 中将包含项目 ID 和位置。例如 my-project-1234:US.bquijob_123x456_123y123z123c。

示例：

以下命令用于取消 my-project-1234 中在 US 多区域位置运行的作业 my-project-1234:US.bquijob_123x456_123y123z123c 并等待操作完成。由于使用的是完全限定的作业 ID，无需提供 location 标志。

bq cancel my-project-1234:US.bquijob_123x456_123y123z123c

以下命令用于取消 my-project-1234 中在 US 多区域位置运行的作业 bquijob_123x456_123y123z123c 并等待操作完成。由于使用的是简写形式的作业 ID，需要提供 --location 标志。

bq --location=US cancel bquijob_123x456_123y123z123c

以下命令用于取消 my-project-1234 中在 US 多区域位置运行的作业 bquijob_123x456_123y123z123c 并立即返回结果。由于使用的是完全限定的作业 ID，无需提供 --location 标志。

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

API

调用 jobs.cancel 并提供 jobId 和 projectId 参数。提供 location 参数并将值设置为运行作业的位置。

Go

在尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 BigQuery Go API 参考文档。

在 GitHub 上查看反馈

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// cancelJob demonstrates how a job cancellation request can be issued for a specific
// BigQuery job.
func cancelJob(projectID, jobID string) error {
	// projectID := "my-project-id"
	// jobID := "my-job-id"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	job, err := client.JobFromID(ctx, jobID)
	if err != nil {
		return nil
	}
	return job.Cancel(ctx)
}

Node.js

在尝试此示例之前，请按照《BigQuery 快速入门：使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

在 GitHub 上查看反馈

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function cancelJob() {
  // Attempts to cancel a job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const jobId = "existing-job-id";

  // Create a job reference
  const job = bigquery.job(jobId);

  // Attempt to cancel job
  const [apiResult] = await job.cancel();

  console.log(apiResult.job.status);
}

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.cancel_job(job_id, location=location)

重复运行作业

您无法重新运行使用同一作业 ID 的作业，只能使用相同的配置新建一个作业。当您在 Cloud Console、经典版网页界面或命令行界面中提交新作业后，系统会分配新的作业 ID。如果您使用 API 或客户端库提交作业，则必须生成新的作业 ID。

所需权限

如需运行作业，您至少必须具有 bigquery.jobs.create 权限。以下预定义的 Cloud IAM 角色具有 bigquery.jobs.create 权限：

bigquery.user
bigquery.jobUser
bigquery.admin

如需详细了解 BigQuery 中的 Cloud IAM 角色和权限，请参阅预定义的角色和权限。

重新运行作业

要重复运行某个作业，请执行以下操作：

控制台

要重复运行某个查询作业，请执行以下操作：

在导航窗格中，点击查询记录。
在个人记录或项目记录部分中，点击要重新运行的查询，然后点击在编辑器中打开查询。
点击运行。

要重复运行某个加载作业，请执行以下操作：

在导航窗格中，点击作业记录。
在个人记录或项目记录部分中，点击要重复运行的作业。最新作业显示在列表顶部。
在作业详细信息中，点击重复加载作业。
注意：您不能使用 Cloud Console 重复导出作业或复制作业。

经典版界面

要重复运行某个查询作业，请执行以下操作：

在导航窗格中，点击 Query History。
在 Queries 部分的相应查询右侧，点击 Open Query。
点击 Run Query。

要重复运行某个加载作业，请执行以下操作：

在导航窗格中，点击 Job History。
在 Recent Jobs 部分，点击要重复运行的作业。最新作业显示在列表顶部。
在作业详细信息中，点击 Repeat Load Job。
注意：您不能使用网页界面重复导出作业或复制作业。

bq

再次发出命令，BigQuery 会自动生成使用新作业 ID 的作业。

API

重复运行作业的操作无法通过单次调用方法完成；如果您想重复运行某个特定作业，请执行以下操作：

调用 jobs.get 以检索重复运行该作业所需的资源。
移除 id、status 和 statistics 字段。将 jobId 字段更改为客户端代码生成的新值。根据需要对其他任何字段进行更改。
使用修改后的资源和新作业 ID 调用 jobs.insert 以启动新作业。