使用 bq 命令行工具

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

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

准备工作

在使用 bq 命令行工具之前，您必须使用 Google Cloud Console 创建或选择项目并安装 Cloud SDK。

  1. 登录您的 Google Cloud 帐号。如果您是 Google Cloud 新手，请创建一个帐号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

  2. 在 Google Cloud Console 的项目选择器页面上，选择或创建一个 Google Cloud 项目。

    转到“项目选择器”

  3. 安装并初始化 Cloud SDK。
  4. 新项目会自动启用 BigQuery。如需在预先存在的项目中激活 BigQuery，请转到 启用 BigQuery API。

    启用 API

  5. 如果您不想提供信用卡或为项目启用结算功能，BigQuery 会提供沙盒。无论您的项目是否启用了结算功能，本主题中的步骤都适用。如果您想启用结算功能，请参阅了解如何启用结算功能。

您可以在 Google Cloud Shell 中使用预安装版本的 Cloud SDK，而不是下载和安装 Cloud SDK。

定位标志和参数

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 命令行工具：

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

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

设置命令行标志的默认值

若要设置命令行标志的默认值，您可以在 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，以将调试输出打印到 Cloud Console。
  • 将全局标志 --format 设置为 prettyjson，以采用易于用户理解的 JSON 格式显示命令输出。
  • 将全局标志 --location 设置为 US 多区域位置。

  • 将 query 特定于命令的标志 --use_legacy_sql 设置为 false，以将标准 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 命令行工具，就如运行 gcloud 命令行工具命令一样。以下示例展示了 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 命令行工具加载数据，请参阅以下内容：

查询数据

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

使用外部数据源

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

导出数据

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

使用 BigQuery Data Transfer Service

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