使用 bq 命令行工具

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

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

准备工作

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

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册新帐号

  2. 在 Cloud Console 的项目选择器页面上,选择或创建 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'

指定含布尔值的标志时,可不用参数。如果您指定 truefalse,则必须指定 =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 属性查找问题排查步骤

设置命令行标志的默认值

若要设置命令行标志的默认值,您可以在命令行工具的配置文件 .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 资源)的链接。

创建资源

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

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

获取资源相关信息

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

列出资源

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

更新资源

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

加载数据

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

查询数据

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

使用外部数据源

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

导出数据

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

使用 BigQuery Data Transfer Service

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