探索 bq 命令行工具

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

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

准备工作

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
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
系统会自动为新项目启用 BigQuery。如需在预先存在的项目中激活 BigQuery，请前往
Enable the BigQuery API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API
可选：为项目启用结算功能。如果您不想启用结算功能或提供信用卡，本文档中的步骤仍然有效。BigQuery 提供执行这些步骤的沙盒。如需了解详情，请参阅启用 BigQuery 沙盒。
注意：如果您的项目具有结算账号，并且您希望使用 BigQuery 沙盒，请为项目停用结算功能。

在 Cloud Shell 中输入 `bq` 命令

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

如需通过 Google Cloud 控制台使用 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 控制台中开发的查询并通过 bq 命令行工具运行该查询，请执行以下操作：

在 bq query 命令中包含该查询，如下所示：bq query --use_legacy_sql=false 'QUERY'。将 QUERY 替换为该查询。
设置查询字符串的格式。

如果您需要在查询中使用其他字符串字面量，则必须遵循所用 shell（例如 Bash 或 PowerShell）的引用规则。

以下示例展示了 Bash 中的典型方法，即使用双引号表示查询中的字符串字面量，然后用单引号将查询本身括起来：
```
'SELECT * FROM mydataset.mytable WHERE column1 = "value";'
```
如果要从其他位置复制查询，则还必须移除查询中的所有注释。

例如，将以下 Google Cloud 控制台查询：
```
-- 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。

将标志添加到 `.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，以将调试输出打印到Google Cloud 控制台。
将全局标志 --format 设置为 prettyjson，以采用易于用户理解的 JSON 格式显示命令输出。
将全局标志 --location 设置为 US 多区域位置。
将特定于 query 命令的标志 --use_legacy_sql 设置为 false，以将 GoogleSQL 设为默认查询语法。
注意：不能在 .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` 命令

您可以使用服务账号代表您来执行已获授权的 API 调用或运行查询作业。如需在 bq 命令行工具中使用服务账号，请向该服务账号授予对 Google Cloud 的访问权限。如需了解详情，请参阅 gcloud auth activate-service-account。

如需开始使用服务账号模拟运行 bq 命令，请运行以下命令：

gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME

将 SERVICE_ACCOUNT_NAME 替换为您的服务账号名称。

您运行的 bq 命令现在会使用服务账号凭据。

如需停止从服务账号运行 bq 命令，请运行以下命令：

gcloud config unset auth/impersonate_service_account

示例

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

创建资源

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

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

获取资源相关信息

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

列出资源

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

列出作业

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

列出作业

更新资源

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

正在加载数据

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

查询数据

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

使用外部数据源

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

导出数据

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

导出存储在 BigQuery 中的数据

使用 BigQuery Data Transfer Service

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

管理转移作业

排查 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 控制台。将 --apilog 设置为 stderr 可输出到标准错误文件。如需记录更多请求，请使用 --httplib2_debuglevel=LOG_LEVEL 标志。LOG_LEVEL 越高，日志中记录的有关 HTTP 请求的信息就越多。
排查错误在获取作业状态或查看有关资源（如表和数据集）的详细信息时，输入 --format=prettyjson 标志。使用此标志可输出 JSON 格式的响应，包括 reason 属性。您可以使用 reason 属性来查找问题排查步骤。如需详细了解执行过程中发生的任何错误，请使用 --debug_mode 标志。