管理默认配置

本文档介绍了如何在组织或项目级create和检索默认配置设置。

为帮助管理作业，您可以在 BigQuery 中配置默认设置。使用此服务的设置在组织或项目级配置，但可以在会话或作业级替换。您可以将默认设置与相关的组织政策结合使用，以强制执行默认行为。

价格

使用 BigQuery 配置服务无需额外费用。如需了解详情，请参阅价格。

默认配置

您可以指定以下默认配置设置：

default_batch_query_queue_timeout_ms：批量查询加入队列的默认时间（以毫秒为单位）。如果未设置，则默认值为 24 小时。最小值为 1 毫秒。最大值为 48 小时。如需停用批量查询排队，请将值设置为 -1。
default_column_name_character_map：列名称中的字符的默认范围和处理方式。如果未设置，则在列名称中使用不受支持的字符的加载作业会失败，并显示错误消息。某些较旧的表可能会设置为替换列名称中不受支持的字符。如需了解详情，请参阅 load_option_list。
default_interactive_query_queue_timeout_ms：交互式查询排队的默认时间（以毫秒为单位）。如果未设置，则默认值为 6 小时。最小值为 1 毫秒。最大值为 48 小时。如需停用交互式查询排队，请将值设置为 -1。
default_kms_key_name：用于加密表数据（包括临时表或匿名表）的默认 Cloud Key Management Service 密钥。如需了解详情，请参阅客户管理的 Cloud KMS 密钥。
default_query_job_timeout_ms：查询作业超时后的默认时间，包括作业排入队列的时间和运行时间。超时时间段必须介于 5 分钟到 6 小时之间。
default_query_optimizer_options：基于历史记录的查询优化。此选项可以是以下各项之一：
- 'adaptive=on'：使用基于历史记录的查询优化。
- 'adaptive=off'：不使用基于历史记录的查询优化。
- NULL（默认）：使用默认的基于历史记录的查询优化设置，这相当于 'adaptive=off'。
default_time_zone：在依赖时区的 SQL 函数中使用的默认时区（如果未将显式时区指定为参数）。此配置不适用于时间单位列分区表（使用 UTC 作为时区）、Storage Transfer Service 时间表转移或使用 bq 命令行工具加载数据。如需了解详情，请参阅时区。
default_storage_billing_model：新数据集的默认存储空间结算模式。将值设置为 PHYSICAL 可在计算存储费用时使用物理字节，设置为 LOGICAL 可使用逻辑字节。请注意，更改默认存储空间结算模式不会影响现有数据集。如需了解详情，请参阅存储空间结算模式。
default_max_time_travel_hours：新数据集的默认时间旅行窗口（以小时为单位）。此时长必须介于 48 到 168 之间（含边界值），且必须能被 24 整除。更改默认最大时间旅行小时数不会影响现有数据集。如需了解详情，请参阅时间旅行。

创建默认配置

本部分介绍如何创建配置。

所需权限

如需创建配置，您需要 bigquery.config.update Identity and Access Management (IAM) 权限。预定义的 IAM 角色 roles/bigquery.admin 包含创建配置所需的权限。

警告：如果您要设置默认 Cloud Key Management Service 密钥，则必须向项目或组织中使用的所有 BigQuery 服务账号授予 Encrypter/Decrypter 角色。如果项目或组织中的服务账号没有适当的权限，则该服务账号中的所有查询都将失败。如需分配 Encrypter/Decrypter 角色，请参阅分配 Encrypter/Decrypter 角色。如果您没有先分配适当的角色，因此未正确设置默认 Cloud Key Management Service 密钥，则可以通过将值设置为 NULL 来清除默认密钥。如需查看示例，请参阅本文档中的配置组织设置和配置项目设置。同样，如果要设置默认时区，请确保使用 DATETIME 字面量的所有现有查询均不受影响。这包括使用显式 DATETIME 关键字的查询、以参数形式传递给 DATETIME_DIFF('2022-10-01', ...)、PARSE_DATETIME() 函数等时间函数的隐式转换字符串字面量。因此，仅在新项目上设置 default_time_zone 参数会更安全。

如需详细了解 BigQuery 中的 IAM 角色和权限，请参阅预定义的角色和权限。

配置默认设置

您可以使用以下 SQL 语句在组织或项目级配置默认设置。创建配置时，您必须指定配置适用的区域。每个语句只能使用一个区域。

配置组织设置

如需配置组织设置，请使用 ALTER ORGANIZATION SET OPTIONS DDL 语句。下面的示例将默认时区设置为 America/Chicago，将默认 Cloud KMS 密钥设置为用户定义的密钥，将默认查询超时设置为 30 分钟，将默认交互式查询队列超时设置为 10 分钟，并将默认批量查询队列超时设置为 20 分钟：

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.default_time_zone`= 'America/Chicago',
  -- Ensure all service accounts under the organization have permission to KMS_KEY
  `region-REGION.default_kms_key_name` = KMS_KEY,
  `region-REGION.default_query_job_timeout_ms` = 1800000,
  `region-REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `region-REGION.default_batch_query_queue_timeout_ms` = 1200000,
  `region-REGION.default_storage_billing_model`= PHYSICAL,
  `region-REGION.default_max_time_travel_hours` = 72);

替换以下内容：

REGION：与您的项目或组织相关联的区域。例如 us 或 europe-west6。
KMS_KEY：用户定义的 Cloud KMS 密钥。如需详细了解 Cloud KMS 密钥，请参阅客户管理的 Cloud KMS 密钥。

下面的示例清除所有组织级默认设置：

ALTER ORGANIZATION
SET OPTIONS (
  `region-REGION.default_time_zone` = NULL,
  `region-REGION.default_kms_key_name` = NULL,
  `region-REGION.default_query_job_timeout_ms` = NULL,
  `region-REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `region-REGION.default_batch_query_queue_timeout_ms` = NULL,
  `region-REGION.default_storage_billing_model`= NULL,
  `region-REGION.default_max_time_travel_hours` = NULL);

配置项目设置

如需配置项目设置，请使用 ALTER PROJECT SET OPTIONS DDL 语句。ALTER PROJECT SET OPTIONS DDL 语句可以选择接受 project_id 变量。如果未指定 project_id，则默认为运行查询的当前项目。下面的示例将默认时区设置为 America/Los_Angeles，将默认 Cloud KMS 密钥设置为示例密钥，将默认查询超时设置为 1 小时，将默认交互式查询队列超时设置为 10 分钟以及将默认的批量查询队列超时为 20 分钟：

ALTER PROJECT project_id
SET OPTIONS (
  `region-REGION.default_time_zone` = 'America/Los_Angeles',
  -- Ensure all service accounts under the project have permission to KMS_KEY
  `region-REGION.default_kms_key_name` = KMS_KEY,
  `region-REGION.default_query_job_timeout_ms` = 3600000,
  `region-REGION.default_interactive_query_queue_timeout_ms` = 600000,
  `region-REGION.default_batch_query_queue_timeout_ms` = 1200000,
  `region-REGION.default_storage_billing_model`= PHYSICAL,
  `region-REGION.default_max_time_travel_hours` = 72);

下面的示例清除所有项目级的默认设置。默认设置使用任何组织级默认设置（如果存在）。否则，所有默认设置都会设置为全局默认值。

ALTER PROJECT project_id
SET OPTIONS (
  `region-REGION.default_time_zone` = NULL,
  `region-REGION.default_kms_key_name` = NULL,
  `region-REGION.default_query_job_timeout_ms` = NULL,
  `region-REGION.default_interactive_query_queue_timeout_ms` = NULL,
  `region-REGION.default_batch_query_queue_timeout_ms` = NULL,
  `region-REGION.default_storage_billing_model`= NULL,
  `region-REGION.default_max_time_travel_hours` = NULL);

项目级配置会覆盖组织级配置。项目级配置又可能会被会话级配置覆盖，会话级配置可能会被作业级配置覆盖。

检索配置值

您可以通过查看信息架构来查看组织或项目的默认配置设置。如需查询三种不同的视图：

INFORMATION_SCHEMA.PROJECT_OPTIONS：应用于项目的配置
INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS：应用于项目的有效配置。有效配置包括在项目级设置的所有配置以及项目从组织继承的所有设置
INFORMATION_SCHEMA.ORGANIZATION_OPTIONS：应用于组织的配置

新配置可能需要几分钟才能生效并在 INFORMATION_SCHEMA 视图中反映。

所需权限

如需检索配置值，您需要拥有 bigquery.config.get IAM 权限。

以下预定义的 IAM 角色均包含从 INFORMATION_SCHEMA 视图获取配置所需的权限：

roles/bigquery.jobUser
roles/bigquery.dataEditor
roles/bigquery.dataUser

如需详细了解 BigQuery 中的 IAM 角色和权限，请参阅预定义的角色和权限。

示例

如需查看 us 区域中的组织下的配置，请运行下面的查询：

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

如需查看 us 区域中默认项目下的有效配置，请运行下面的查询：

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

如需查看 us 区域中默认项目下的配置，请运行下面的查询：

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;