bq 命令行工具参考文档

本文档介绍了 bq 命令行工具（BigQuery 命令行工具）的语法、命令、标志和参数。本指南的目标读者是熟悉 BigQuery，但希望了解如何使用特定 bq 命令行工具的用户。如需了解有关如何使用 bq 命令行工具的一般信息，请参阅使用 bq 命令行工具。

摘要

bq 命令行工具使用以下格式：

bq COMMAND [FLAGS] [ARGUMENTS]

某些标志可与多个 bq 命令行工具命令搭配使用；全局标志部分介绍了这些标志。

其他标志是特定于命令的；它们只能与特定的 bq 命令行工具命令搭配使用。命令部分中介绍了特定于命令的标志。

布尔值标志

某些 bq 命令行工具标志是布尔值；您可以将该标志的值设置为 true 或 false。bq 命令行工具接受使用以下格式来设置布尔值标志。

值	格式	示例
true	--FLAGNAME=true	--debug_mode=true
true	--FLAGNAME	--debug_mode
false	--FLAGNAME=false	--debug_mode=false
false	--noFLAGNAME	--nodebug_mode

本文档对布尔值标志使用 --FLAGNAME=VALUE 格式。

所有布尔值标志都是可选项；如果布尔值标志不存在，则 BigQuery 会使用该标志的默认值。

为标志指定值

在为标志指定值时，等号 = 为可选项。例如，以下两个命令是等效的：

bq ls --format prettyjson myDataset
bq ls --format=prettyjson myDataset

为清楚起见，本文档使用等号。

在线帮助

bq 命令行工具中提供了文档，如下所示：

说明	帮助命令格式	示例
列出所有命令及示例	bq help	bq help
全局标志的说明	bq --help	bq --help
特定命令的说明	bq help COMMAND	bq help mk

资源规范

用于指定资源的格式取决于上下文；在某些情况下，项目和数据集之间的分隔符是英文冒号 (:)，在某些情况下，它是英文句点 (.)。下表介绍了如何在不同上下文中指定 BigQuery 表。

Context	格式	示例
bq 命令行工具	PROJECT:DATASET.TABLE	myProject:myDataset.myTable
标准 SQL 查询	PROJECT.DATASET.TABLE	myProject.myDataset.myTable
旧版 SQL 查询	PROJECT:DATASET.TABLE	myProject:myDataset.myTable

如果您未指定项目，则 BigQuery 将使用当前项目。例如，如果当前项目为 myProject，则 BigQuery 会将 myDataset.myTable 解释为 myProject:myDataset.myTable（或 myProject.myDataset.myTable）。

某些资源标识符必须使用反引号 (`) 进行引用。如果您的资源标识符以字母或下划线字符开头，且仅包含字母、数字和下划线字符，则无需用引号进行引用。但是，如果您的资源标识符包含其他类型的字符或预留关键字，您需要将该标识符（或包含特殊字符或预留关键字的标识符部分）用反引号括起来。如需了解详情，请参阅标识符。

全局标志

您可以将以下标志与任何 bq 命令结合使用（如适用）：

--api=ENDPOINT

指定要调用的 API 端点。默认值为 https://www.googleapis.com。

--api_version=VERSION

指定要使用的 API 版本。默认值为 v2。

--apilog=FILE

将所有 API 请求和响应记录到 FILE 指定的文件中。可能的值如下：

• 文件的路径 - 记录到指定文件
• stdout - 记录到标准输出
• stderr - 记录到标准错误
• false - 系统不会记录 API 请求和响应（默认值）

--bigqueryrc=PATH

指定 bq 命令行工具配置文件的路径。如果未指定 --bigqueryrc 标志，则命令会使用 BIGQUERYRC 环境变量。如果未设置环境变量，则使用 $HOME/.bigqueryrc。如果该文件不存在，则系统会使用 ~/.bigqueryrc。如需了解详情，请参阅为命令行标志设置默认值。

--ca_certificates_file=PATH

指定 Certificate Authority Service (CA) 文件的位置。

--dataset_id=DATASET_ID

指定要与命令搭配使用的默认数据集。系统会在不适用的情况下忽略此标志。您可以使用 PROJECT:DATASET 或 DATASET 格式指定 DATASET_ID 参数。 如果缺少 PROJECT 部分，则使用默认项目。您可以通过指定 --project_id 标志来替换默认项目设置。

--debug_mode={true|false}

如果设置为 true，则系统会显示 Python 异常的回溯。默认值为 false。

--disable_ssl_validation={true|false}

如果设置为 true，则系统会启用 HTTPS 证书验证。默认值为 false。

--discovery_file=PATH

指定为了发现而要读取的 JSON 文件。

--enable_gdrive={true|false}

如果此标志设置为 false，则系统会请求一个不包含 Google 云端硬盘范围的新 OAuth 令牌。默认值为 true；系统会请求一个包含云端硬盘范围的新 OAuth 令牌。

--fingerprint_job_id={true|false}

如需使用派生自作业配置指纹的作业 ID，请设置为 true。这能防止同一个作业意外运行多次。默认值为 false。

--format=FORMAT

此标志指定命令输出的格式。请使用以下某个值：

• pretty：设置了格式的表输出
• sparse：较为简单的表输出
• prettyjson：简单易读的 JSON 格式
• json：极其紧凑的 JSON
• csv：带有标题的 csv 格式

pretty、sparse 和 prettyjson 用于提供人类可读的信息。json 和 csv 旨在供其他程序使用。如果指定了 none，则命令不会产生任何输出。如果没有 --format 标志，则根据命令选择适当的输出格式。

--headless={true|false}

如需在无用户互动的情况下运行 bq 会话，请设置为 true。例如，debug_mode 不会进入调试程序，信息输出的频率会降低。默认值为 false。

--httplib2_debuglevel=DEBUG_LEVEL

此标志指定是否显示 HTTP 调试信息。如果 DEBUG_LEVEL 大于 0，则除了错误消息之外，此命令还会将 HTTP 服务器请求和响应记录到 stderr。如果 DEBUG_LEVEL 不大于 0，或者未使用 --httplib2_debuglevel 标志，则仅会提供错误消息。

例如：

--httplib2_debuglevel=1

注意：此标志不支持多级层调试，因此您可以将 DEBUG_LEVEL 设置为任意正数。

--job_id=JOB_ID

为新作业指定作业标识符。此标志仅适用于创建作业的命令：cp、extract、load 和 query。如果您不使用 --job_id 标志，则此命令会生成一个唯一的作业标识符。如需了解详情，请参阅以编程方式运行作业。

--job_property=KEY:VALUE

此标志表示要在作业配置的属性字段中包含的键值对。重复使用此标志可指定多个额外属性。

--location=LOCATION

此标志表示与您的单区域或多区域位置相对应的字符串。在您使用 --jobs 标志显示有关作业的信息时，bq cancel 命令和 bq show 命令需要此位置标志。对于以下命令，此位置标志为可选项。

• query
• cp
• load
• extract
• partition
• update
• wait
• mk（在您使用 --dataset 标志创建数据集时）

所有其他命令均会忽略 --location 标志。

注意：--location 标志是在 bq 版本 2.0.29 中推出的。如需验证 bq 命令行工具的版本，请输入 bq version。

--max_rows_per_request=MAX_ROWS

此标志表示一个整数，它指定了每次读取时返回的最大行数。

--project_id=PROJECT

指定要用于命令的项目。

--proxy_address=PROXY

此标志指定要用于连接到 Google Cloud 的代理主机的名称或 IP 地址。

--proxy_password=PASSWORD

此标志指定在向代理主机进行身份验证时要使用的密码。

--proxy_port=PORT

此标志指定要用于连接到代理主机的端口号。

--proxy_username=USERNAME

此标志指定在向代理主机进行身份验证时要使用的用户名。

--quiet={true|false} 或 -q={true|false}

如需在作业运行期间禁止状态更新，请设置为 true。默认值为 false。

--synchronous_mode={true|false} 或 -sync={true|false}

如需创建作业并立即返回成功完成状态作为错误代码，请设置为 false。如果此标志设置为 true，则此命令会等待作业完成后再返回，并返回作业完成状态作为错误代码。默认值为 true。

--trace=token:TOKEN

指定要包含在 API 请求中包含的跟踪记录令牌。

已弃用的全局标志

以下用于从文件指定 bq 命令行工具标志的全局标志已弃用。如需从文件指定标志，请使用 --bigqueryrc 标志。

--flagfile=PATH

如果指定此标志，则所提供的文件中的标志定义会插入 bq 命令行工具。默认值为 ''。如需了解详情，请参阅为命令行标志设置默认值。

命令

以下各部分介绍了 bq 命令行工具命令及其特定于命令的标志和参数。

bq add-iam-policy-binding

使用 bq add-iam-policy-binding 命令，只需一步即可检索表或视图的 Identity and Access Management (IAM) 政策并向该政策添加绑定。

此命令是执行以下三个步骤的替代方法：

1. 使用 bq get-iam-policy 命令检索政策文件（采用 JSON 格式）。
2. 修改政策文件
3. 使用 bq set-iam-policy 命令通过新绑定更新政策。

摘要

bq add-iam-policy-binding [FLAGS] --member=MEMBER_TYPE:MEMBER --role=ROLE
  [--table] RESOURCE

示例

bq add-iam-policy-binding --member=user:[e-mail] \
  --role=roles/bigquery.dataViewer myDataset.myTable

标志和参数

bq add-iam-policy-binding 命令使用以下标志和参数：

--member=MEMBER_TYPE:MEMBER

必需。使用 --member 标志可以指定 IAM 政策绑定的成员部分。--member 标志必须与 --role 标志同时指定。--member 和 --role 标志的一个组合等同于一个绑定。

MEMBER_TYPE 值用于指定 IAM 政策绑定中的成员类型。请使用以下某个值：

• user
• serviceAccount
• group
• domain

MEMBER 值用于指定 IAM 政策绑定中的成员的电子邮件地址或网域。

--role=ROLE

必需。此标志指定 IAM 政策绑定的角色部分。--role 标志必须与 --member 标志同时指定。--member 和 --role 标志的一个组合等同于一个绑定。

--table={true|false}

如需在 RESOURCE 参数不是表标识符或视图标识符时返回错误，请将 --table 标志设置为 true。默认值为 false。支持此标志以与其他命令保持一致。

RESOURCE

要添加到其政策的表或视图。

如需了解详情，请参阅 IAM 政策参考文档。

bq cancel

使用 bq cancel 命令可取消 BigQuery 作业。

摘要

bq [--synchronous_mode=false] cancel JOB_ID

示例

bq cancel bqjob_12345

bq --synchronous_mode=false cancel bqjob_12345

标志和参数

bq cancel 命令使用以下标志和参数：

--synchronous_mode=false

如果您不想等待 bq cancel 命令完成，请将全局 --synchronous_mode 标志设置为 false。默认值为 true。

JOB_ID

要取消的作业。

如需详细了解如何使用 bq cancel 命令，请参阅管理作业。

bq cp

使用 bq cp 命令执行以下任务：

• 创建表、表克隆或表快照的副本。
• 创建表克隆。
• 创建表快照。

摘要

bq cp [FLAGS] SOURCE_TABLE DESTINATION_TABLE

示例

bq cp myDataset.myTable myDataset.myTableCopy

标志和参数

bq cp 命令使用以下标志和参数：

--append_table={true|false} 或 -a={true|false}

要将表附加到现有表，请设置为 true。 默认值为 false。

--clone={true|false}

如需创建表克隆，请设置为 true。源表可以是标准表、表克隆或表快照。目标表是表克隆。默认值为 false；如果 --clone=true 和 --snapshot=true 均未指定，则目标表与源表的类型相同。

--destination_kms_key=KEY

此标志指定用于加密目标表数据的 Cloud KMS 密钥资源 ID。

例如：

--destination_kms_key=projects/myProject/locations/global/keyRings/myKeyRing/cryptoKeys/myKey

--expiration=SECONDS

表快照到期前的秒数。如果未添加此标志，则表快照到期时间设置为包含新表快照的数据集的默认到期时间。与 --snapshot 标志搭配使用。

--force={true|false} 或 -f={true|false}

如需在无提示的情况下覆盖目标表（如果存在），请设置为 true。默认值为 false；如果存在目标表，此命令会在覆盖之前先提示进行确认。

--no_clobber={true|false} 或 -n={true|false}

如需禁止覆盖目标表（如果存在），请设置为 true。默认值为 false；如果目标表存在，则会覆盖该表。

--restore={true|false}

此标志即将被弃用。如需通过表快照创建一个可写入表，请使用 bq cp 命令或 bq cp --clone 命令。

--snapshot={true|false}

如需创建 SOURCE_TABLE 参数中指定的表的表快照，请设置为 true。源表可以是标准表、表克隆或其他表快照。默认值为 false；如果 --clone=true 和 --snapshot=true 均未指定，则目标表与源表的类型相同。需要用到 --no_clobber 标志。

SOURCE_TABLE

此标志表示要复制的表。

DESTINATION_TABLE

此标志表示要复制到的表。

如需详细了解如何使用 cp 命令，请参阅以下内容：

• 复制表
• 创建表克隆
• 创建表快照
• 恢复表快照

bq extract

使用 bq extract 命令可将表数据导出到 Cloud Storage。

摘要

bq extract [FLAGS] RESOURCE DESTINATION

示例

bq extract --compression=GZIP --destination_format=CSV --field_delimiter=tab \
    --print_header=false myDataset.myTable gs://my-bucket/myFile.csv.gzip

bq extract --destination_format=CSV --field_delimiter='|' myDataset.myTable \
  gs://myBucket/myFile.csv

标志和参数

bq extract 命令使用以下标志和参数：

--compression=COMPRESSION_TYPE

指定用于导出文件的压缩类型。可能的值如下：

• GZIP
• DEFLATE
• SNAPPY
• NONE

默认值为 NONE。

如需了解每种压缩类型支持的格式，请参阅导出格式和压缩类型。

--destination_format=FORMAT

此标志指定导出的数据的格式。可能的值如下：

• CSV
• NEWLINE_DELIMITED_JSON
• AVRO
• PARQUET

默认值为 CSV。

--field_delimiter=DELIMITER

对于 CSV 导出文件，请指定用于标记输出文件中各列之间边界的字符。该分隔符可以是任何 ISO-8859-1 单字节字符。您可以使用 \t 或 tab 指定制表符分隔符。

--print_header={true|false}

如需禁止针对带有标题的格式输出标题行，请设置为 false。默认值为 true；包含标题行。

RESOURCE

此标志表示要从中导出数据的表。

DESTINATION

此标志表示接收导出的数据的存储位置。

如需详细了解如何使用 bq extract 命令，请参阅导出表数据。

bq get-iam-policy

使用 bq get-iam-policy 命令可检索资源的 IAM 政策并将其输出到 stdout。资源可以是表或视图。此政策采用 JSON 格式。

摘要

bq get-iam-policy [FLAGS] RESOURCE

示例

bq get-iam-policy myDataset.myTable

标志和参数

bq get-iam-policy 命令使用以下标志和参数：

--table={true|false} 或 --t={true|false}

要在 RESOURCE 不是表标识符或视图标识符时返回错误，请将 --table 标志设置为 true。默认值为 false。支持此标志以与其他命令保持一致。

RESOURCE

此标志表示要获取其政策的表或视图。

如需详细了解 bq get-iam-policy 命令，请参阅使用 IAM 控制对资源的访问权限。

bq head

使用 bq head 命令显示表的指定行和列。默认情况下，系统会显示前 100 行的所有列。

摘要

bq head [FLAGS] [TABLE]

示例

bq head --max_rows=10 --start_row=50 --selected_fields=field1,field3 \
  myDataset.myTable

标志和参数

bq head 命令使用以下标志和参数：

--job=JOB or -j=JOB

如需读取查询作业的结果，请指定此标志并提供有效的作业 ID。

--max_rows=MAX or -n=MAX

此标志表示一个整数，指示了在显示表数据时要输出的行数上限。默认值为 100。

--selected_fields=COLUMN_NAMES or -c=COLUMN_NAMES

此标志表示一个英文逗号分隔列表，指定了在显示表数据时要返回的部分字段（包括嵌套字段和重复字段）。如果未指定此标志，则系统会返回所有列。

--start_row=START_ROW or -s=START_ROW

此标志表示一个整数，指定了在显示表数据之前要跳过的行数。默认值为 0；表数据从第一行开始。

--table={true|false} 或 -t={true|false}

如需在命令参数不是表或视图时返回错误，请设置为 true。默认值为 false。支持此标志以与其他命令保持一致。

TABLE

此标志表示您要检索其数据的表。

如需详细了解如何使用 bq head 命令，请参阅管理表数据。

bq help

使用 bq help 命令可在 bq 命令行工具中显示其文档。

摘要

bq help [COMMAND]

标志和参数

bq help 命令使用以下标志和参数：

COMMAND

此标志指定要获取其在线帮助的特定 bq 命令行工具命令。

bq insert

使用 bq insert 命令可通过流式插入将以换行符分隔的 JSON 格式的数据行从文件插入表中。数据类型会被转换以匹配目标表的列类型。此命令仅用于测试目的。如需将数据流式传输到 BigQuery 中，请使用 insertAll API 方法。

摘要

bq insert [FLAGS] TABLE FILE

示例

bq insert --ignore_unknown_values --template_suffix=_insert myDataset.myTable /tmp/myData.json

echo '{"a":1, "b":2}' | bq insert myDataset.myTable

标志和参数

bq insert 命令使用以下标志和参数：

--ignore_unknown_values={true|false} 或 -i={true|false}

如果此标志设置为 true，BigQuery 会忽略与表架构不匹配的任何键值对，并插入所含数据与该架构匹配的行。如果此标志设置为 false，则系统不会插入所含数据与表架构不匹配的行。默认值为 false。

--skip_invalid_rows={true|false} 或 -s={true|false}

如果此标志设置为 true，则 BigQuery 会尝试插入所有有效行，即使存在无效行也是如此。如果此标志置为 false，则在存在任何无效行时，该命令会失败。默认值为 false。

--template_suffix=SUFFIX or -x=SUFFIX

指定此标志时，系统会将目标表 TABLE 视为基本模板，并将行插入到名为 {destination}{templateSuffix} 的实例表中。BigQuery 会使用基本模板的架构创建实例表。

TABLE

此标志表示要向其中插入数据的表。

FILE

此标志表示包含您要插入的数据的文件。

如需详细了解如何使用 bq insert 命令，请参阅将数据流式插入到 BigQuery。

bq load

使用 bq load 命令可将数据加载到表中。

摘要

bq load [FLAGS] DESTINATION_TABLE SOURCE_DATA [SCHEMA]

示例

bq load myDataset.newTable gs://mybucket/info.csv ./info_schema.json

标志和参数

bq load 命令使用以下标志和参数：

--allow_jagged_rows={true|false}

如需允许 CSV 数据末尾缺少可选列，请设置为 true。

--preserve_ascii_control_characters={true|false}

如需允许 CSV 数据中嵌入的 ASCII 控制字符，请设置为 true。

--allow_quoted_newlines={true|false}

如需允许 CSV 数据中包含带英文引号的换行符，请设置为 true。

--autodetect={true|false}

如需为 CSV 和 JSON 数据启用架构自动检测功能，请设置为 true。默认值为 false。如果 --autodetect 为 false，且未使用 --schema 标志指定任何架构，并且存在目标表，则使用目标表的架构。

--clustering_fields=COLUMNS

此标志表示一个以英文逗号分隔的列名称列表（最多包含 4 个列名称），指定了要用于表聚簇的字段。

--destination_kms_key=KEY

此标志指定用于加密目标表数据的 Cloud KMS 密钥资源 ID。

--encoding=ENCODING_TYPE or -E=ENCODING_TYPE

数据中使用的字符编码。请使用以下某个值：

• ISO-8859-1（也称为 Latin-1）
• UTF-8

--field_delimiter=DELIMITER or -F=DELIMITER

指定用于标记数据中各列之间边界的字符。该分隔符可以是任何 ISO-8859-1 单字节字符。您可以使用 \t 或 tab 指定制表符分隔符。

--ignore_unknown_values={true|false}

如果此标志设置为 true，则对于 CSV 和 JSON 文件，系统会忽略所含额外列值与表架构不匹配的行，并且不会加载这些行。同样，对于 Avro、Parquet 和 ORC 文件，系统会忽略表架构中不存在的文件架构中的字段，并且不会加载这些字段。

--json_extension=JSON_TYPE

指定要加载的 JSON 文件类型。仅适用于 JSON 文件。可能的值如下：

• GEOJSON - 以换行符分隔的 GeoJSON 文件

如需使用此标志，必须将 --source_format 标志设置为 NEWLINE_DELIMITED_JSON。

如需了解详情，请参阅加载以换行符分隔的 GeoJSON 文件。

--max_bad_records=MAX

此标志表示一个整数，指定了作业中允许的最大错误记录数量，超过此数量之后，整个作业就会失败。默认值为 0。无论 --max_bad_records 值是多少，任意类型的错误最多返回 5 个。此标志仅适用于加载 CSV、JSON 和 Google 表格数据。

--null_marker=STRING

此标志表示一个可选的自定义字符串，该字符串代表 CSV 数据中的一个 NULL 值。

--projection_fields=PROPERTY_NAMES

如果将 --source_format 设置为 DATASTORE_BACKUP，则此标志表示要从 Datastore 导出文件中加载哪些实体属性。以英文逗号分隔的列表形式指定属性名称。属性名称区分大小写，且必须是顶级属性。您还可以将此标志与 Firestore 导出文件一起使用。

--quote=CHARACTER

此标志指定用于括起 CSV 数据中字段的英文引号字符。CHARACTER 参数可以是任何单字节字符。默认值为英文双引号 (")。 如需指定没有英文引号字符，请使用空字符串 ""。

--replace={true|false}

如需在加载新数据时清空任何现有数据和架构，请设置为 true。除非您指定 --destination_kms_key 标志，否则所有 Cloud KMS 密钥也会被移除。默认值为 false。

注意：您可以使用 TRUNCATE TABLE 语句从表中移除所有行，而无需删除架构。

--schema={SCHEMA_FILE|SCHEMA}

此标志指定本地 JSON 架构文件的路径，或英文逗号分隔的列定义列表（采用 FIELD:DATA_TYPE, FIELD:DATA_TYPE 形式，以此类推）。如果您使用架构文件，请勿为其提供扩展名。

例如：

--schema=/tmp/tabledef

--schema=Region:STRING,Quarter:STRING,Total_sales:INTEGER

如果未指定架构，则 --autodetect 为 false，并且存在目标表，则系统会使用目标表的架构。

--schema_update_option=OPTION

在将数据附加到表时（在加载作业或查询作业中），或者覆盖表分区时，此标志可指定如何更新目标表的架构。请使用以下某个值：

• ALLOW_FIELD_ADDITION：允许添加新字段
• ALLOW_FIELD_RELAXATION：允许将 REQUIRED 字段放宽为 NULLABLE

重复使用此标志可指定多个架构更新选项。

--skip_leading_rows=NUMBER_OF_ROWS

此标志表示一个整数，指定了在源文件开头处要跳过的行数。 默认值为 0。

--source_format=FORMAT

此标志表示源数据的格式。请使用以下某个值：

• CSV
• NEWLINE_DELIMITED_JSON
• AVRO
• DATASTORE_BACKUP（将此值用于 Filestore）
• PARQUET
• ORC

--time_partitioning_expiration=SECONDS

此标志表示一个整数，指定了应在何时删除基于时间的分区（以秒为单位）。到期时间以分区的世界协调时间 (UTC) 日期加上这个整数值为准。负数表示无到期时间。

--time_partitioning_field=COLUMN_NAME

此标志指定用于确定如何创建基于时间的分区的字段。如果在未使用此值的情况下启用了基于时间的分区，表会根据加载时间进行分区。

--time_partitioning_type=INTERVAL

此标志会在表上启用基于时间的分区，并设置分区类型。请使用以下某个值：

• DAY
• HOUR
• MONTH
• YEAR

基于时间的分区的默认分区类型为 DAY。

--use_avro_logical_types={true|false}

如果 --source_format 标志设置为 AVRO，则将此标志设置为 true 可将逻辑类型转换为对应的类型（如 TIMESTAMP），而不是仅使用其原始类型（如 INTEGER）。

--decimal_target_types=DECIMAL_TYPE

此标志用于确定如何转换 Decimal 逻辑类型。与 JobConfigurationLoad.decimalTargetTypes 相同。重复使用此标志可以指定多个定位类型。

--parquet_enum_as_string={true|false}

如果 --source_format 标志设置为 PARQUET，并且您希望 BigQuery 将 Parquet ENUM 逻辑类型推断为 STRING 值，则将此标志设置为 true。默认值为 false。

--parquet_enable_list_inference={true|false}

如果 --source_format 标志设置为 PARQUET，则此标志表示是否对 Parquet LIST 逻辑类型使用架构推断。

--reference_file_schema_uri=URI

指定具有创建外部表的预期表架构的引用文件的路径。与 ExternalDataConfiguration.referenceFileSchemaUri 相同。系统会为 Avro、ORC 和 PARQUET 格式启用此标志。

DESTINATION_TABLE

此标志表示要向其中加载数据的表。

SOURCE_DATA

此标志表示包含要加载的数据的文件的 Cloud Storage URI。

SCHEMA

此标志表示目标表的架构。

如需详细了解如何使用 bq load 命令从 Cloud Storage 加载数据，请参阅以下内容：

• 加载 Avro 数据
• 加载 CSV 数据
• 加载 JSON 数据
• 加载 ORC 数据
• 加载 Parquet 数据
• 从 Datastore 导出文件中加载数据
• 从 Firestore 导出文件中加载数据

如需详细了解如何使用 bq load 命令从本地源加载数据，请参阅以下内容：

• 从本地文件加载数据。

bq ls

使用 bq ls 命令可列出集合中的对象。

摘要

bq ls [FLAGS] [RESOURCE]

示例

bq ls myDataset

标志和参数

bq ls 命令使用以下标志和参数：

--all={true|false} 或 -a={true|false}

如需显示所有结果，请设置为 true。显示来自所有用户或所有数据集（包括隐藏的数据集）的作业。在列出传输配置或传输运行时，不需要使用此标志。 默认值为 false。

--capacity_commitment={true|false}

如需列出容量承诺，请设置为 true 并使用 --location 标志指定该位置。如需了解详情，请参阅查看购买的承诺。

例如：bq ls --capacity_commitment=true --location='us'

--datasets={true|false} 或 -d={true|false}

如需列出数据集，请设置为 true。默认值为 false。

--filter="FILTER"

过滤列出的资源以匹配 FILTER 参数。

对于数据集，FILTER 包括一个或多个以空格分隔的三元组，格式为 labels.KEY:VALUE。如果提供了多个三元组，则命令仅会返回与所有三元组匹配的数据集（即命令使用 AND 逻辑运算符，而非OR）。如果您要指定多个三元组，则使用英文引号引起 FILTER 值。

• 如需根据数据集标签进行过滤，请使用您应用于数据集的键和值。

  例如：

  --filter "labels.department:marketing labels.team:sales"
  

对于转移作业配置，请将 dataSourceIds 用作键，并将以下数据源之一用作值：

• amazon_s3 - Amazon S3 数据转移
• dcm_dt - Campaign Manager 数据转移
• google_cloud_storage - Cloud Storage 数据转移
• cross_region_copy - 数据集副本
• dfp_dt- Google Ad Manager 数据转移
• adwords - Google Ads 数据转移
• google_ads - Google Ads 数据传输（预览版）
• merchant_center - Google Merchant Center 数据转移
• play - Google Play 数据转移
• scheduled_query - 计划查询数据传输
• doubleclick_search- Search Ads 360 数据转移
• youtube_channel - YouTube 频道数据转移
• youtube_content_owner - YouTube 内容所有者数据转移
• redshift - Amazon Redshift 迁移
• on_premises - Teradata 迁移

例如：

   --filter labels.dataSourceIds:dcm_dt
   

对于转移作业运行，请将 states 用作键，并将以下转移作业状态之一用作值： + SUCCEEDED + FAILED + PENDING + RUNNING + CANCELLED

 For example:
 <pre>
 --filter labels.states:FAILED
 </pre>

对于作业，过滤条件标志不受支持。

--jobs={true|false} 或 -j={true|false}

如需列出作业，请设置为 true。默认值为 false。默认情况下，结果数上限为 10 万个。

--max_creation_time=MAX_CREATION_TIME_MS

此标志是一个整数，表示时间戳（以毫秒为单位）。与 --jobs 标志一同指定时，此标志仅会列出在时间戳之前创建的作业。

--max_results=MAX_RESULTS or -n=MAX_RESULTS

此标志表示一个整数，用于指明最大结果数。默认值为 50，最大值为 1000。如果您的作业数量超过 1000 个，则可以使用 page_token 标志，通过分页列出所有作业。

--min_creation_time=MIN_CREATION_TIME_MS

此标志是一个整数，表示时间戳（以毫秒为单位）。与 --jobs 标志一同指定时，此标志仅会列出在时间戳之后创建的作业。

--message_type=messageTypes:MESSAGE_TYPE

如需仅列出特定类型的转移作业运行日志消息，请指定 messageTypes:MESSAGE_TYPE。可能的值如下：

• INFO
• WARNING
• ERROR

--models={true|false} 或 -m={true|false}

如需列出 BigQuery ML 模型，请设置为 true。默认值为 false。

--page_token=TOKEN 或 -k=TOKEN

此标志列出从指定的页面令牌开始的项。

--projects={true|false} 或 -p={true|false}

如需显示所有项目，请设置为 true。默认值为 false。

--reservation={true|false}

如需列出给定项目和位置的所有预留，请设置为 true。默认值为 false。与 --project_id 和 --location 标志搭配使用。

例如：

bq ls --reservation=true --project_id=myProject --location=us

--reservation_assignment={true|false}

如需列出给定项目和位置的所有预留分配，请设置为 true。默认值为 false。与 --project_id 和 --location 标志搭配使用。

--routines={true|false}

如需列出指定数据集中的所有例程，请设置为 true。默认值为 false。例程包括用户定义的永久性函数、表函数（预览版）和 存储过程。

--row_access_policies

指定此标志 时，系统会列出表的所有行级层访问权限政策。行级层访问权限政策用于行级层安全性。您必须以 dataset.table 格式提供表名称。

--run_attempt=RUN_ATTEMPT

与 --transfer_run 标志搭配使用。如需列出指定转移作业运行的所有运行尝试，请设置为 RUN_ATTEMPT_UNSPECIFIED。如需仅列出最新的运行尝试，请设置为 LATEST。默认值为 LATEST。

--transfer_config={true|false}

如需列出指定项目和位置中的转移作业配置，请设置为 true。与 --transfer_location 和 --project_id 标志搭配使用。默认值为 false。

--transfer_location=LOCATION

此标志列出指定位置的转移作业配置。您在创建传输时设置传输位置。

--transfer_log={true|false}

与 --transfer_run 标志搭配使用。如需列出指定转移作业运行的转移作业日志消息，请设置为 true。默认值为 false。

--transfer_run={true|false}

此标志列出指定转移作业配置的转移作业运行。

例如：

bq ls --transfer_run=true projects/myProject/locations/us/transferConfigs/12345

RESOURCE

此标志表示要列出其对象的集合。资源可以是数据集、项目、预留或转移作业配置。

如需详细了解如何使用 bq ls 命令，请参阅以下内容：

• 管理作业
• 列出项目中的数据集
• 创建和使用表
• 列出数据集中的视图
• 处理转移作业
• 列出数据集中的表快照

bq mk

使用 bq mk 命令可创建 BigQuery 资源。

摘要

bq mk TYPE_FLAG [OTHER FLAGS] [ARGS]

标志和参数

bq mk 命令接受一个类型标志，用于指定要创建的资源类型以及依赖于资源类型的其他标志。

TYPE_FLAG：将以下标志之一设置为 true。您的选择指定了要创建的资源类型。

• --capacity_commitment：购买容量承诺。

• --connection：创建连接。

• --dataset 或 -d：创建数据集。

• --materialized_view：创建具体化视图。

• --reservation：创建预留。

• --reservation_assignment：为预留分配文件夹、项目或组织。

• --table 或 -t：创建表。

• --transfer_config：创建转移作业配置。

• --transfer_run：为某个时间范围创建转移作业运行。

• --view：创建视图。

bq mk 命令支持所有类型的资源的以下标志：

--force={true|false} 或 -f={true|false}

如需在已存在同名资源的情况下忽略错误，请将该值设置为 true。如果资源已存在，则退出代码为 0，但将此标志设置为 true 不会导致 bq mk 命令覆盖资源。默认值为 false。

bq mk 命令支持其他标志，具体取决于您要创建的资源类型，如以下部分所述。

bq mk --capacity_commitment

如需购买容量承诺，请将 --capacity_commitment 设置为 true 并使用以下标志：

--location=LOCATION

指定承诺的位置。

--plan=PLAN_TYPE

指定承诺方案类型。设置为以下其中一项：

• FLEX
• MONTHLY
• ANNUAL

--renewal_plan=RENEWAL_TYPE

指定续订方案类型。仅适用于 ANNUAL 承诺方案。以下项之一：

• FLEX
• MONTHLY
• ANNUAL

--project_id=PROJECT_ID

此标志指定管理槽的项目。

--slots=NUMBER_OF_SLOTS

此标志指定要购买的槽数。

如需了解详情，请参阅购买槽。

bq mk --connection

创建连接。支持以下标志：

--connection_type=CONNECTION_TYPE

连接类型，例如对于 Cloud SQL 连接为 CLOUD_SQL。

--properties=PROPERTIES

JSON 格式的连接专属参数。必须指定 instanceId、database 和 type。

--connection_credential=CONNECTION_CREDENTIAL

JSON 格式的连接凭据。必须指定 username 和 password。

--project_id=PROJECT_ID

指定连接所属项目的 ID。

--location=LOCATION

指定将存储连接的存储位置。

--display_name=DISPLAY_NAME

为连接指定可选的好记名称。

--description=DESCRIPTION

指定连接的可选说明。

--iam_role_id=ROLE_ID

对于 BigQuery Omni on AWS，指定允许访问资源的 IAM 角色。

请使用以下格式："arn:aws:iam::AWS_ACCOUNT_ID:role/POLICY_NAME"，其中：

• AWS_ACCOUNT_ID 是连接的 AWS IAM 用户的 ID 号。
• POLICY_NAME 是政策名称。

示例："arn:aws:iam::0123456789AB:policy/s3-read-role"

--tenant_id=TENANT_ID

对于 Azure Omni on Azure，请指定包含 Azure Storage 帐号的 Azure 目录的租户 ID。

CONNECTION_ID

指定连接的可选连接 ID。如果未提供连接 ID，则系统会自动生成一个唯一 ID。连接 ID 可以包含字母、数字和下划线。

如需了解详情，请参阅创建连接。

bq mk --dataset

创建数据集。支持以下标志：

--default_kms_key=KEY

此标志指定在创建或查询表期间未明确提供密钥的情况下，用于加密数据集中的表数据的默认 Cloud KMS 密钥资源 ID。

--default_partition_expiration=SECONDS

此标志表示一个整数，用于指定数据集中新创建的分区表中所有分区的默认到期时间（以秒为单位）。分区的到期时间设置为分区的世界协调时间 (UTC) 日期加上这个整数值。如果设置了该属性，则该值将替换数据集级层的默认表到期时间（如果存在）。如果在创建或更新分区表时提供 --time_partitioning_expiration 标志，则表级层的分区到期时间优先于数据集级层的默认分区到期时间。

--default_table_expiration=SECONDS

此标志表示一个整数，用于指定数据集中新创建的表的默认生命周期（以秒为单位）。到期时间设置为当前世界协调时间 (UTC) 加上此值。

--description=DESCRIPTION

此标志指定数据集的说明。

--label=KEY:VALUE

指定数据集的标签。重复使用此标志可以指定多个标签。

--location=LOCATION 或 --data_location=LOCATION

指定数据集的位置。首选 --location 标志；--data_location 标志是旧版标志。

--max_time_travel_hours=HOURS

处于预览版阶段。指定数据集的时间旅行窗口的时长（以小时为单位）。--max_time_travel_hours 值必须是 48（2 天）到 168（7 天）之间的整数。如果未指定此标志，则默认值为 168 小时。

如需详细了解时间旅行窗口，请参阅配置时间旅行窗口。

--storage_billing_model=BILLING_MODEL

处于预览版阶段。指定数据集的存储计费模型。您可以将此标志值设置为 LOGICAL 以使用逻辑字节数进行存储计费，也可以设置为 PHYSICAL 以使用物理字节数。如果未指定此标志，则默认为 LOGICAL。

如需了解详情，请参阅数据集存储计费模型。

如需了解详情，请参阅创建数据集。

bq mk --materialized_view

创建具体化视图。支持以下标志：

--enable_refresh={true|false}

如需为具体化视图停用自动刷新功能，请设置为 false。创建具体化视图时，默认值为 true。

--refresh_interval_ms=MILLISECONDS

此标志指定具体化视图的刷新间隔毫秒数。如果未指定此标志，则启用了刷新功能的具体化视图的默认刷新间隔时间为 180 万毫秒，即 30 分钟。

如需了解详情，请参阅创建和使用具体化视图。

bq mk --reservation

使用专用槽创建预留。 支持以下标志：

--concurrency=CONCURRENCY

处于预览版阶段。指定同时执行的查询的目标数量。默认值为 0，表示系统会根据预留大小自动计算并发性。如需了解详情，请参阅使用查询队列。

--ignore_idle_slots={true|false}

如需将在此预留中运行的作业限制为仅使用分配给该预留的槽，请设置为 true。默认值为 false；此预留中的作业可以使用其他预留中的空闲槽，或使用未分配给任何预留的槽。如需了解详情，请参阅空闲槽。

--location=LOCATION

指定预留的位置。

--project_id=PROJECT_ID

此标志指定拥有预留的项目。

--slots=NUMBER_OF_SLOTS

此标志指定要分配给此预留的槽数。

如需了解详情，请参阅创建包含专用槽的预留。

bq mk --reservation_assignment

将项目、文件夹或组织分配到预留。 支持以下标志：

--assignee_id=ASSIGNEE_ID

此标志指定文件夹、组织或项目的 ID。

--assignee_type=ASSIGNEE_TYPE

此标志指定要分配给预留的实体类型。以下项之一：

• FOLDER
• ORGANIZATION
• PROJECT

--job_type=JOB_TYPE

此标志指定要分配给预留的作业类型。以下项之一：

• QUERY
• PIPELINE
• ML_EXTERNAL
• BACKGROUND

--location=LOCATION

指定预留的位置。

--project_id=PROJECT_ID

此标志指定拥有预留的项目。

--reservation_id=RESERVATION_ID

此标志指定预留的 ID。

如需了解详情，请参阅使用预留分配。

bq mk --table

创建一个表。支持以下标志：

--clustering_fields=COLUMNS

此标志表示一个以英文逗号分隔的列名称列表（最多包含 4 个列名称），指定了要用于表聚簇的字段。如果与分区一起指定，则系统首先会对表进行分区，然后使用所提供的列对每个分区进行聚簇。

--description=DESCRIPTION

指定表的说明。

--destination_kms_key=KEY

此标志指定用于加密目标表数据的 Cloud KMS 密钥资源 ID。

--expiration=SECONDS

指定表有效期。如果 SECONDS 为 0，则表不会过期。如果未指定 --expiration 标志，则 BigQuery 将使用数据集的默认表生命周期来创建表。

--external_table_definition=STRING

指定用于创建外部表的表定义。

对于 Cloud Storage 和 Google 云端硬盘外部表：

--external_table_definition={PATH_TO_FILE|DEFINITION}

其值可以是包含表定义 (PATH_TO_FILE) 或内嵌表定义 (DEFINITION) 的文件的路径。

• DEFINITION 字段的格式为 SCHEMA@FORMAT=URI。

• SCHEMA 值的格式是 FIELD:DATA_TYPE, FIELD:DATA_TYPE 形式的列定义列表（以英文逗号分隔），以此类推。 如果数据格式是自描述形式（例如 Avro），或者您使用的是架构自动检测功能，则可以省略 SCHEMA 值。

• FORMAT 值指定数据格式；为以下各项之一：

  • AVRO
  • CSV
  • DATASTORE_BACKUP（将此值用于 Filestore）
  • ICEBERG
  • NEWLINE_DELIMITED_JSON
  • ORC
  • PARQUET

如果您指定表定义文件，请勿为其提供扩展名。

例如：

--external_table_definition=/tmp/tabledef

--external_table_definition=Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv

对于 Cloud Bigtable 外部表以及基于 AWS 和 Azure 的 BigLake 表：

--external_table_definition=PATH_TO_FILE

该值必须是包含表定义的文件的路径。

对于基于 Cloud Storage 的 BigLake 表：

--external_table_definition=FORMAT=[e-mail]_NAME：

• FORMAT 值指定数据格式；为以下各项之一：

  • AVRO
  • CSV
  • NEWLINE_DELIMITED_JSON
  • ICEBERG
  • ORC
  • PARQUET

• BUCKET_PATH 是 Cloud Storage 中包含 BigLake 表数据的一个或多个文件的路径。您可以使用以下格式指定 BUCKET_PATH：

  • 对于单个文件：gs://bucket_name/[folder_name/]file_name。
  • 对于单个存储桶中的多个文件：gs://bucket_name/[folder_name/]*。

  • 对于多个存储桶中的多个文件：['gs://mybucket1/*', 'gs://mybucket2/folder5/*']。

    重要提示：如果您指定多个文件，则所有文件都必须具有兼容的架构。

    您可以使用通配符来限制 BigLake 表中包含的文件。例如，如果存储桶包含多种类型的数据，您可以通过指定 gs://bucket_name/*.parquet 让表仅使用 PARQUET 文件。如需详细了解如何使用通配符，请参阅 URI 通配符。

• REGION 值指定包含连接的区域或多区域。

• CONNECTION_NAME 值指定与此外部表结合使用的�