使用 bq 命令行工具

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

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

准备工作

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

  1. 登录您的 Google 帐号。

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

  2. 选择或创建 Google Cloud Platform 项目。

    转到“管理资源”页面

  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,请参阅以下内容:

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面