运行交互式查询作业和批量查询作业

本文介绍如何运行交互式（按需）查询作业和批量查询作业。

查询结果会保存到临时表或永久表中。您可以选择将结果附加到现有表、改写现有表中的数据，或者新建一个表（前提是不存在同名表）。

所需权限

如需运行查询作业，您需要对运行查询作业的项目拥有 bigquery.jobs.create Identity and Access Management (IAM) 权限。

以下预定义的每个 IAM 角色均包含运行查询作业所需的权限：

roles/bigquery.admin
roles/bigquery.jobUser
roles/bigquery.user

您还需要对查询引用的所有表和视图拥有 bigquery.tables.getData 权限。此外，在查询视图时，您需要对所有底层表和视图拥有此权限。但是，如果您使用的是已获授权的视图或已获授权的数据集，则无需访问底层源数据。

以下预定义的每个 IAM 角色均包含您对查询引用的所有表和视图所需的权限：

roles/bigquery.admin
roles/bigquery.dataOwner
roles/bigquery.dataEditor
roles/bigquery.dataViewer

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

运行交互式查询

默认情况下，BigQuery 运行交互式查询作业，也就是说，查询会尽快执行。交互式查询计入并发速率限制和每日限制。

如需运行写入临时表的交互式查询，请按照下列步骤操作：

控制台

在控制台中，打开 BigQuery 页面。

转到 BigQuery
点击编写新查询。
在查询编辑器文本区域中输入有效的 BigQuery SQL 查询。
（可选）如需更改数据处理位置，请点击更多，然后点击查询设置。在处理位置下，点击自动选择并选择数据的位置。最后，点击保存以更新查询设置。
点击运行。

这会创建一个将输出写入临时表中的查询作业。

bq

输入 bq query 命令并添加查询文本。

（可选）提供 --location 标志并将其值设置为您的位置。

您可以指定以下可选标志。此列表包含一些最常用的标志。如需查看 query 命令标志的完整列表，请参阅 bq 命令行工具参考文档中的 bq query。

指定以下标志：

--destination_table 标志，用于基于查询结果创建一个永久表。如需将查询结果写入非默认项目中的某个表，请按以下格式将相应项目 ID 添加到数据集名称中：project_id:dataset。如果未指定 --destination_table，系统会生成一个将输出写入临时（缓存）表的查询作业。
--append_table 标志，用于将查询结果附加到目标表。
--destination_kms_key 标志，指示使用 Cloud Key Management Service 密钥加密目标表数据。
--use_legacy_sql=false 标志，指示使用标准 SQL 语法。您可以使用 .bigqueryrc 文件为 bq 命令行工具设置默认语法。
--label 标志，指示以 key:value 的形式向查询作业应用标签。重复使用此标志可以指定多个标签。
--max_rows 或 -n 标志，用于指定要在查询结果中返回的行数。
--maximum_bytes_billed 标志，用于限制查询的收费字节数。如果查询超出此限制，则查询会失败（不会产生费用）。如果未指定此标志，则收费字节数设置为项目默认值。
--udf_resource 标志，用于加载和评估要用作用户定义的函数资源的代码文件。您可以指定一个 Cloud Storage URI 或某个本地代码文件的路径。重复使用此标志可以指定多个文件。

输入以下命令，以使用标准 SQL 语法运行交互式查询：

bq --location=location query \
--use_legacy_sql=false \
'query'

其中：

location 是查询处理位置的名称。--location 是可选标志。例如，如果您在东京地区使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置位置的默认值。
query 是使用标准 SQL 语法的查询。

示例：

输入以下命令以将查询结果写入 mydataset 中名为 mytable 的目标表。该数据集在默认项目中。该查询从美国姓名数据公共数据集中检索数据。

bq query \
--destination_table mydataset.mytable \
--use_legacy_sql=false \
'SELECT
  name,
  number
FROM
  `bigquery-public-data.usa_names.usa_1910_current`
WHERE
  gender = "M"
ORDER BY
  number DESC'

输入以下命令以将查询结果写入 mydataset 中名为 mytable 的目标表。该数据集属于 myotherproject，而非默认项目。该查询从非分区表（美国姓名数据公共数据集）中检索数据。

bq query \
--destination_table myotherproject:mydataset.mytable \
--use_legacy_sql=false \
'SELECT
  name,
  number
FROM
  `bigquery-public-data.usa_names.usa_1910_current`
WHERE
  gender = "M"
ORDER BY
  number DESC'

API

如需使用 API 运行查询，请插入新作业，并填写 jobs#configuration.query 属性。在任务资源的 jobReference 部分的 location 属性中指定您的所用位置。

通过调用 getQueryResults 提取结果，直到 jobComplete 等于 true。检查 errors 列表中是否存在错误和警告。

C#

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

在 GitHub 上查看反馈


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryQuery
{
    public void Query(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        string query = @"
            SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013`
            WHERE state = 'TX'
            LIMIT 100";
        BigQueryJob job = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: new QueryOptions { UseQueryCache = false });
        // Wait for the job to complete.
        job.PollUntilCompleted();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["name"]}");
        }
    }
}

Go

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

在 GitHub 上查看反馈

import (
	"context"
	"fmt"
	"io"

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

// queryBasic demonstrates issuing a query and reading results.
func queryBasic(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query(
		"SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " +
			"WHERE state = \"TX\" " +
			"LIMIT 100")
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"
	// Run the query and print results when the query job is completed.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Java

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

在 GitHub 上查看反馈

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

public class SimpleQuery {

  public static void runSimpleQuery() {
    // TODO(developer): Replace this query before running the sample.
    String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
    simpleQuery(query);
  }

  public static void simpleQuery(String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Create the query job.
      QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(query).build();

      // Execute the query.
      TableResult result = bigquery.query(queryConfig);

      // Print the results.
      result.iterateAll().forEach(rows -> rows.forEach(row -> System.out.println(row.getValue())));

      System.out.println("Query ran successfully");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query did not run \n" + e.toString());
    }
  }
}

Node.js

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

在 GitHub 上查看反馈

// Import the Google Cloud client library using default credentials
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();
async function query() {
  // Queries the U.S. given names dataset for the state of Texas.

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();

  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

PHP

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

在 GitHub 上查看反馈

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$jobConfig = $bigQuery->query($query);
$job = $bigQuery->startQuery($jobConfig);

$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
$queryResults = $job->queryResults();

$i = 0;
foreach ($queryResults as $row) {
    printf('--- Row %s ---' . PHP_EOL, ++$i);
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, json_encode($value));
    }
}
printf('Found %s row(s)' . PHP_EOL, $i);

Python

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

在 GitHub 上查看反馈


from google.cloud import bigquery

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

query = """
    SELECT name, SUM(number) as total_people
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE state = 'TX'
    GROUP BY name, state
    ORDER BY total_people DESC
    LIMIT 20
"""
query_job = client.query(query)  # Make an API request.

print("The query data:")
for row in query_job:
    # Row values can be accessed by field name or index.
    print("name={}, count={}".format(row[0], row["total_people"]))

Ruby

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

在 GitHub 上查看反馈

require "google/cloud/bigquery"

def query
  bigquery = Google::Cloud::Bigquery.new
  sql = "SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " \
        "WHERE state = 'TX' " \
        "LIMIT 100"

  # Location must match that of the dataset(s) referenced in the query.
  results = bigquery.query sql do |config|
    config.location = "US"
  end

  results.each do |row|
    puts row.inspect
  end
end

运行批量查询

BigQuery 也可运行批量查询。BigQuery 会替您将每个批量查询排成队列，并在 BigQuery 共享资源池中有空闲资源可用时尽快开始查询，这通常需要几分钟的时间。如果 BigQuery 没有在 24 小时内启动查询，BigQuery 会将作业优先级更改为交互式。

批量查询不会计入并发速率限制，因此您可以更轻松地同时启动多项查询。批量查询使用的资源与交互式（按需）查询相同。如果您使用统一费率价格，则批量查询和交互式查询将共用系统分配给您的槽。

要运行批量查询，请按照以下步骤操作：

控制台

在控制台中，打开 BigQuery 页面。

转到 BigQuery
点击编写新查询按钮。
在查询编辑器文本区域中输入有效的 SQL 查询。
点击更多按钮，然后点击查询设置。
在作业优先级部分，选择批量选项。
（可选）在处理位置部分，点击未指定并选择数据的位置。
点击保存以更新查询设置。
点击运行。

bq

输入 bq query 命令并添加查询文本。指定 --batch 标志以运行批量查询。

（可选）提供 --location 标志并将值设置为您所用的位置。

您可以指定以下可选标志。此列表包含一些最常用的标志。如需查看 query 命令标志的完整列表，请参阅 bq 命令行工具参考文档中的 bq query。

指定以下标志：

--destination_table 标志，用于基于查询结果创建一个永久表。如需将查询结果写入非默认项目中的某个表，请按以下格式将相应项目 ID 添加到数据集名称中：project_id:dataset。如果未指定 --destination_table，系统会生成一个将输出写入临时（缓存）表的查询作业。
--append_table 标志，用于将查询结果附加到目标表。
--destination_kms_key 标志，指示使用 Cloud Key Management Service 密钥加密目标表数据。
--use_legacy_sql=false 标志，指示使用标准 SQL 语法。您可以使用 .bigqueryrc 文件为 bq 命令行工具设置默认语法。
--label 标志，指示以 key:value 的形式向查询作业应用标签。重复使用此标志可以指定多个标签。
--max_rows 或 -n 标志，用于指定要在查询结果中返回的行数。
--maximum_bytes_billed 标志，用于限制查询的收费字节数。如果查询超出此限制，则查询会失败（不会产生费用）。如果未指定此标志，则收费字节数设置为项目默认值。
--udf_resource 标志，用于加载和评估要用作用户定义的函数资源的代码文件。您可以指定一个 Cloud Storage URI 或某个本地代码文件的路径。重复使用此标志可以指定多个文件。

输入以下命令，以使用标准 SQL 语法运行批量查询：

bq --location=location query \
--batch \
--use_legacy_sql=false \
'query'

其中：

location 是查询处理位置的名称。--location 是可选标志。例如，如果您在东京地区使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置位置的默认值。
query 是使用标准 SQL 语法的查询。

示例：

输入以下命令可将批量查询结果写入 mydataset 中名为 mytable 的目标表。该数据集在默认项目中。该查询从美国姓名数据公共数据集中检索数据。

bq query \
--batch \
--destination_table mydataset.mytable \
--use_legacy_sql=false \
'SELECT
  name,
  number
FROM
  `bigquery-public-data.usa_names.usa_1910_current`
WHERE
  gender = "M"
ORDER BY
  number DESC'

输入以下命令可将批量查询结果写入 mydataset 中名为 mytable 的目标表。该数据集属于 myotherproject，而非默认项目。该查询从非分区表（美国姓名数据公共数据集）中检索数据。

bq query \
--batch \
--destination_table myotherproject:mydataset.mytable \
--use_legacy_sql=false \
'SELECT
  name,
  number
FROM
  `bigquery-public-data.usa_names.usa_1910_current`
WHERE
  gender = "M"
ORDER BY
  number DESC'

API

如需使用 API 运行查询，请插入新作业，并填写 query 作业配置属性。（可选）在作业资源的 jobReference 部分的 location 属性中指定您所用的位置。

填写查询作业属性时，请添加 configuration.query.priority 属性并将其值设为 BATCH。

Go

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

在 GitHub 上查看反馈

import (
	"context"
	"fmt"
	"io"
	"time"

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

// queryBatch demonstrates issuing a query job using batch priority.
func queryBatch(w io.Writer, projectID, dstDatasetID, dstTableID string) error {
	// projectID := "my-project-id"
	// dstDatasetID := "mydataset"
	// dstTableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	// Build an aggregate table.
	q := client.Query(`
		SELECT
  			corpus,
  			SUM(word_count) as total_words,
  			COUNT(1) as unique_words
		FROM ` + "`bigquery-public-data.samples.shakespeare`" + `
		GROUP BY corpus;`)
	q.Priority = bigquery.BatchPriority
	q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)

	// Start the job.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Job is started and will progress without interaction.
	// To simulate other work being done, sleep a few seconds.
	time.Sleep(5 * time.Second)
	status, err := job.Status(ctx)
	if err != nil {
		return err
	}

	state := "Unknown"
	switch status.State {
	case bigquery.Pending:
		state = "Pending"
	case bigquery.Running:
		state = "Running"
	case bigquery.Done:
		state = "Done"
	}
	// You can continue to monitor job progress until it reaches
	// the Done state by polling periodically.  In this example,
	// we print the latest status.
	fmt.Fprintf(w, "Job %s in Location %s currently in state: %s\n", job.ID(), job.Location(), state)

	return nil

}

Java

如需运行批量查询，请在创建 QueryJobConfiguration 时将查询优先级设置为 QueryJobConfiguration.Priority.BATCH。

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

在 GitHub 上查看反馈

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

// Sample to query batch in a table
public class QueryBatch {

  public static void runQueryBatch() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String query =
        "SELECT corpus"
            + " FROM `"
            + projectId
            + "."
            + datasetName
            + "."
            + tableName
            + " GROUP BY corpus;";
    queryBatch(query);
  }

  public static void queryBatch(String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Run at batch priority, which won't count toward concurrent rate limit.
              .setPriority(QueryJobConfiguration.Priority.BATCH)
              .build();

      TableResult results = bigquery.query(queryConfig);

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query batch performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query batch not performed \n" + e.toString());
    }
  }
}

Node.js

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

在 GitHub 上查看反馈

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

async function queryBatch() {
  // Runs a query at batch priority.

  // Create query job configuration. For all options, see
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationquery
  const queryJobConfig = {
    query: `SELECT corpus
            FROM \`bigquery-public-data.samples.shakespeare\`
            LIMIT 10`,
    useLegacySql: false,
    priority: 'BATCH',
  };

  // Create job configuration. For all options, see
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfiguration
  const jobConfig = {
    // Specify a job configuration to set optional job resource properties.
    configuration: {
      query: queryJobConfig,
    },
  };

  // Make API request.
  const [job] = await bigquery.createJob(jobConfig);

  const jobId = job.metadata.id;
  const state = job.metadata.status.state;
  console.log(`Job ${jobId} is currently in state ${state}`);
}

Python

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

在 GitHub 上查看反馈

from google.cloud import bigquery

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

job_config = bigquery.QueryJobConfig(
    # Run at batch priority, which won't count toward concurrent rate limit.
    priority=bigquery.QueryPriority.BATCH
)

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(sql, job_config=job_config)  # Make an API request.

# Check on the progress by getting the job's updated state. Once the state
# is `DONE`, the results are ready.
query_job = client.get_job(
    query_job.job_id, location=query_job.location
)  # Make an API request.

print("Job {} is currently in state {}".format(query_job.job_id, query_job.state))

后续步骤

如需了解如何管理查询作业，请参阅管理作业。
如需了解如何查看查询历史记录，请参阅查看作业详细信息。
如需了解如何保存和共享查询，请参阅保存和共享查询。