管理配置设置

本文档介绍如何在组织或项目级层指定和检索 BigQuery 配置设置。

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

配置设置

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

• default_batch_query_queue_timeout_ms：批量查询加入queued的默认时间（以毫秒为单位）。如果未设置，则默认值为 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 小时之间。 此超时仅适用于单个查询作业和脚本的子作业。如需为脚本作业设置超时，您应使用 jobs.insert API 方法并设置 jobTimeoutMs 字段。

• 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 整除。更改默认最大时间旅行小时数不会影响现有数据集。如需了解详情，请参阅时间旅行。

• default_cloud_resource_connection_id：创建表和模型时使用的默认连接。仅指定连接的 ID 或名称，不包括关联的项目 ID 和区域前缀。根据您要创建的表或模型的类型，使用默认连接可能会导致授予连接服务账号的权限被更新。如需了解详情，请参阅默认连接概览。

• default_sql_dialect_option：使用 bq 命令行工具或 BigQuery API 执行查询作业的默认 SQL 查询方言。更改此设置不会影响控制台中的默认方言。此选项可以是以下各项之一：

  • 'default_legacy_sql'（默认）：如果未在作业级层指定查询方言，则使用旧版 SQL。
  • 'default_google_sql'：如果未在作业级层指定查询方言，则使用 GoogleSQL。
  • 'only_google_sql'：如果未在作业级层指定查询方言，则使用 GoogleSQL。拒绝查询方言设置为旧版 SQL 的作业。
  • NULL：使用默认的查询方言设置，这相当于 'default_legacy_sql'。

• enable_reservation_based_fairness：确定如何共享空闲槽的选项。默认值为 false，这意味着空闲槽会平均分配到所有查询项目。如果启用，空闲槽会先在所有预留中平等共享，然后再在预留中的项目中平等共享。如需了解详情，请参阅基于预留的公平性。此选项仅在项目级层受支持。您无法在组织或作业级层指定此设置。

指定配置设置

本部分介绍如何指定配置设置。

所需权限

如需指定配置设置，您需要 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：与您的项目或组织相关联的区域。例如 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,
  `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID,
  `region-REGION.default_sql_dialect_option` = 'default_google_sql',
  `region-REGION.enable_reservation_based_fairness` = true);

替换以下内容：

• PROJECT_ID：项目的 ID。
• REGION：与您的项目或组织相关联的区域。例如 us 或 europe-west6。
• KMS_KEY：用户定义的 Cloud KMS 密钥。如需详细了解 Cloud KMS 密钥，请参阅客户管理的 Cloud KMS 密钥。
• CONNECTION_ID：表和模型的默认连接的 ID。

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

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,
  `region-REGION.default_cloud_resource_connection_id` = NULL,
  `region-REGION.default_sql_dialect_option` = 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;

价格

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