使用 bq 命令行工具

bq 命令行工具是基于 Python 的 BigQuery 命令行工具。本页面提供有关使用 bq 命令行工具的常规信息。

如需所有 bq 命令和标志的完整参考信息，请参阅 bq 命令行工具参考文档。

准备工作

您必须先使用 Google Cloud Console 创建或选择项目，然后才能使用 bq 命令行工具。

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

4. 系统会自动为新项目启用 BigQuery。 如需在预先存在的项目中激活 BigQuery，请转到

   Enable the BigQuery API.

   Enable the API

5. 可选：为项目启用结算功能。如果您不想启用结算功能或提供信用卡，本文档中的步骤仍然有效。BigQuery 提供执行这些步骤的沙盒。如需了解详情，请参阅启用 BigQuery 沙盒。
   注意：如果您的项目具有结算帐号，并且您希望使用 BigQuery 沙盒，请为项目停用结算功能。

在 Cloud Shell 中输入 bq 命令

您可以在 Cloud Shell 中通过 Google Cloud 控制台或 Google Cloud CLI 输入 bq 命令行工具命令。

• 如需在控制台中使用 bq 命令行工具，请激活 Cloud Shell：

  激活 Cloud Shell

• 如需在 gcloud CLI 中使用 bq 命令行工具，请安装并配置 gcloud CLI。

定位标志和参数

bq 命令行工具支持两种标志：

• 全局标志在所有命令中使用。
• 特定于命令的标记适用于特定的命令。

如需查看可用的全局标志和特定于命令的标志列表，请参阅 bq 命令行工具参考文档。

请将任何全局标志放在 bq 命令前面，然后包含特定于命令的标志。您可以包含多个全局标志或特定于命令的标志。例如：

bq --location=us mk --reservation --project_id=project reservation_name

您可以通过以下方式指定命令参数：

• --FLAG ARGUMENT（如前面的示例中所示）
• --FLAG=ARGUMENT
• --FLAG='ARGUMENT'
• --FLAG="ARGUMENT"
• --FLAG 'ARGUMENT'
• --FLAG "ARGUMENT"

替换以下内容：

• FLAG：全局标志或特定于命令的标志
• ARGUMENT：标志的参数

在某些命令中，必须为参数加上单引号或双引号。当参数包含空格、逗号或其他特殊字符时，通常都必须使用引号。例如：

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

指定含布尔值的标志时，可不用参数。如果您指定 true 或 false，则必须使用 FLAG=ARGUMENT 格式。

例如，以下命令在布尔值标志 --use_legacy_sql 前加上 no，以此来指定 false：

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

或者，如果要将 false 指定为标志的参数，则可以输入以下命令：

bq query --use_legacy_sql=false \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

通过 bq 命令行工具运行查询

如需获取您在 Google Cloud Console 中开发的查询并通过 bq 命令行工具运行该查询，请执行以下操作：

1. 在 bq query 命令中包含该查询，如下所示：bq query --use_legacy_sql=false 'QUERY'。将 QUERY 替换为该查询。
2. 将查询中的任何英文单引号 (') 替换为英文双引号 (")。
3. 从查询中移除注释。

例如，将以下 Google Cloud Console 查询：

-- count Shakespeare's use of the string "raisin"
SELECT
  word,
  SUM(word_count) AS count
FROM
  `bigquery-public-data`.samples.shakespeare
WHERE
  word LIKE '%raisin%'
GROUP BY
  word

转换为 bq 命令行工具查询，如下所示：

bq query --use_legacy_sql=false \
'SELECT
  word,
  SUM(word_count) AS count
FROM
  `bigquery-public-data`.samples.shakespeare
WHERE
  word LIKE "%raisin%"
GROUP BY
  word'

如需了解详情，请参阅运行交互式查询作业和批量查询作业。

获取帮助

如需获取 bq 命令行工具的帮助，您可以输入以下命令：

• 如需已安装的 bq 命令行工具版本，请输入 bq version。
• 如需完整的命令列表，请输入 bq help。
• 如需全局标志列表，请输入 bq --help。
• 如需特定命令的帮助，请输入 bq help COMMAND。
• 如需特定命令的帮助以及全局标志列表，请输入 bq COMMAND --help。

将 COMMAND 替换为您需要帮助的命令。

设置命令行标志的默认值

若要设置命令行标志的默认值，您可以在 bq 命令行工具的配置文件 .bigqueryrc 中包括默认值。配置默认选项之前，必须先创建 .bigqueryrc 文件。您可以使用自己偏好的文本编辑器创建该文件。创建 .bigqueryrc 文件后，您可以使用 --bigqueryrc 全局标志指定该文件的路径。

如果未指定 --bigqueryrc 标志，则使用 BIGQUERYRC 环境变量。如果未指定该变量，则会使用路径 ~/.bigqueryrc。默认路径为 $HOME/.bigqueryrc。

注意：不建议使用 bq init 命令创建 .bigqueryrc 文件。

将标志添加到 .bigqueryrc

要将命令行标志的默认值添加到 .bigqueryrc，请执行以下操作：

• 在没有文件头的文件顶端添加全局标志。
• 若要添加特定于命令的标志，请输入命令名称（在括号中），然后在命令名称后面添加特定于命令的标志（每行一个）。

例如：

--apilog=stdout
--format=prettyjson
--location=US

[query]
--use_legacy_sql=false
--max_rows=100
--maximum_bytes_billed=10000000

[load]
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey

上述示例设置以下标志的默认值：

• 将全局标志 --apilog 设置为 stdout，以将调试输出打印到控制台。
• 将全局标志 --format 设置为 prettyjson，以采用易于用户理解的 JSON 格式显示命令输出。
• 将全局标志 --location 设置为 US 多区域位置。

• 将 query 特定于命令的标志 --use_legacy_sql 设置为 false，以将标准 SQL 设为默认查询语法。

  注意：不能在 .bigqueryrc 中使用 --nouse_legacy_sql。

• 将 query 特定于命令的标志 --max_rows 设置为 100，以控制查询输出中的行数。

• 将 query 特定于命令的标志 --maximum_bytes_billed 设置为 10,000,000 字节 (10 MB)，以让读取数据量超过 10 MB 的查询失败。

• 将 load 特定于命令的标志 --destination_kms_key 设置为 projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey。

在交互式 shell 中运行 bq 命令行工具

在交互式 shell 中运行 bq 命令行工具时，无需为命令加上 bq 前缀。要启动交互模式，请输入 bq shell。启动 shell 后，提示符会更改为默认项目的 ID。要退出交互模式，请输入 exit。

在脚本中运行 bq 命令行工具

您可以在脚本中运行 bq 命令行工具，就像运行 Google Cloud CLI 命令一样。以下示例展示了 bash 脚本中的 gcloud 和 bq 命令：

#!/bin/bash
gcloud config set project myProject
bq query --use_legacy_sql=false --destination_table=myDataset.myTable \
'SELECT
   word,
   SUM(word_count) AS count
 FROM
   `bigquery-public-data`.samples.shakespeare
 WHERE
   word LIKE "%raisin%"
 GROUP BY
   word'

从服务帐号运行 bq 命令

要使用服务帐号运行 bq 命令，您必须向服务帐号授予对 Google Cloud 的访问权限。如需了解详情，请参阅 gcloud auth activate-service-account。

示例

您可以在 BigQuery 文档的方法指南部分中找到命令行示例。本部分列出了指向常见命令行任务（如创建、获取、列出、删除和修改 BigQuery 资源）的链接。

创建资源

如需了解如何使用 bq 命令行工具创建资源，请参阅以下内容：

• 创建数据集
• 创建具有架构定义的空表
• 基于查询结果创建表
• 创建提取时间分区表
• 创建视图

如需使用数据文件创建表的相关示例，请参阅加载数据：

获取资源相关信息

如需了解如何使用 bq 命令行工具获取有关资源的信息，请参阅以下内容：

• 获取数据集相关信息
• 获取表相关信息
• 获取视图相关信息

列出资源

如需了解如何使用 bq 命令行工具列出资源，请参阅以下内容：

• 列出数据集
• 列出表
• 列出视图

更新资源

如需了解如何使用 bq 命令行工具更新资源，请参阅以下内容：

• 更新数据集属性
• 更新表属性
• 更新视图属性

加载数据

如需了解如何使用 bq 命令行工具加载数据，请参阅以下内容：

• 从 Cloud Storage 加载 Avro 数据
• 从 Cloud Storage 加载 JSON 数据
• 从 Cloud Storage 加载 CSV 数据
• 从本地文件加载数据

查询数据

如需了解如何使用 bq 命令行工具查询数据，请参阅以下内容：

• 运行查询
• 写入查询结果
• 运行参数化查询

使用外部数据源

如需了解如何使用 bq 命令行工具查询外部数据源中的数据，请参阅以下内容：

• 使用 JSON 架构文件创建表定义
• 使用永久外部表查询 Cloud Bigtable 数据
• 使用永久外部表查询 Cloud Storage 数据
• 使用永久外部表查询 Google 云端硬盘数据

导出数据

如需了解如何使用 bq 命令行工具导出数据，请参阅以下内容：

• 导出存储在 BigQuery 中的数据

使用 BigQuery Data Transfer Service

如需了解如何将 bq 命令行工具与 BigQuery Data Transfer Service 搭配使用，请参阅以下内容：

• 设置 Amazon S3 转移作业
• 设置 Campaign Manager 转移作业
• 设置 Cloud Storage 转移作业
• 设置 Google Ad Manager 转移作业
• 设置 Google Ads 转移作业
• 设置 Google Merchant Center 转移作业（Beta 版）
• 设置 Google Play 转移作业
• 设置 Search Ads 360 转移作业（Beta 版）
• 设置 YouTube 频道转移作业
• 设置 YouTube 内容所有者转移作业
• 从 Amazon Redshift 迁移数据
• 从 Teradata 迁移数据

• 获取有关转移作业配置的信息
• 列出转移作业配置
• 查看运行记录
• 查看转移作业运行详情和日志消息
• 更新转移作业配置

对 bq 命令行工具进行问题排查

本部分介绍如何解决 bq 命令行工具的问题。

让 gcloud CLI 保持为最新版本

如果您是在 Google Cloud CLI 中使用 bq 命令行工具，那么请让 gcloud CLI 安装保持为最新版本，以确保您拥有 bq 命令行工具的最新功能和最新版修复程序。要查看您运行的是否为最新版本的 gcloud CLI，请在 Cloud Shell 中输入以下命令：

gcloud components list

输出的前两行显示当前 gcloud CLI 安装的版本号以及最新的 gcloud CLI 的版本号。如果您发现自己的版本已过期，可以在 Cloud Shell 中输入以下命令，将 gcloud CLI 安装更新到最新版本：

gcloud components update

调试

您可以输入以下命令来调试 bq 命令行工具：

• 查看已发送和已接收的请求。添加 --apilog=PATH_TO_FILE 标志，将操作日志保存到本地文件。将 PATH_TO_FILE 替换为要用于保存日志的路径。bq 命令行工具工作时须进行基于 REST 的标准 API 调用来帮助进行查看。当您报告问题时，附上此日志也很有帮助。使用 - 或 stdout 代替路径会将日志打印到 Google Cloud Console。将 --apilog 设置为 stderr 可输出到标准错误文件。

• 排查错误在获取作业状态或查看有关资源（如表和数据集）的详细信息时，输入 --format=prettyjson 标志。使用此标志可输出 JSON 格式的响应，包括 reason 属性。您可以使用 reason 属性来查找问题排查步骤。