管理默认配置

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

为帮助管理作业,您可以在 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 包含创建配置所需的权限。

如需详细了解 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:与您的项目或组织相关联的区域。例如 useurope-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 视图中反映。

所需权限

如需检索配置值,您需要拥有 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;