写入查询结果

本文档介绍了如何写入或保存查询结果。

临时表和永久表

BigQuery 会将所有查询结果保存到表中，该表可以是永久表，也可以是临时表。

• 临时表是保存在特殊数据集中的随机命名表，用于缓存查询结果。临时表的生命周期约为 24 小时。临时表不可用于共享，也无法使用任何标准列表或其他表操作方法显示临时表。您不需要支付临时表的存储费用。

• 永久表可以是您有权访问的任何数据集中的新表或现有表。如果将查询结果写入新表，那么您就需要为存储数据支付费用。将查询结果写入永久表时，需要查询的表必须与目标表所在的数据集位于相同的位置。

所需权限

如需将查询结果写入表中，您必须至少具有以下权限：

• bigquery.tables.create 权限：用于创建新表
• bigquery.tables.updateData 权限：用于将数据写入新表、覆盖表或将数据附加到表中
• bigquery.jobs.create 权限：用于运行查询作业

如需访问要查询的数据，您可能还需要具备其他权限（例如 bigquery.tables.getData）。

以下预定义 Cloud IAM 角色包含 bigquery.tables.create 和 bigquery.tables.updateData 权限：

• bigquery.dataEditor
• bigquery.dataOwner
• bigquery.admin

以下预定义的 Cloud IAM 角色可提供 bigquery.jobs.create 权限：

• bigquery.user
• bigquery.jobUser
• bigquery.admin

此外，如果用户具有 bigquery.datasets.create 权限，则当该用户创建数据集时，系统会为其授予该数据集的 bigquery.dataOwner 访问权限。借助 bigquery.dataOwner 访问权限，用户可以在数据集内创建和更新表。

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

将查询结果写入永久表

将查询结果写入永久表时，您可以创建新表，将结果附加到现有表，或覆盖现有表。您可以通过以下方式将查询结果写入永久表：

• 使用 Cloud Console 或经典版 BigQuery 网页界面
• 使用命令行工具的 bq query 命令
• 调用 jobs.insert API 方法并配置 query 作业
• 使用客户端库

写入查询结果

如需将查询结果写入永久表，请执行以下操作：

控制台

1. 在 Cloud Console 中打开 BigQuery 网页界面。
   

   转到 Cloud Console

2. 在导航面板的资源部分中，展开您的项目并选择数据集。

3. 如果查询编辑器处于隐藏状态，请点击窗口右上角的显示编辑器。

4. 在查询编辑器文本区域中输入有效的 SQL 查询。

5. 点击编辑器下方的更多，然后选择查询设置。

   

6. 勾选为查询结果设置目标表复选框。

   

7. 在目标位置部分中，选择要在其中创建表的相应项目名称和数据集名称，然后选择表名称。

8. 在目标表的写入设置部分，选择以下选项之一：

   • 只写入空白表 - 仅在表为空时才将查询结果写入表。
   • 附加到表 - 将查询结果附加到现有表。
   • Overwrite table - 使用查询结果覆盖名称相同的现有表。

9. （可选）在处理位置部分中，点击自动选择并选择您的位置。

10. 点击运行查询。这会创建一个查询作业，并将查询结果写入您指定的表中。

或者，如果您在运行查询之前忘记指定目标表，可以点击编辑器下方的保存结果按钮，将缓存结果表复制到永久表。

DDL

通过数据定义语言 (DDL) 语句，您可以使用标准 SQL 查询语法创建和修改表。

如需了解详情，请参阅 CREATE TABLE 语句页面和 CREATE TABLE 示例：从现有表创建新表。

经典版界面

1. 转到经典版 BigQuery 网页界面。
   转到经典版 BigQuery 网页界面

2. 点击 Compose query 按钮。

3. 在 New Query 文本区域中输入有效的 SQL 查询。

4. 点击 Show Options。

5. 在 Destination Table 部分，点击 Select Table。

6. 在 Select Destination Table 对话框中，执行以下操作：

   1. 对于 Project，选择一个用于存储数据集和表的项目。

   2. 在 Dataset 部分，选择用于存储表的数据集。

   3. 在 Table ID 字段中，输入表名称。该名称在目标数据集中必须是唯一的。表名称不得超过 1024 个字符，并且只能包含 a-z、A-Z、0-9 或 _（下划线字符）。

   4. 点击 OK。

7. 在 Destination Table 部分的 Write Preference 中，选择以下某个选项：

   • Write if empty - 仅在表为空时才将查询结果写入表。
   • 附加到表 - 将查询结果附加到现有表。
   • Overwrite table - 使用查询结果覆盖名称相同的现有表。

8. （可选）在 Processing Location 部分中，点击 Unspecified 并选择数据的位置。

9. 点击 Run query。这会创建一个查询作业，并将查询结果写入您指定的表中。

或者，如果您在运行查询之前忘记指定目标表，可以点击结果窗口中的 Save as Table 按钮，将临时表复制到永久表。

CLI

输入 bq query 命令，并指定 --destination_table 标志以根据查询结果创建永久表。指定 use_legacy_sql=false 标志可使用标准 SQL 语法。如需将查询结果写入非默认项目中的某个表，请按以下格式将相应项目 ID 添加到数据集名称中：project_id:dataset。

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

如需控制现有目标表的写入处置方式，请指定以下可选标志之一：

• --append_table - 如果目标表存在，指定该标志可将查询结果附加到该表。
• --replace - 如果目标表存在，指定该标志可使用查询结果覆盖该表。

bq --location=location query \
--destination_table project_id:dataset.table \
--use_legacy_sql=false 'query'

其中：

• location 是用于处理查询的位置的名称。 --location 是可选标志。例如，如果您在东京区域使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置位置的默认值。
• project_id 是项目 ID。
• dataset 是数据集的名称，该数据集包含您要向其中写入查询结果的表。
• table 是您要向其中写入查询结果的表的名称。
• query 是使用标准 SQL 语法的查询。

如果未指定“写入处置方式”标志，则默认行为是仅在表为空时写入结果。如果表已存在且非空，则系统会返回以下错误：`BigQuery error in query operation: Error processing job project_id:bqjob_123abc456789_00000e1234f_1': Already Exists: Table project_id:dataset.table。

示例：

注意：以下示例可查询美国境内的公共数据集。由于公共数据集存储在美国的多区域位置，因此您的目标表所属的数据集也必须位于美国。您无法查询一个位置的数据集而将结果写入另一个位置的目标表。

输入以下命令可将查询结果写入 mydataset 中名为 mytable 的目标表。该数据集在默认项目中。由于命令中未指定“写入处置方式”标志，因此该表必须为新表或空表。否则，系统将返回 Already exists 错误。该查询从美国姓名数据公共数据集中检索数据。

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 的目标表。该数据集在默认项目中。该命令使用 --replace 标志覆盖目标表。

bq query \
--destination_table mydataset.mytable \
--replace \
--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 的目标表。该数据集属于 my-other-project，而非默认项目。该命令使用 --append_table 标志将查询结果附加到目标表。

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

各示例的输出如下所示。为了方便阅读，部分输出已被截断。

Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE
+---------+--------+
|  name   | number |
+---------+--------+
| Robert  |  10021 |
| John    |   9636 |
| Robert  |   9297 |
| ...              |
+---------+--------+

API

如需将查询结果保存到永久表中，请调用 jobs.insert 方法，配置 query 作业，并添加 destinationTable 属性的值。如需控制现有目标表的写入处置方式，请配置 writeDisposition 属性。

如需控制查询作业的处理位置，请在作业资源的 jobReference 部分中指定 location 属性。

Go

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

bigquery/snippets/querying/bigquery_query_destination_table.go

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

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

// queryWithDestination demonstrates saving the results of a query to a specific table by setting the destination
// via the API properties.
func queryWithDestination(w io.Writer, projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	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 17 as my_col")
	q.Location = "US" // Location must match the dataset(s) referenced in query.
	q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
	// 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 参考文档。

如需将查询结果保存到永久表中，请在 QueryJobConfiguration 中将目标表设置为所需的 TableId。

在 GitHub 上查看

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

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 queryDestinationTable() {
  // Queries the U.S. given names dataset for the state of Texas
  // and saves results to permanent table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Create destination table reference
  const dataset = bigquery.dataset(datasetId);
  const destinationTable = dataset.table(tableId);

  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/v2/tables#resource
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    destination: destinationTable,
  };

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

  console.log(`Job ${job.id} started.`);
  console.log(`Query results loaded to table ${destinationTable.id}`);
}

Python

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

如需将查询结果保存到永久表中，请创建 QueryJobConfig 并将目标设置为所需的 TableReference。然后，将作业配置传递给查询方法。

在 GitHub 上查看 反馈

from google.cloud import bigquery

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

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.QueryJobConfig(destination=table_id)

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.
query_job.result()  # Wait for the job to complete.

print("Query results loaded to the table {}".format(table_id))

写入大型查询结果

通常，查询都存在响应大小上限。如果您计划运行可能返回大型结果的查询，可以采取以下措施：

• 在标准 SQL 中，为查询结果指定目标表。
• 在旧版 SQL 中，指定目标表并设置 allowLargeResults 选项。

如果指定目标表来存储大型查询结果，您需要支付数据的存储费用。

限制

在旧版 SQL中，写入大型结果受到以下限制：

• 您必须指定目标表。
• 您不能指定顶级 ORDER BY、TOP 或 LIMIT 子句。如果指定这些子句，您就无法再并行计算查询输出，如此会抵消使用 allowLargeResults 的好处。
• 窗口函数只有在与 PARTITION BY 子句配合使用时才能返回大型查询结果。

使用旧版 SQL 写入大型结果

如需使用旧版 SQL 写入大型结果集，请执行以下操作：

控制台

1. 在 Cloud Console 中打开 BigQuery 网页界面。
   转到 Cloud Console

2. 点击编写新查询。

3. 在查询编辑器文本区域中输入有效的 SQL 查询。请使用 #legacySQL 前缀，或务必在查询设置中勾选使用旧版 SQL。

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

   

5. 在目标位置部分中，勾选为查询结果设置目标表。

   

6. 在项目名称部分，选择将在其中创建目标表的项目。

7. 在数据集名称部分，选择将存储表的数据集。

8. 在表名称字段中，输入表名称。

9. 如需将大型结果集写入现有表，您可以使用目标表的写入设置选项控制目标表的写入处置方式：

   • 只写入空白表：仅在表为空时才将查询结果写入表。
   • 附加到表：将查询结果附加到现有表。
   • 覆盖表：使用查询结果覆盖名称相同的现有表。

   

10. 在结果大小部分，勾选允许大型结果（无大小限制）。

    

11. （可选）在处理位置部分，点击自动选择并选择数据的位置。

    

12. 点击保存以更新查询设置。

13. 点击运行。这会创建一个查询作业，并将大型结果集写入您指定的表中。

经典版界面

1. 转到 BigQuery 网页界面。
   转到 BigQuery 网页界面

2. 点击 Compose query 按钮。

3. 在 New Query 文本区域中输入有效的 BigQuery SQL 查询。使用 #legacySQL 前缀，或务必在查询选项中勾选 Use Legacy SQL。

4. 点击 Show Options。

5. 在 Destination Table 部分，点击 Select Table。

6. 在 Select Destination Table 对话框中，执行以下操作：

   1. 对于 Project，选择要在哪个项目中创建目标表。

   2. 在 Dataset 部分，选择将存储表的数据集。

   3. 在 Table ID 字段中，输入表名称。

   4. 点击 OK。

7. 如需将大型结果集写入现有表，可以使用 Write Preference 选项来控制目标表的写入处置方式：

   • Write if empty - 仅在表为空时才将查询结果写入表。
   • 附加到表 - 将查询结果附加到现有表。
   • Overwrite table - 使用查询结果覆盖名称相同的现有表。

8. 在 Results Size 部分，勾选 Allow Large Results。

   

9. （可选）在 Processing Location 部分中，点击 Unspecified 并选择数据的位置。

10. 点击 Run Query。这会创建一个查询作业，并将大型结果集写入您指定的表中。

bq

搭配使用 --allow_large_results 标志与 --destination_table 标志，以创建用于存储大型结果集的目标表。由于 -- allow_large_results 选项仅适用于旧版 SQL，因此您还必须指定 --use_legacy_sql=true 标志。如需将查询结果写入非默认项目中的某个表，请按以下格式将相应项目 ID 添加到数据集名称中：[PROJECT_ID]:[DATASET]。提供 -- location 标志并将其值设置为您的位置。

如需控制现有目标表的写入处置方式，请指定以下可选标志之一：

• --append_table - 如果目标表存在，指定该标志可将查询结果附加到该表。
• --replace - 如果目标表存在，指定该标志可使用查询结果覆盖该表。

bq --location=location query \
--destination_table project_id:dataset.table \
--use_legacy_sql=true \
--allow_large_results "query"

其中：

• location 是用于处理查询的位置的名称。--location 是可选标志。例如，如果您在东京区域使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置位置的默认值。
• project_id 是项目 ID。
• dataset 是数据集名称，该数据集包含您要向其中写入查询结果的表。
• table 是您要向其中写入查询结果的表的名称。
• query 是使用旧版 SQL 语法的查询。

示例：

注意：以下示例查询的是公共数据集。由于该数据集存储在美国的多区域位置，因此您的目标数据集也必须位于美国境内。您无法将公共数据查询结果写入位于不同区域的表中。

输入以下命令可将大型查询结果写入 mydataset 中名为 mytable 的目标表。该数据集属于默认项目。由于命令中未指定“写入处置方式”标志，因此该表必须为新表或空表。否则，系统将返回 Already exists 错误。该查询会从美国姓名数据公共数据集中检索数据。该查询仅用于举例。所返回的结果集不会超过响应大小上限。

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

输入以下命令可使用大型查询结果覆盖 mydataset 中名为 mytable 的目标表。该数据集属于 myotherproject，而非默认项目。该命令使用 --replace 标志覆盖目标表。

bq query \
--destination_table mydataset.mytable \
--replace \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
  name,
  number
FROM
  [bigquery-public-data:usa_names.usa_1910_current]
WHERE
  gender = 'M'
ORDER BY
  number DESC"

输入以下命令可将大型查询结果附加到 mydataset 中名为 mytable 的目标表。该数据集属于 myotherproject，而非默认项目。该命令使用 --append_table 标志将查询结果附加到目标表。

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

API

如需将大型结果写入目标表中，请调用 jobs.insert 方法，配置 query 作业，并将 allowLargeResults 属性设置为 true。 使用 destinationTable 属性指定目标表。如需控制现有目标表的写入处置方式，请配置 writeDisposition 属性。

在作业资源 jobReference 部分的 location 属性中指定您的位置。

Go

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

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

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

// queryLegacyLargeResults demonstrates issuing a legacy SQL query and writing a large result set
// into a destination table.
func queryLegacyLargeResults(w io.Writer, projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "destinationdataset"
	// tableID := "destinationtable"
	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 corpus FROM [bigquery-public-data:samples.shakespeare] GROUP BY corpus;")
	q.UseLegacySQL = true
	q.AllowLargeResults = true
	q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
	// 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

如需启用大型结果，请在 QueryJobConfiguration 中将允许大型结果设置为 true，并将目标表设置为所需的 TableId。

在 GitHub 上查看

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM [bigquery-public-data:samples.shakespeare] GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // To use legacy SQL syntax, set useLegacySql to true.
    QueryJobConfiguration.newBuilder(query)
        .setUseLegacySql(true)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        // Allow results larger than the maximum response size.
        // If true, a destination table must be set.
        .setAllowLargeResults(true)
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

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 queryLegacyLargeResults() {
  // Query enables large result sets.

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const projectId = "my_project"
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  const query = `SELECT word FROM [bigquery-public-data:samples.shakespeare] LIMIT 10;`;

  // 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 and of the destination table.
    useLegacySql: true,
    allowLargeResult: true,
    destinationTable: {
      projectId: projectId,
      datasetId: datasetId,
      tableId: tableId,
    },
  };

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

Python

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

在 GitHub 上查看 反馈

from google.cloud import bigquery

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

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Set the destination table and use_legacy_sql to True to use
# legacy SQL syntax.
job_config = bigquery.QueryJobConfig(
    allow_large_results=True, destination=table_id, use_legacy_sql=True
)

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.
query_job.result()  # Wait for the job to complete.

print("Query results loaded to the table {}".format(table_id))

下载和保存查询结果

运行 SQL 查询后，您可以将结果下载到本地计算机上的文件中，也可以将结果保存到 Google 云端硬盘或 Google 表格中，还可以将结果保存到 BigQuery 中的永久表中。

限制

查询结果的下载和保存须遵循以下限制：

• 在经典版 BigQuery 网页界面中，您只能将查询结果下载到本地文件或 Google 表格中。如需将结果下载到 Google 云端硬盘，请使用 Cloud Console。
• 如需使用经典版 BigQuery 网页界面下载查询结果，结果集包含的行数不得超过 16000 行，且大小不得超过 10 MB。如果结果大于 10 MB 或超过 16000 行，则可以将其保存到表中。
• 您只能以 CSV 或换行符分隔的 JSON 格式在本地下载查询结果。
• 不能以 CSV 格式下载包含嵌套和重复数据的查询结果。
• 不能将包含嵌套和重复数据的查询结果保存到 Google 表格中。
• 使用经典版 BigQuery 网页界面将查询结果保存到 Google 表格时，结果集包含的行数不得超过 16000 行，且大小不得超过 10 MB。如果结果大于 10 MB 或超过 16000 行，则可以改为保存到表中。
• 命令行工具或 API 不支持将结果保存到本地文件、Google 表格和 Google 云端硬盘。
• 如需使用 Cloud Console 将查询结果保存到 Google 云端硬盘，结果集必须不超过 1 GB。如果结果大于 1 GB，则可以改为保存到表中。
• 您只能以 CSV 或换行符分隔的 JSON 格式将查询结果保存到 Google 云端硬盘。

将查询结果下载到本地文件

命令行工具或 API 不支持将查询结果下载到本地文件。

如需使用网页界面以 CSV 或换行符分隔的 JSON 文件格式下载查询结果，请执行以下操作：

控制台

1. 在 Cloud Console 中打开 BigQuery 网页界面。
   转到 Cloud Console

2. 点击编写新查询。

3. 在查询编辑器文本区域中输入有效的 SQL 查询。

4. （可选）如需更改处理位置，请点击更多并选择查询设置。在处理位置下，点击自动选择并选择数据的位置。

5. 点击运行。

6. 返回结果后，点击保存结果，并选择要保存结果的格式/位置。

   此时文件会下载到您浏览器的默认下载位置。

经典版界面

1. 转到 BigQuery 网页界面。
   转到 BigQuery 网页界面

2. 点击 Compose Query 按钮。

3. 在 New Query 文本区域中输入有效的 SQL 查询。

4. 点击 Show Options。

5. （可选）在 Processing Location 部分中，点击 Unspecified 并选择数据的位置。

6. 点击 Run Query。

7. 结果返回后，点击查询结果上方的 Download as CSV 或 Download as JSON 按钮。

   

   此时文件会下载到您浏览器的默认下载位置。

将查询结果保存到 Google 云端硬盘

Beta 版

此功能目前处于预发布状态，可能会更改或仅提供有限支持。如需了解详情，请参阅产品发布阶段。

命令行工具、API 或经典版 BigQuery 网页界面不支持将查询结果保存到 Google 云端硬盘。

如需使用 Cloud Console 将查询结果保存到 Google 云端硬盘，请执行以下操作：

控制台

1. 在 Cloud Console 中打开 BigQuery 网页界面。

   转到 Cloud Console

2. 在查询编辑器文本区域中输入有效的 SQL 查询。

3. 点击运行。

4. 返回结果后，点击保存结果。

   

5. 选择 CSV（Google 云端硬盘）或 JSON（Google 云端硬盘）。将结果保存到 Google 云端硬盘时，您无法选择位置。结果始终会保存到根目录“My Drive”位置。

6. 将结果保存到 Google 云端硬盘可能需要几分钟时间。结果保存后，您会收到一条包含下列文件名的弹出消息：bq-results-[TIMESTAMP]-[RANDOM_CHARACTERS].[CSV or JSON]。

   

7. 在弹出消息中，点击打开以打开该文件，或导航到 Google 云端硬盘并点击 My Drive。

将查询结果保存到表中

如需将查询结果保存为表，请执行以下操作：

控制台

1. 在 Cloud Console 中打开 BigQuery 网页界面。
   

   转到 Cloud Console

2. 在导航面板的资源部分中，展开您的项目并选择数据集。

3. 如果查询编辑器处于隐藏状态，请点击窗口右上角的显示编辑器。

4. 在查询编辑器文本区域中输入有效的 SQL 查询。

5. 点击编辑器下方的更多，然后选择查询设置。

   

6. 勾选为查询结果设置目标表复选框。

   

7. 在目标位置部分中，选择要在其中创建表的相应项目名称和数据集名称，然后选择表名称。

8. 在目标表的写入设置部分，选择以下选项之一：

   • 只写入空白表 - 仅在表为空时才将查询结果写入表。
   • 附加到表 - 将查询结果附加到现有表。
   • Overwrite table - 使用查询结果覆盖名称相同的现有表。

9. （可选）在处理位置部分中，点击自动选择并选择您的位置。

10. 点击运行查询。这会创建一个查询作业，并将查询结果写入您指定的表中。

或者，如果您在运行查询之前忘记指定目标表，可以点击编辑器下方的保存结果按钮，将缓存结果表复制到永久表。

DDL

通过数据定义语言 (DDL) 语句，您可以使用标准 SQL 查询语法创建和修改表。

如需了解详情，请参阅 CREATE TABLE 语句页面和 CREATE TABLE 示例：从现有表创建新表。

经典版界面

1. 转到经典版 BigQuery 网页界面。
   转到经典版 BigQuery 网页界面

2. 点击 Compose query 按钮。

3. 在 New Query 文本区域中输入有效的 SQL 查询。

4. 点击 Show Options。

5. 在 Destination Table 部分，点击 Select Table。

6. 在 Select Destination Table 对话框中，执行以下操作：

   1. 对于 Project，选择一个用于存储数据集和表的项目。

   2. 在 Dataset 部分，选择用于存储表的数据集。

   3. 在 Table ID 字段中，输入表名称。该名称在目标数据集中必须是唯一的。表名称不得超过 1024 个字符，并且只能包含 a-z、A-Z、0-9 或 _（下划线字符）。

   4. 点击 OK。

7. 在 Destination Table 部分的 Write Preference 中，选择以下某个选项：

   • Write if empty - 仅在表为空时才将查询结果写入表。
   • 附加到表 - 将查询结果附加到现有表。
   • Overwrite table - 使用查询结果覆盖名称相同的现有表。

8. （可选）在 Processing Location 部分中，点击 Unspecified 并选择数据的位置。

9. 点击 Run query。这会创建一个查询作业，并将查询结果写入您指定的表中。

或者，如果您在运行查询之前忘记指定目标表，可以点击结果窗口中的 Save as Table 按钮，将临时表复制到永久表。

CLI

输入 bq query 命令，并指定 --destination_table 标志以根据查询结果创建永久表。指定 use_legacy_sql=false 标志可使用标准 SQL 语法。如需将查询结果写入非默认项目中的某个表，请按以下格式将相应项目 ID 添加到数据集名称中：project_id:dataset。

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

如需控制现有目标表的写入处置方式，请指定以下可选标志之一：

• --append_table - 如果目标表存在，指定该标志可将查询结果附加到该表。
• --replace - 如果目标表存在，指定该标志可使用查询结果覆盖该表。

bq --location=location query \
--destination_table project_id:dataset.table \
--use_legacy_sql=false 'query'

其中：

• location 是用于处理查询的位置的名称。 --location 是可选标志。例如，如果您在东京区域使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置位置的默认值。
• project_id 是项目 ID。
• dataset 是数据集的名称，该数据集包含您要向其中写入查询结果的表。
• table 是您要向其中写入查询结果的表的名称。
• query 是使用标准 SQL 语法的查询。

如果未指定“写入处置方式”标志，则默认行为是仅在表为空时写入结果。如果表已存在且非空，则系统会返回以下错误：`BigQuery error in query operation: Error processing job project_id:bqjob_123abc456789_00000e1234f_1': Already Exists: Table project_id:dataset.table。

示例：

注意：以下示例可查询美国境内的公共数据集。由于公共数据集存储在美国的多区域位置，因此您的目标表所属的数据集也必须位于美国。您无法查询一个位置的数据集而将结果写入另一个位置的目标表。

输入以下命令可将查询结果写入 mydataset 中名为 mytable 的目标表。该数据集在默认项目中。由于命令中未指定“写入处置方式”标志，因此该表必须为新表或空表。否则，系统将返回 Already exists 错误。该查询从美国姓名数据公共数据集中检索数据。

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 的目标表。该数据集在默认项目中。该命令使用 --replace 标志覆盖目标表。

bq query \
--destination_table mydataset.mytable \
--replace \
--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 的目标表。该数据集属于 my-other-project，而非默认项目。该命令使用 --append_table 标志将查询结果附加到目标表。

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

各示例的输出如下所示。为了方便阅读，部分输出已被截断。

Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE
+---------+--------+
|  name   | number |
+---------+--------+
| Robert  |  10021 |
| John    |   9636 |
| Robert  |   9297 |
| ...              |
+---------+--------+

API

如需将查询结果保存到永久表中，请调用 jobs.insert 方法，配置 query 作业，并添加 destinationTable 属性的值。如需控制现有目标表的写入处置方式，请配置 writeDisposition 属性。

如需控制查询作业的处理位置，请在作业资源的 jobReference 部分中指定 location 属性。

Go

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

bigquery/snippets/querying/bigquery_query_destination_table.go

在 GitHub 上查看 反馈

import (
	"context"
	"fmt"
	"io"

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

// queryWithDestination demonstrates saving the results of a query to a specific table by setting the destination
// via the API properties.
func queryWithDestination(w io.Writer, projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	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 17 as my_col")
	q.Location = "US" // Location must match the dataset(s) referenced in query.
	q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
	// 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 参考文档。

如需将查询结果保存到永久表中，请在 QueryJobConfiguration 中将目标表设置为所需的 TableId。

在 GitHub 上查看

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

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 queryDestinationTable() {
  // Queries the U.S. given names dataset for the state of Texas
  // and saves results to permanent table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Create destination table reference
  const dataset = bigquery.dataset(datasetId);
  const destinationTable = dataset.table(tableId);

  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/v2/tables#resource
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    destination: destinationTable,
  };

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

  console.log(`Job ${job.id} started.`);
  console.log(`Query results loaded to table ${destinationTable.id}`);
}

Python

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

如需将查询结果保存到永久表中，请创建 QueryJobConfig 并将目标设置为所需的 TableReference。然后，将作业配置传递给查询方法。

在 GitHub 上查看 反馈

from google.cloud import bigquery

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

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.QueryJobConfig(destination=table_id)

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.
query_job.result()  # Wait for the job to complete.

print("Query results loaded to the table {}".format(table_id))

将查询结果保存到 Google 表格

命令行工具或 API 不支持将查询结果保存到 Google 表格。

如需使用网页界面将查询结果保存到 Google 表格中，请执行以下操作：

控制台

1. 在 Cloud Console 中打开 BigQuery 网页界面。
   转到 BigQuery 网页界面

2. 点击编写新查询。

3. 在查询编辑器文本区域中输入有效的 SQL 查询。

4. （可选）如需更改处理位置，请点击更多并选择查询设置。在处理位置下，点击自动选择并选择数据的位置。

5. 点击运行。

6. 返回结果后，点击保存结果，并选择 Google 表格。

7. 如有必要，请按照系统提示登录到您的 Google 帐号，然后点击允许以授予 BigQuery 相应的权限，使其能够将数据写入您的 Google 云端硬盘的 MY Drive 文件夹。

   按照系统提示操作后，您应该会收到一封主题为“BigQuery 客户端工具已连接到您的 Google 帐号”(BigQuery Client Tools connected to your Google Account) 的电子邮件。这封电子邮件包含有关您已授予的权限的信息以及移除这些权限的相关步骤。

8. 保存结果后，控制台 BigQuery 网页界面中的查询结果下方会显示如下消息：Saved to Sheets as "results-20190225-103531. Open。您可以点击此消息中的链接以在 Google 表格中查看您的结果，也可以导航到 My Drive 文件夹并手动打开文件。

   当您将查询结果保存到 Google 表格时，文件名会以 results-[DATE] 开头，其中 [DATE] 是今天的日期（格式为 YYYYMMDD）。

注意：命令行工具或 API 不支持将结果保存到 Google 表格。

经典版界面

1. 转到 BigQuery 网页界面。
   转到 BigQuery 网页界面

2. 点击 Compose Query 按钮。

3. 在 New Query 文本区域中输入有效的 SQL 查询。

4. 点击 Show Options。

5. （可选）在 Processing Location 部分中，点击 Unspecified 并选择数据的位置。

6. 点击 Run Query。

7. 结果返回后，点击查询结果上方的 Save to Google Sheets 按钮。

   

8. 如有必要，请按照系统提示登录到您的 Google 帐号，然后点击允许以授予 BigQuery 相应的权限，使其能够将数据写入您的 Google 云端硬盘的 MY Drive 文件夹。

   按照系统提示操作后，您应该会收到一封主题为“BigQuery 客户端工具已连接到您的 Google 帐号”(BigQuery Client Tools connected to your Google Account) 的电子邮件。这封电子邮件包含有关您已授予的权限的信息以及移除这些权限的相关步骤。

9. 保存结果后，经典版 BigQuery 网页界面中的查询结果上方会显示如下消息：Results saved to Google Sheets. Click to view。您可以点击此消息中的链接以在 Google 表格中查看您的结果，也可以导航至 MY Drive 文件夹并手动打开文件。

   当您将查询结果保存到 Google 表格时，文件名会以 results-[DATE] 开头，其中 [DATE] 是今天的日期（格式为 YYYYMMDD）。

注意：命令行工具或 API 不支持将结果保存到 Google 表格。