Manage default configuration settings

Default configuration settings in BigQuery can help your organization enforce security, control costs, and optimize query performance. As a BigQuery administrator or project owner, you can specify, remove, and retrieve these defaults at the organization and project levels, or override them for individual sessions and jobs.

Required roles

To get the permissions that you need to specify or retrieve configuration settings, ask your administrator to grant you the following IAM roles:

• Specify configuration settings: BigQuery Admin (roles/bigquery.admin) on your organization or project
• Retrieve configuration settings: BigQuery Job User (roles/bigquery.jobUser) on the specified project

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to specify or retrieve configuration settings. To see the exact permissions that are required, expand the Required permissions section:

You might also be able to get these permissions with custom roles or other predefined roles.

For more information about IAM roles and permissions in BigQuery, see Predefined roles and permissions.

Specify global settings

Global settings apply across all locations and don't use a region-REGION. prefix. In contrast, regional settings apply only to a specific location. You can specify global settings at the organization or project level. The default location (default_location) is the only global setting that you can configure.

If you don't explicitly specify a location, the location is determined in one of the following ways:

• The location of the datasets referenced in the request. For example, if a query references a table or view in a dataset stored in the asia-northeast1 region, the query job runs in asia-northeast1.
• The region specified for a connection referenced in a request.
• The location of a destination table.

If the location isn't explicitly specified, and it can't be determined from the resources in the request, the default location is used. If default location isn't set, the job runs in the US multi-region.

Limitations

Global configuration settings are subject to the following limitations:

• Global organization and project settings aren't supported in BigQuery Omni locations. You can't set default_location to a BigQuery Omni location, or configure or view global settings in a BigQuery Omni location.
• You can't mix global and regional settings in the same ALTER ORGANIZATION SET OPTIONS or ALTER PROJECT SET OPTIONS DDL statement.
• When you modify the default_location global setting, the change can take up to 10 minutes to propagate. Until the setting propagates, BigQuery might route jobs that rely on the default location to the previous default location.

Configure global organization settings

You can configure global settings at the organization level by using the ALTER ORGANIZATION SET OPTIONS DDL statement. The default location (default_location) is the only global setting that you can configure at the organization level. All other organization-level settings are regional settings.

The ALTER ORGANIZATION SET OPTIONS DDL statement applies to the organization that the current project belongs to.

To configure the default_location setting at the organization level, follow these steps:

  ALTER ORGANIZATION
  SET OPTIONS (
  `default_location` = 'LOCATION'
  );

  ALTER ORGANIZATION
  SET OPTIONS (
  `default_location` = NULL
  );

Configure global project settings

You can configure global settings at the project level by using the ALTER PROJECT SET OPTIONS DDL statement. The default location (default_location) is the only global setting that you can configure at the project level. All other project-level settings are regional settings.

The ALTER PROJECT SET OPTIONS DDL statement optionally accepts the PROJECT_ID variable. If you don't specify PROJECT_ID, then the statement defaults to the project where you run the ALTER PROJECT DDL statement.

Project-level configurations override organization-level configurations. In turn, session-level configurations can override project-level configurations, and job-level configurations can override session-level configurations.

To configure the default_location setting at the project level, follow these steps:

  ALTER PROJECT PROJECT_ID
  SET OPTIONS (
  `default_location` = 'LOCATION'
  );

  ALTER PROJECT PROJECT_ID
  SET OPTIONS (
  `default_location` = NULL
  );

Specify regional settings

Regional settings apply to a specific location and require a region-REGION. prefix. You can configure regional settings at the organization or project level.

Reservation and billing controls

You can configure regional project-level settings to control how queries use reservations or on-demand billing. These settings help ensure cost predictability by either allowing flexible reservation usage or requiring that queries use reservation slots.

Common reservation and billing controls include reservation_override_mode (Preview) and disable_on_demand_billing (Preview). To configure these settings, see Configure regional project settings. For a complete list of project options, see the ALTER PROJECT SET OPTIONS options list.

Configure regional organization settings

You can configure regional settings at the organization level by using the ALTER ORGANIZATION SET OPTIONS DDL statement. You must specify the region where each organization setting applies. You can use only one region in a statement.

The examples in this section specify the following default regional organization settings:

• Time zone: America/Chicago
• Cloud KMS key: a user-defined key
• Query timeout: 30 minutes (1,800,000 milliseconds)
• Interactive query queue timeout: 10 minutes (600,000 milliseconds)
• Batch query queue timeout: 20 minutes (1,200,000 milliseconds)
• Table storage and search index INFORMATION_SCHEMA views (enable_info_schema_storage): enabled

For more information about all regional organization settings, see organization_set_options_list.

To configure regional organization settings, follow these steps:

  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.enable_info_schema_storage` = true);

  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.enable_info_schema_storage` = NULL);

Configure regional project settings

You can configure regional settings at the project level by using the ALTER PROJECT SET OPTIONS DDL statement. You must specify the region where each project setting applies. You can use only one region in a statement.

Project-level configurations override organization-level configurations. In turn, session-level configurations can override project-level configurations, and job-level configurations can override session-level configurations.

The ALTER PROJECT SET OPTIONS DDL statement optionally accepts the PROJECT_ID variable. If you don't specify PROJECT_ID, then the statement defaults to the project where you run the ALTER PROJECT DDL statement.

The examples in this section specify the following default regional project settings:

• Time zone: America/Los_Angeles
• Cloud KMS key: a user-defined key
• Query timeout: 1 hour (3,600,000 milliseconds)
• Interactive query queue timeout: 10 minutes (600,000 milliseconds)
• Batch query queue timeout: 20 minutes (1,200,000 milliseconds)
• Reservation-based fairness: enabled
• Global queries: enabled for running and for accessing data
• Table storage and search index INFORMATION_SCHEMA views (enable_info_schema_storage): enabled

For more information about all regional project settings, see project_set_options_list.

To configure regional project settings, follow these steps:

  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.enable_reservation_based_fairness` = true,
  `region-REGION.enable_global_queries_execution` = true,
  `region-REGION.enable_global_queries_data_access` = true,
  `region-REGION.enable_info_schema_storage` = true);

  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.enable_reservation_based_fairness` = false,
  `region-REGION.enable_global_queries_execution` = NULL,
  `region-REGION.enable_global_queries_data_access` = NULL,
  `region-REGION.enable_info_schema_storage` = NULL);

Retrieve configuration settings

You can view the configuration settings for an organization or project by using the following INFORMATION_SCHEMA views:

• INFORMATION_SCHEMA.PROJECT_OPTIONS: the configurations applied to a project.
• INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS: the effective configurations applied to a project. Effective configurations include all configurations set at the project level as well as all settings inherited by the project from an organization.
• INFORMATION_SCHEMA.ORGANIZATION_OPTIONS: the configurations applied to an organization.

New configurations can take a few minutes to take effect and appear in the INFORMATION_SCHEMA views.

Query examples to retrieve settings

Use the following query examples to retrieve your project and organization settings from the INFORMATION_SCHEMA views.

View global settings

To view all global organization settings, run the following query:

SELECT * FROM INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

To view only the default_location organization setting, run the following query:

SELECT
    option_value
FROM INFORMATION_SCHEMA.ORGANIZATION_OPTIONS
WHERE option_name = 'default_location'

To view all effective global configurations for your default project, run the following query:

SELECT * FROM INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

To view only the effective default_location setting for your default project, run the following query:

SELECT
    option_value
FROM INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS
WHERE option_name = 'default_location'

To view all global configurations for your default project, run the following query:

SELECT * FROM INFORMATION_SCHEMA.PROJECT_OPTIONS;

To view only the default_location setting for your default project, run the following query:

SELECT
    option_value
FROM INFORMATION_SCHEMA.PROJECT_OPTIONS
WHERE option_name = 'default_location'

View regional settings

To view the configurations under an organization in the us region, run the following query:

SELECT * FROM region-us.INFORMATION_SCHEMA.ORGANIZATION_OPTIONS;

To view the effective configurations under your default project in the us region, run the following query:

SELECT * FROM region-us.INFORMATION_SCHEMA.EFFECTIVE_PROJECT_OPTIONS;

To view the configurations under your default project in the us region, run the following query:

SELECT * FROM region-us.INFORMATION_SCHEMA.PROJECT_OPTIONS;

Default configuration settings

The following sections describe the configuration settings that you can specify.

Query and job execution settings

Use the following settings to control how queries are executed, timed, and queued.

• default_batch_query_queue_timeout_ms: The default amount of time, in milliseconds, that a batch query waits in a query queue. If unset, the default is 24 hours. The minimum value is 1 millisecond. The maximum value is 48 hours. To turn off batch query queueing, set the value to -1.

• default_interactive_query_queue_timeout_ms: The default amount of time in milliseconds that an interactive query waits in a query queue. If unset, then the default is 6 hours. The minimum value is 1 millisecond, and the maximum value is 48 hours. To turn off interactive query queueing, set the value to -1.

• default_query_job_timeout_ms: The default time after which a query job times out, including the time the job is queued and the time spent running. The timeout period must be between 5 minutes and 48 hours. This timeout only applies to individual query jobs and the child jobs of scripts. To set a timeout for script jobs, use the jobs.insert API method and set the jobTimeoutMs field.

• default_location: The default_location configuration setting is used to run jobs when the location isn't set or can't be determined. If default_location isn't set, the job runs in the US multi-region. For more information, see Specify locations.

• enable_reservation_based_fairness: The option that determines how idle slots are shared. For administration projects created after October 10, 2026, this option is enabled (TRUE) by default. For projects created before October 10, 2026, default value is FALSE, which means that idle slots are distributed equally across all query projects. If you enable this option, then idle slots are shared equally across all reservations first, and then across projects within each reservation. For more information, see reservation-based fairness. This option is only supported at the project level. You can't specify it at the organization or job level.

• default_time_zone: The default time zone to use in time zone-dependent GoogleSQL functions, when a time zone is not specified as an argument. This configuration does not apply to time-unit column partitioned tables (which use UTC as the time zone), the Storage Transfer Service schedule transfers, or loading data with the bq command-line tool. For more information, see time zones.

• default_query_optimizer_options: The history-based query optimizations. This option can be one of the following:

  • 'adaptive=on': Use history-based query optimizations.
  • 'adaptive=off': Don't use history-based query optimizations.
  • NULL (default): Use the default history-based query optimizations setting, which is equivalent to 'adaptive=on'.

• default_sql_dialect_option: The default SQL query dialect for executing query jobs using the bq command-line tool or BigQuery API. Changing this setting doesn't affect the default dialect in the console. This option can be one of the following:

  • 'default_legacy_sql' (default): Use legacy SQL if the query dialect isn't specified at the job level.
  • 'default_google_sql': Use GoogleSQL if the query dialect isn't specified at the job level.
  • 'only_google_sql': Use GoogleSQL if the query dialect isn't specified at the job level. Reject jobs with query dialect set to legacy SQL.
  • NULL: Use the default query dialect setting, which is equivalent to 'default_legacy_sql'.

• enable_global_queries_execution: The option that determines whether global queries can run. The default value is FALSE, which means that global queries are not enabled.

• enable_global_queries_data_access: The option that determines whether global queries can access data stored in the region. The default value is FALSE, which means that global queries can't copy data from this region regardless of the project in which they run.

• reusable_column_aliases_mode: The option that determines whether reusable column aliases are enabled for queries. The default value is off, which means that reusable column aliases aren't enabled. For more information, see Reusable column aliases.

Data management settings

Use the following settings to define rules for data creation, security, and lifecycle.

• default_column_name_character_map: The default scope and handling of characters in column names. If unset, load jobs that use unsupported characters in column names fail with an error message. Some older tables might be set to replace unsupported characters in column names. For more information, see load_option_list.

• default_data_policy_projects: The default list of projects whose data policies are evaluated when accessing columns protected by data governance tags. By default, only the data policies of the table's project are evaluated. When you configure a default data policy project at the organization level, BigQuery evaluates both the data policies of the table's project and those of the default data policy project. If conflicting policies exist in both projects, the data policies in the table's project take precedence. You can configure this setting only at the organization level by using the ALTER ORGANIZATION SET OPTIONS statement—for example, region-us.default_data_policy_projects = ["my_default_project"]. For more information, see Configure a default data policy project.

• default_kms_key_name: The default Cloud Key Management Service key for encrypting table data, including temporary or anonymous tables. For more information, see Customer-managed Cloud KMS keys.

• default_max_time_travel_hours: The default time travel window in hours for new datasets. This duration must be within the range of 48 to 168, inclusive, and must be divisible by 24. Changing the default max time travel hours does not affect existing datasets. For more information, see Time Travel and data retention.

• enable_info_schema_storage: The option that provides access to INFORMATION_SCHEMA.TABLE_STORAGE and SEARCH_INDEXES views and their variants. By default, this option isn't enabled. If you query these views for the first time without setting this option to TRUE, then the query fails and provides instructions to enable the option. After you enable this option, queries succeed immediately and return data generated from that point forward. A complete backfill of historical data can take approximately one day to become available in the views. If you used these views before this setting was introduced, then this option is already enabled.

Cost and resource settings

Use the following settings to determine how resources are billed and connected.

• default_storage_billing_model: The default storage billing model for new datasets. Set the value to PHYSICAL to use physical bytes when calculating storage charges or to LOGICAL to use logical bytes. Changing the default storage billing model doesn't affect existing datasets. For more information, see Storage billing models.
• default_cloud_resource_connection_id: The default connection to use when you create tables and models. Specify only the connection's ID or name, and exclude the attached project ID and region prefixes. When you use default connections, BigQuery might update the permissions granted to the connection's service account, depending on the type of table or model that you're creating. For more information, see the Default connection overview.
• reservation_override_mode (Preview): Specifies how query reservations can be overridden in the region (for example, 'ALLOW_ANY_OVERRIDE'). For details, see the ALTER PROJECT SET OPTIONS options list.
• disable_on_demand_billing (Preview): Determines whether on-demand billing is disabled for queries in the region. If true, all queries must use an assigned reservation or they fail. For details, see the ALTER PROJECT SET OPTIONS options list.
• preflight_fluid_autoscaling_reservations: The list of reservations that are opted in to fluid scaling for per-second billing with no minimum duration. For more information, see Understand reservations.

Pricing

There is no additional charge to use the BigQuery configuration service. For more information, see BigQuery pricing.