运行查询

本文档介绍如何在 BigQuery 中运行查询，并通过执行试运行来了解查询在执行之前将处理多少数据。

交互式查询与批量查询

在 BigQuery 中，您可以运行两种类型的查询：

• 交互式查询作业，即 BigQuery 按需运行的作业。
• 批量查询作业，即 BigQuery 等待空闲计算资源可用之前运行的作业。

默认情况下，BigQuery 将您的查询作为交互式查询作业运行，会尽快运行。 BigQuery 会根据资源可用性动态计算并发查询限制，并且比批量查询运行更多的并发交互式查询。达到并发查询限制后，其他查询将在队列中等待。如需了解详情，请参阅查询队列。

BigQuery 会将查询结果保存到临时表（默认）或永久表中。指定永久表作为结果的目标表时，您可以选择是附加还是覆盖现有表，或者创建具有唯一名称的新表。

注意：如果您查询项目中的数据，或存储在其他项目中的数据，则查询项目需要支付查询作业的费用，同时存储数据的项目需要按 BigQuery 中存储的数据量支付费用。

所需的角色

如需获得运行查询作业所需的权限，请让您的管理员授予您以下 IAM 角色：

• 针对项目的 BigQuery Job User (roles/bigquery.jobUser)。
• 针对查询引用的所有表和视图的 BigQuery Data Viewer (roles/bigquery.dataViewer)。如需查询视图，您还需要在所有底层表和视图上使用此角色。如果您使用的是已获授权的视图或已获授权的数据集，则无需访问底层源数据。

如需详细了解如何授予角色，请参阅管理访问权限。

这些预定义角色包含运行查询作业所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需运行查询作业，您需要拥有以下权限：

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

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需详细了解 BigQuery 权限，请参阅使用 IAM 进行访问权限控制。

运行交互式查询

如需运行交互式查询，请选择以下任一选项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 点击 编写新查询。

3. 在查询编辑器中，输入有效的 GoogleSQL 查询。

   例如，查询 BigQuery 公开数据集 usa_names，以确定 1910 年至 2013 年间美国人最常用的名字：

   SELECT
     name, gender,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name, gender
   ORDER BY
     total DESC
   LIMIT
     10;
   

4. 可选：指定查询结果的目标表和位置：

   1. 在查询编辑器中，点击 更多，然后点击查询设置。
   2. 在目标位置部分，选择为查询结果设置目标表。
   3. 在数据集部分，输入目标表的现有数据集的名称，例如 myProject.myDataset。
   4. 在表 ID 部分，输入目标表的名称，例如 myTable。

   5. 如果目标表是现有表，则对于目标表写入偏好设置，请选择是使用查询结果附加表还是覆盖表。

      如果目标表是新表，则 BigQuery 会在运行查询时创建表。

   6. 在其他设置部分中，点击数据位置菜单，然后选择一个选项。

      在此示例中，usa_names 数据集存储在美国多区域位置。如果您为此查询指定目标表，则包含目标表的数据集也必须位于美国多区域中。您无法查询一个位置的数据集而将结果写入另一个位置的表。

   7. 点击保存。

5. 点击 运行。

   如果未指定目标表，则查询作业会将输出写入临时（缓存）表。

6. 可选：如需按列对查询结果进行排序，请点击列名称旁边的 打开排序菜单，然后选择排序顺序。如果针对排序处理的估算字节数大于零，则菜单顶部会显示字节数。

7. 可选：如需查看查询结果的可视化效果，请前往图表标签页。您可以放大或缩小图表，将图片下载为 PNG 文件，也可以切换图例的可见性。

   在图表配置窗格中，您可以更改图表类型（折线图、条形图或散点图），并配置图表的度量和维度。此窗格中的字段预先填充了从查询的目标表架构推断的初始配置。在同一查询编辑器中的以下查询运行之间会保留配置。维度支持 INTEGER、INT64、FLOAT、FLOAT64、NUMERIC、BIGNUMERIC、TIMESTAMP、DATE、DATETIME、TIME 和 STRING 数据类型，而指标支持 INTEGER、INT64、FLOAT、FLOAT64、NUMERIC 和 BIGNUMERIC 数据类型。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 bq query 命令。 在以下示例中，--use_legacy_sql=false 标志可让您使用 GoogleSQL 语法。

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

   将 QUERY 替换为有效的 GoogleSQL 查询。例如，查询 BigQuery 公开数据集 usa_names，以确定 1910 年至 2013 年间美国人最常用的名字：

   bq query \
       --use_legacy_sql=false \
       'SELECT
         name, gender,
         SUM(number) AS total
       FROM
         `bigquery-public-data.usa_names.usa_1910_2013`
       GROUP BY
         name, gender
       ORDER BY
         total DESC
       LIMIT
         10;'
   

   查询作业将输出写入临时（缓存）表。

   （可选）您可以为查询结果指定目标表和位置。如需将结果写入现有表，请添加适当的标志以附加 (--append_table=true) 或覆盖 (--replace=true) 表。

   bq query \
       --location=LOCATION \
       --destination_table=TABLE \
       --use_legacy_sql=false \
       'QUERY'

   请替换以下内容：

   • LOCATION：目标表的单区域或多区域，例如 US

     在此示例中，usa_names 数据集存储在美国多区域位置。如果您为此查询指定目标表，则包含目标表的数据集也必须位于美国多区域中。您无法查询一个位置的数据集而将结果写入另一个位置的表。

     您可以使用 .bigqueryrc 文件设置位置的默认值。

   • TABLE：目标表的名称，例如 myDataset.myTable

     如果目标表是新表，则 BigQuery 会在运行查询时创建表。但是，您必须指定现有数据集。

     如果该表不在当前项目中，请使用 PROJECT_ID:DATASET.TABLE 格式添加 Google Cloud 项目 ID，例如 myProject:myDataset.myTable。如果未指定 --destination_table，系统会生成一个将输出写入临时表的查询作业。

API

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

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

C#

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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 = job.PollUntilCompleted().ThrowOnAnyError();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["name"]}");
        }
    }
}

Go

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

// 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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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
"""
rows = client.query_and_wait(query)  # Make an API request.

print("The query data:")
for row in rows:
    # 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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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

如需了解详情，请参阅交互式查询与批量查询。

运行批量查询

如需运行批量查询，请选择以下任一选项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 点击 编写新查询。

3. 在查询编辑器中，输入有效的 GoogleSQL 查询。

   例如，查询 BigQuery 公开数据集 usa_names，以确定 1910 年至 2013 年间美国人最常用的名字：

   SELECT
     name, gender,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name, gender
   ORDER BY
     total DESC
   LIMIT
     10;
   

4. 点击 更多，然后点击查询设置。

5. 在资源管理部分，选择批量。

6. 可选：指定查询结果的目标表和位置：

   1. 在目标位置部分，选择为查询结果设置目标表。
   2. 在数据集部分，输入目标表的现有数据集的名称，例如 myProject.myDataset。
   3. 在表 ID 部分，输入目标表的名称，例如 myTable。

   4. 如果目标表是现有表，则对于目标表写入偏好设置，请选择是使用查询结果附加表还是覆盖表。

      如果目标表是新表，则 BigQuery 会在运行查询时创建表。

   5. 在其他设置部分中，点击数据位置菜单，然后选择一个选项。

      在此示例中，usa_names 数据集存储在美国多区域位置。如果您为此查询指定目标表，则包含目标表的数据集也必须位于美国多区域中。您无法查询一个位置的数据集而将结果写入另一个位置的表。

7. 点击保存。

8. 点击 运行。

   如果未指定目标表，则查询作业会将输出写入临时（缓存）表。

9. 可选：如需按列对查询结果进行排序，请点击列名称旁边的 打开排序菜单，然后选择排序顺序。如果针对排序处理的估算字节数大于零，则菜单顶部会显示字节数。

10. 可选：如需查看查询结果的可视化效果，请前往图表标签页。您可以放大或缩小图表，将图片下载为 PNG 文件，也可以切换图例的可见性。

    在图表配置窗格中，您可以更改图表类型（折线图、条形图或散点图），并配置图表的度量和维度。此窗格中的字段预先填充了从查询的目标表架构推断的初始配置。在同一查询编辑器中的以下查询运行之间会保留配置。维度支持 INTEGER、INT64、FLOAT、FLOAT64、NUMERIC、BIGNUMERIC、TIMESTAMP、DATE、DATETIME、TIME 和 STRING 数据类型，而指标支持 INTEGER、INT64、FLOAT、FLOAT64、NUMERIC 和 BIGNUMERIC 数据类型。

bq

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 使用 bq query 命令并指定 --batch 标志。在以下示例中，--use_legacy_sql=false 标志可让您使用 GoogleSQL 语法。

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

   将 QUERY 替换为有效的 GoogleSQL 查询。例如，查询 BigQuery 公开数据集 usa_names，以确定 1910 年至 2013 年间美国人最常用的名字：

   bq query \
       --batch \
       --use_legacy_sql=false \
       'SELECT
         name, gender,
         SUM(number) AS total
       FROM
         `bigquery-public-data.usa_names.usa_1910_2013`
       GROUP BY
         name, gender
       ORDER BY
         total DESC
       LIMIT
         10;'
   

   查询作业将输出写入临时（缓存）表。

   （可选）您可以为查询结果指定目标表和位置。如需将结果写入现有表，请添加适当的标志以附加 (--append_table=true) 或覆盖 (--replace=true) 表。

   bq query \
       --batch \
       --location=LOCATION \
       --destination_table=TABLE \
       --use_legacy_sql=false \
       'QUERY'

   请替换以下内容：

   • LOCATION：目标表的单区域或多区域，例如 US

     在此示例中，usa_names 数据集存储在美国多区域位置。如果您为此查询指定目标表，则包含目标表的数据集也必须位于美国多区域中。您无法查询一个位置的数据集而将结果写入另一个位置的表。

     您可以使用 .bigqueryrc 文件设置位置的默认值。

   • TABLE：目标表的名称，例如 myDataset.myTable

     如果目标表是新表，则 BigQuery 会在运行查询时创建表。但是，您必须指定现有数据集。

     如果该表不在当前项目中，请使用 PROJECT_ID:DATASET.TABLE 格式添加 Google Cloud 项目 ID，例如 myProject:myDataset.myTable。如果未指定 --destination_table，系统会生成一个将输出写入临时表的查询作业。

API

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

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

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

Go

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

// 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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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))

如需了解详情，请参阅交互式查询与批量查询。

配额

如需了解交互式查询和批量查询的配额，请参阅查询作业。

查看交互式查询和批量查询的数量

您可以使用 INFORMATION_SCHEMA.JOBS_BY_PROJECT 视图查看交互式查询和批量查询的数量。以下示例使用 INFORMATION_SCHEMA.JOBS_BY_PROJECT 视图获取过去 7 小时内运行的交互式查询和批量查询的数量：

SELECT
  priority,
  COUNT(*) active_jobs,
FROM
  `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE
  creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 hour)
  AND end_time IS NULL
  AND job_type = 'QUERY'
GROUP BY priority

INFORMATION_SCHEMA.JOBS_BY_PROJECT 视图使用 priority 字段来指明查询是 INTERACTIVE 还是 BATCH。如需了解详情，请参阅架构。

执行试运行

BigQuery 中的试运行提供以下信息：

• 按需模式下的费用估算
• 验证查询
• 容量模式下查询的近似大小和复杂程度。

试运行不使用查询槽，您不需要为执行试运行支付费用。您可以使用试运行返回的估算值在价格计算器中计算查询费用。

注意：使用外部数据源的联合查询的试运行可能会报告 0 字节数据的下限，即使在返回了数据行的情况下也是如此。这是因为在实际查询完成之前，无法确定从外部表处理的数据量。运行联合查询仍会产生处理此数据的费用。

执行试运行

如需执行试运行，请执行以下操作：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 在查询编辑器中输入查询。

   如果查询有效，则会自动显示一个对勾标记以及查询将处理的数据量。如果查询无效，则会显示一个感叹号，并会显示错误消息。

bq

使用 --dry_run 标志输入如下所示的查询。

bq query \
--use_legacy_sql=false \
--dry_run \
'SELECT
   COUNTRY,
   AIRPORT,
   IATA
 FROM
   `project_id`.dataset.airports
 LIMIT
   1000'
 

对于有效查询，该命令会生成以下响应：

Query successfully validated. Assuming the tables are not modified,
running this query will process 10918 bytes of data.

注意：如果查询处理的数据量较少，您可能需要将所处理的字节数单位从 KB 转换为 MB。MB 是价格计算器使用的最小计量单位。

API

如需使用 API 执行试运行，请提交一项查询作业，并在 JobConfiguration 类型中将 dryRun 设置为 true。

Go

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import (
	"context"
	"fmt"
	"io"

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

// queryDryRun demonstrates issuing a dry run query to validate query structure and
// provide an estimate of the bytes scanned.
func queryDryRun(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,
		COUNT(*) as name_count
	FROM ` + "`bigquery-public-data.usa_names.usa_1910_2013`" + `
	WHERE state = 'WA'
	GROUP BY name`)
	q.DryRun = true
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"

	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Dry run is not asynchronous, so get the latest status and statistics.
	status := job.LastStatus()
	if err := status.Err(); err != nil {
		return err
	}
	fmt.Fprintf(w, "This query will process %d bytes\n", status.Statistics.TotalBytesProcessed)
	return nil
}

Java

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobStatistics;
import com.google.cloud.bigquery.QueryJobConfiguration;

// Sample to run dry query on the table
public class QueryDryRun {

  public static void runQueryDryRun() {
    String query =
        "SELECT name, COUNT(*) as name_count "
            + "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
            + "WHERE state = 'WA' "
            + "GROUP BY name";
    queryDryRun(query);
  }

  public static void queryDryRun(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).setDryRun(true).setUseQueryCache(false).build();

      Job job = bigquery.create(JobInfo.of(queryConfig));
      JobStatistics.QueryStatistics statistics = job.getStatistics();

      System.out.println(
          "Query dry run performed successfully." + statistics.getTotalBytesProcessed());
    } catch (BigQueryException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Node.js

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

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

async function queryDryRun() {
  // Runs a dry query of 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',
    dryRun: true,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  // Print the status and statistics
  console.log('Status:');
  console.log(job.metadata.status);
  console.log('\nJob Statistics:');
  console.log(job.metadata.statistics);
}

PHP

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

use Google\Cloud\BigQuery\BigQueryClient;

/** 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`';

// Construct a BigQuery client object.
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);

// Set job configs
$jobConfig = $bigQuery->query($query);
$jobConfig->useQueryCache(false);
$jobConfig->dryRun(true);

// Extract query results
$queryJob = $bigQuery->startJob($jobConfig);
$info = $queryJob->info();

printf('This query will process %s bytes' . PHP_EOL, $info['statistics']['totalBytesProcessed']);

Python

将 QueryJobConfig.dry_run 属性设置为 True。如果提供了试运行查询配置，Client.query() 将始终返回已完成的 QueryJob。

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

如需向 BigQuery 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为客户端库设置身份验证。

from google.cloud import bigquery

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

job_config = bigquery.QueryJobConfig(dry_run=True, use_query_cache=False)

# Start the query, passing in the extra configuration.
query_job = client.query(
    (
        "SELECT name, COUNT(*) as name_count "
        "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
        "WHERE state = 'WA' "
        "GROUP BY name"
    ),
    job_config=job_config,
)  # Make an API request.

# A dry run query completes immediately.
print("This query will process {} bytes.".format(query_job.total_bytes_processed))

后续步骤

• 了解如何管理查询作业。
• 了解如何查看查询历史记录。
• 了解如何保存和共享查询。
• 了解查询队列。