使用 bq 命令行工具

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

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

准备工作

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

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号，请注册一个新帐号。

  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 --global_flag argument bq_command --command-specific_flag argument
  • 全局标志（或通用标志）适用于所有命令。
  • 特定于命令的标记适用于特定的命令。

请使用空格分隔多个全局标记或特定于命令的标记。例如：

bq \
--global_flag argument \
--global_flag argument \
bq_command \
--command-specific_flag argument \
--command-specific_flag argument

您可以使用以下某种方式指定命令参数：

  • --flag=argument
  • --flag='argument'
  • --flag="argument"
  • --flag argument
  • --flag 'argument'
  • --flag "argument"

以上这些方法都会在 BigQuery 文档中用到。

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

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

指定含布尔值的标志时，可不用参数。如果您指定 true 或 false，则必须指定 =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 命令行工具参考文档。

获取帮助

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

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

调试

您可以输入以下命令以调试 bq：

  • 查看发送和接收的请求
    添加 --apilog=path_to_file 标志，将操作日志保存到本地文件。bq 执行基于 REST 的标准 API 调用，以帮助进行查看。当您报告问题时，附上此日志也会有所帮助。使用 - 或 stdout 代替文件路径时，系统会在控制台中打印日志。将 --apilog 设置为 stderr 可输出标准错误文件。
  • 帮助排查错误
    在获取作业状态或查看有关资源（如表和数据集）的详细信息时输入 --format=prettyjson 标志。使用此标志可输出 JSON 格式的响应，包括 reason 属性。您可以使用 reason 属性查找问题排查步骤。

设置命令行标志的默认值

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

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

将标志添加到 .bigqueryrc

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

  • 在没有文件头的文件顶端添加全局标志
  • 若要添加特定于命令的标志，请输入命令名称（使用中括号），然后在下方逐一添加特定于命令的标志（每行一个），格式如下：
command
--command-specific_flag=argument
--command-specific_flag=argument

在 .bigqueryrc 中输入命令行标志时，必须采用 =argument 格式指定标志的参数。

每次运行 bq 时都会读取 .bigqueryrc，因此所做更改会立即更新。在交互模式 (bq shell) 中运行 bq 时，必须重启 shell 才能使更改生效。

示例

本示例将为以下全局标志设置默认值：

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

本示例将为以下特定于 query 命令的标志设置默认值：

  • 将 --use_legacy_sql 设置为 false，将标准 SQL 指定为默认查询语法。

  • 将 --max_rows 设置为 100，以控制查询输出中的行数。

  • 将 --maximum_bytes_billed 设置为 1 千万个字节 (10 MB)，使读取数据量超过 10 MB 的查询失败。

本示例将为以下特定于 load 命令的标志设置默认值：

  • 将 --destination_kms_key 设置为 projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey。
credential_file = path_to_credential_file
--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

要确认您的设置，请输入以下命令：

cat ~/.bigqueryrc

在交互式 shell 中运行 bq

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

示例

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

创建资源

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

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

获取资源相关信息

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

列出资源

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

更新资源

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

加载数据

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

查询数据

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

使用外部数据源

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

导出数据

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

使用 BigQuery Data Transfer Service

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