Changes to dataset-level access controls

Starting Mar 17 2026, thebigquery.datasets.getIamPolicyIdentity and Access Management (IAM) permission isrequired to view a dataset's access controls and to query theINFORMATION_SCHEMA.OBJECT_PRIVILEGESview. Thebigquery.datasets.setIamPolicy permission is required to update adataset's access controls or tocreate a dataset with access controls using theAPI.

Opt into early enforcement

Before Mar 17, 2026, you can opt into early enforcement of the permissionchanges. When you opt in, thebigquery.datasets.getIamPolicy permission isnecessary to get a dataset's access controls, and thebigquery.datasets.setIamPolicy permission is necessary to update a dataset'saccess controls or to create a dataset with access controls using the API.

To opt into early enforcement, set theenable_fine_grained_dataset_acls_optionconfiguration setting toTRUE at the organization or project level. Forinstructions on enabling configuration settings, seeManage configurationsettings.

Configuration setting examples

The following examples show you how to set and remove theenable_fine_grained_dataset_acls_option configuration setting.

Configure organization settings

To configure organization settings, use theALTER ORGANIZATION SET OPTIONS DDL statement.The following example setsenable_fine_grained_dataset_acls_option toTRUEat the organization level:

ALTERORGANIZATIONSETOPTIONS(`region-REGION.enable_fine_grained_dataset_acls_option`=TRUE);

ReplaceREGION with theregionassociated with your organization—for example,us oreurope-west6.

The following example clears the organization-levelenable_fine_grained_dataset_acls_option setting:

ALTERORGANIZATIONSETOPTIONS(`region-REGION.enable_fine_grained_dataset_acls_option`=FALSE);

Configure project settings

To configure project settings, use theALTER PROJECT SET OPTIONS DDL statement.TheALTER PROJECT SET OPTIONS DDL statement optionally accepts theproject_id variable. If theproject_id is not specified, it defaults to thecurrent project where the query runs.

The following example setsenable_fine_grained_dataset_acls_option toTRUE.

ALTERPROJECTPROJECT_IDSETOPTIONS(`region-REGION.enable_fine_grained_dataset_acls_option`=TRUE);

ReplacePROJECT_ID with your project ID.

The following example clears the project-levelenable_fine_grained_dataset_acls_option setting:

ALTERPROJECTPROJECT_IDSETOPTIONS(`region-REGION.enable_fine_grained_dataset_acls_option`=FALSE);

Changes to custom roles

This change to the required permissions impacts existing custom roles that grantbigquery.datasets.get,bigquery.datasets.create, orbigquery.datasets.update permission and don't also grant thebigquery.datasets.getIamPolicy orbigquery.datasets.setIamPolicy permission.

Any custom roles that only include thebigquery.datasets.get,bigquery.datasets.update, orbigquery.datasets.create permission must beupdated to include thebigquery.datasets.getIamPolicy orbigquery.datasets.setIamPolicy permission by Mar 17, 2026, if you wantto maintain the existing functionality of the custom roles. If your custom rolesneed to view or update only a dataset's metadata, use the newdataset_view andupdate_mode parameters.

BigQuery predefined roles arenot affected by this change. Allpredefined roles that grant thebigquery.datasets.get permission alsogrant thebigquery.datasets.getIamPolicy permission. All predefined roles thatgrant thebigquery.datasets.update permission also grant thebigquery.datasets.setIamPolicy permission.

Changes to bq command-line tool commands

When you opt into early enforcement, the following bq tool commands areaffected.

bq show

You can use thebq showcommand with the following flag:

--dataset_view={METADATA|ACL|FULL}

Specifies how to apply permissions when you're viewing a dataset's accesscontrols or metadata.Use one of the following values:

• METADATA: view only the dataset's metadata. This value requiresthebigquery.datasets.get permission.
• ACL: view only the dataset's access controls. This value requiresthebigquery.datasets.getIamPolicy permission.
• FULL: view both the dataset's metadata and access controls. Thisvalue requires thebigquery.datasets.get permission andbigquery.datasets.getIamPolicy permissions.

bq update

You can use thebq updatecommand with the following flag:

--update_mode={UPDATE_METADATA|UPDATE_ACL|UPDATE_FULL}

Specifies how to apply permissions when you're updating a dataset's accesscontrols or metadata.Use one of the following values:

• UPDATE_METADATA: update only the dataset's metadata. This valuerequires thebigquery.datasets.update permission.
• UPDATE_ACL: update only the dataset's access controls. This valuerequires thebigquery.datasets.setIamPolicy permission.
• UPDATE_FULL: update both the dataset's metadata and access controls.This value requires thebigquery.datasets.update permission andbigquery.datasets.setIamPolicy permissions.

Changes to data control language (DCL) statements

When you opt into early enforcement, the following permissions are required torunGRANT andREVOKE statements on datasets using thedata control language(DCL):

• bigquery.datasets.setIamPolicy

Changes toINFORMATION_SCHEMA view queries

When you opt into early enforcement, thebigquery.datasets.getIamPolicypermission is required to query theINFORMATION_SCHEMA.OBJECT_PRIVILEGESview.

Changes to API methods

After you opt into early enforcement, the following REST v2 API dataset methodsare affected.

datasets.get method

Thedatasets.get method hasan additionalpath parameternameddataset_view.

This parameter gives you more control over the information returned by thedatasets.get method. Rather than always returning both access controls andmetadata, thedataset_view parameter lets you specify whether to return justmetadata, just access controls, or both.

Theaccess field in thedataset resourcecontains the dataset's access controls. The other fields such asfriendlyName,description, andlabels represent the dataset's metadata.

The following table shows the required permission and API response for thedifferent values supported by thedataset_view parameter:

If you don't opt into early enforcement, or if you opt out after opting in, youcan use thedataset_view parameter with theMETADATA orACL values. TheFULL andDATASET_VIEW_UNSPECIFIED (or empty) values default to the previousbehavior; thebigquery.datasets.get permission lets you get both metadataand access controls.

Example

The following example sends aGET request with thedataset_viewparameter set toMETADATA:

GET https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?datasetView=METADATA&key=YOUR_API_KEY HTTP/1.1

Replace the following:

• YOUR_PROJECT: the name of your project
• YOUR_DATASET: the name of the dataset
• YOUR_API_KEY: your API key

datasets.update method

Thedatasets.update methodhas an additionalpath parameternamedupdate_mode.

This parameter gives you more control over the fields updated by thedatasets.update method. Rather than always allowing updates to both accesscontrols and metadata, theupdate_mode parameter lets you specify whether toupdate just metadata, just access controls, or both.

Theaccess field in thedataset resourcecontains the dataset's access controls. The other fields such asfriendlyName,description, andlabels represent the dataset's metadata.

The following table shows the required permission and API response for thedifferent values supported by theupdate_mode parameter:

If you don't opt into early enforcement, or if you opt out after opting in,BigQuery default's to the previousbehavior; thebigquery.datasets.update permission lets you update bothmetadata and access controls.

Example

The following example sends aPUT request with theupdate_mode parameter set toMETADATA:

PUT https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?updateMode=METADATA&key=YOUR_API_KEY HTTP/1.1

Replace the following:

• YOUR_PROJECT: the name of your project
• YOUR_DATASET: the name of the dataset
• YOUR_API_KEY: your API key name

datasets.patch method

Thedatasets.patch methodhas an additionalpath parameternamedupdate_mode.

This parameter gives you more control over the fields updated by thedatasets.patch method. Rather than always allowing updates to both accesscontrols and metadata, theupdate_mode parameter lets you specify whether toupdate just metadata, just access controls, or both.

Theaccess field in thedataset resourcecontains the dataset's access controls. The other fields such asfriendlyName,description, andlabels represent the dataset's metadata.

The following table shows the required permission and API response for thedifferent values supported by theupdate_mode parameter:

If you don't opt into early enforcement, or if you opt out after opting in,BigQuery default's to the previousbehavior; thebigquery.datasets.update permission lets you update bothmetadata and access controls.

Example

The following example sends aPUT request with theupdate_mode parameter set toMETADATA:

PUT https://bigquery.googleapis.com/bigquery/v2/projects/YOUR_PROJECT/datasets/YOUR_DATASET?updateMode=METADATA&key=YOUR_API_KEY HTTP/1.1

Replace the following:

• YOUR_PROJECT: the name of your project
• YOUR_DATASET: the name of the dataset
• YOUR_API_KEY: your API key name

datasets.insert method

If you opt into early enforcement and use thedatasets.insert method,to create a dataset with access controls, BigQuery verifiesthat thebigquery.datasets.create andbigquery.datasets.setIamPolicypermissions are granted to the user.

If you use the API to create a dataset without access controls, onlythebigquery.datasets.create permission is required.