Access control

Overview

BigQuery uses Identity and Access Management (IAM) to manage access to resources. The three types of resources available in BigQuery are organizations, projects, and datasets. In the IAM policy hierarchy, datasets are child resources of projects. Tables and views are child resources of datasets — they inherit permissions from their parent dataset.

To grant access to a resource, assign one or more roles to a user, group, or service account. Organization and project roles affect the ability to run jobs or manage the project's resources, whereas dataset roles affect the ability to access or modify the data inside of a particular dataset.

IAM provides two types of roles: predefined and primitive roles. When you assign both predefined and primitive roles to a user, the permissions granted are a union of each role's permissions.

Permissions and roles

Predefined roles comparison matrix

You can assign the following BigQuery predefined roles.

Capability	dataViewer	dataEditor	dataOwner	metadataViewer	user	jobUser	admin
List/get projects
List tables
Get table metadata
Get table data
Create tables
Modify/delete tables
Get dataset metadata
Create new datasets
Modify/delete datasets					Self-created datasets
Create jobs/queries
Get jobs						Self-created jobs	Any jobs
List jobs					Any jobs (jobs from other users are redacted)		Any jobs
Cancel jobs					Self-created jobs	Self-created jobs	Any jobs
Get/list saved queries
Create/update/delete saved queries
Create a read session via the BigQuery BigQuery Storage API
Get transfers
Create/update/delete transfers

Permissions

The following table describes the permissions available in BigQuery.

Permission	Description
bigquery.jobs.create	Create new jobs.
bigquery.jobs.listAll	List all jobs and retrieve metadata on any job submitted by any user.*
bigquery.jobs.list	List all jobs and retrieve metadata on any job submitted by any user.* For jobs submitted by other users, details and metadata are redacted.
bigquery.jobs.get	Get data and metadata on any job.*
bigquery.jobs.update	Cancel any job.*
bigquery.datasets.create	Create new empty datasets.
bigquery.datasets.delete	Delete a dataset.
bigquery.datasets.get	Get metadata about a dataset.
bigquery.datasets.update	Update metadata for a dataset.
bigquery.tables.create	Create new tables.
bigquery.tables.list	List tables and metadata on tables.
bigquery.tables.delete	Delete tables.
bigquery.tables.get	Get table metadata. To get table data, you need bigquery.tables.getData.
bigquery.tables.getData	Get table data. To get table metadata, you need bigquery.tables.get.
bigquery.tables.export	Export table data out of BigQuery.
bigquery.tables.update	Update table metadata. To update table data, you need bigquery.tables.updateData.
bigquery.tables.updateData	Update table data. To update table metadata, you need bigquery.tables.update.
bigquery.transfers.get	Get transfer metadata.
bigquery.transfers.update	Create, update, and delete transfers.
bigquery.savedqueries.create	Create saved queries.
bigquery.savedqueries.get	Get metadata on saved queries.
bigquery.savedqueries.list	List saved queries.
bigquery.savedqueries.update	Update saved queries.
bigquery.savedqueries.delete	Delete saved queries.
bigquery.readsessions.create	Create a new read session via the BigQuery BigQuery Storage API.

* For any job you create, you automatically have the equivalent of the bigquery.jobs.get and bigquery.jobs.update permissions for that job.

Permissions required for methods

The following table lists the permissions that the caller must have to call each method:

Method	Required Permission(s)
datasets.delete	bigquery.datasets.delete If the targeted dataset is not empty, you also need bigquery.tables.delete.
datasets.get	bigquery.datasets.get
datasets.insert	bigquery.datasets.create
datasets.list	Uses bigquery.datasets.get to check permissions on returned datasets.
datasets.patch	bigquery.datasets.update
datasets.update	bigquery.datasets.update
jobs.cancel	bigquery.jobs.update You can cancel your own jobs without this permission.
jobs.get	bigquery.jobs.get You can get your own jobs without this permission.
jobs.getQueryResults	bigquery.jobs.get To get job results, you need bigquery.jobs.get permissions, or you need to be the job owner. In addition, you need to be the owner of the table into which the results of the job are written.
jobs.insert	bigquery.jobs.create to start the job Additional permissions might be necessary to complete the job.
jobs.list	bigquery.jobs.list to show all jobs from all users. Details and metadata are redacted for jobs submitted by other users. bigquery.jobs.listAll to show full details for all jobs from all users using the allUsers=true parameter.
jobs.query	bigquery.jobs.create to start the job Additional permissions might be necessary to complete the job.
projects.list	resourcemanager.projects.get
tabledata.insertAll	bigquery.tables.updateData
tabledata.list	bigquery.tables.getData
tables.delete	bigquery.tables.delete
tables.get	bigquery.tables.get
tables.insert	bigquery.tables.create If the method creates a view, it also needs bigquery.tables.getData permissions to all the tables referenced in the view.
tables.list	bigquery.tables.list
tables.patch	bigquery.tables.update
tables.update	bigquery.tables.update If the method updates a view, it also needs bigquery.tables.getData permissions to all the tables referenced in the view. If the view is already authorized on the dataset, the method also needs bigquery.datasets.update on all datasets associated with the tables.
projects.transferConfigs.create	bigquery.transfers.update
projects.transferConfigs.get	bigquery.transfers.get
projects.transferConfigs.patch	bigquery.transfers.update

Roles

The following table lists the Google BigQuery API IAM roles with a corresponding list of all the permissions each role includes. Note that every permission is applicable to a particular resource type.

Role	includes permission(s):	for resource type:
roles/bigquery.metadataViewer	resourcemanager.projects.get	Organization
	resourcemanager.projects.list	Organization
	bigquery.datasets.get	Dataset
	bigquery.tables.list	Dataset
	bigquery.tables.get	Dataset
roles/bigquery.dataViewer	All of the above, as well as:
	bigquery.tables.getData	Dataset
	bigquery.tables.export	Dataset
roles/bigquery.dataEditor	All of the above, as well as:
	bigquery.datasets.create	Project
	bigquery.tables.create	Dataset
	bigquery.tables.delete	Dataset
	bigquery.tables.update	Dataset
	bigquery.tables.updateData	Dataset
roles/bigquery.dataOwner	All of the above, as well as:
	bigquery.datasets.delete	Project
	bigquery.datasets.update	Dataset
roles/bigquery.user	resourcemanager.projects.get	Organization
	resourcemanager.projects.list	Organization
	bigquery.jobs.create	Project
	bigquery.jobs.list	Project
	bigquery.datasets.create	Project
	bigquery.datasets.get	Project
	bigquery.tables.list	Project
	bigquery.transfers.get	Project
	bigquery.savedqueries.get	Project
	bigquery.savedqueries.list	Project
	bigquery.readsessions.create	Project
roles/bigquery.jobUser	resourcemanager.projects.get	Organization
	bigquery.jobs.create	Project
roles/bigquery.readSessionUser	resourcemanager.projects.get	Organization
	resourcemanager.projects.list	Organization
	bigquery.readsessions.create	Project
roles/bigquery.admin	All permissions from other roles, as well as:
	bigquery.jobs.get	Project
	bigquery.jobs.listAll	Project
	bigquery.jobs.update	Project
	bigquery.savedqueries.create	Project
	bigquery.savedqueries.delete	Project
	bigquery.savedqueries.update	Project
	bigquery.transfers.update	Project

Predefined roles details

Predefined roles details
roles/bigquery. user	Permissions to run jobs, including queries, within the project. Most individuals (data scientists/analysts) in an enterprise should be users. The user role can enumerate their own jobs, cancel their own jobs, and enumerate datasets within a project. Additionally, allows the creation of new datasets within the project; the creator is granted the bigquery.dataOwner role for these new datasets. Rationale: This role allows the separation of data access from the ability to run work in the project, which is useful when team members query data from multiple projects. Dataset and table enumeration is included as a way to help users discover potential data sources. Resource Types: Organization Project
roles/bigquery. jobUser	Permissions to run jobs, including queries, within the project. The jobUser role can get information about their own jobs and cancel their own jobs. Rationale: This role allows the separation of data access from the ability to run work in the project, which is useful when team members query data from multiple projects. This role does not allow access to any BigQuery data. If data access is required, grant dataset-level access controls. Resource Types: Organization Project
roles/bigquery. readSessionUser	Permissions to create and use read sessions within the project via the BigQuery Storage API. Rationale: This role allows the separation of data access from the ability to create read sessions in the project. Users granted the bigquery.readSessionUser do not have access to table data. To read data, you must also grant bigquery.tables.getData permissions or provide READER access to the dataset that contains the tables. Resource Types: Organization Project
roles/bigquery. dataViewer	When applied to a dataset, dataViewer provides permissions to: Read the dataset's metadata and to list tables in the dataset. Read data and metadata from the dataset's tables. When applied at the project or organization level, this role can also enumerate all datasets in the project. Additional roles, however, are necessary to allow the running of jobs. For example, a user who merely has bigquery.dataViewer permissions on a dataset without any other permissions can only list the tables in the dataset and use the get() APIs to read the contents of the tables. The user cannot query the data without additional permissions. For an example of a user with permissions to run queries, consider the following scenario. A user who has bigquery.user permissions in projectA, and bigquery.dataViewer permissions on projectA:dataset1 and projectB:dataset2 can run a query in projectA that uses either or both of these datasets. For external data sources that reside outside of BigQuery storage, additional permissions from those non-BigQuery data sources might be necessary. Rationale: The dataViewer role is intended for read-only data access. The dataViewer can access data, but additional permissions, such as those granted by the bigquery.user or bigquery.admin roles, are necessary to issue query jobs. The dataViewer doesn’t have the ability to incur costs. Resource Types: Organization Project
roles/bigquery. metadataViewer	When applied at the organization or project level, metadataViewer provides permissions to: List all datasets and read metadata for all datasets in the project. List all tables and views and read metadata for all tables and views in the project. Additional roles are necessary to run jobs. Rationale: The metadataViewer role is intended for metadata-only access. The metadataViewer can access dataset, table, and view metadata, but additional permissions, such as those granted by the bigquery.user role are necessary to run query jobs. Resource Types: Organization Project
roles/bigquery. dataEditor	When applied to a dataset, dataEditor provides permissions to: Read the dataset's metadata and to list tables in the dataset. Create, update, get, and delete the dataset's tables. When applied at the project or organization level, this role can also create new datasets. Rationale: The dataEditor role extends bigquery.dataViewer by issuing create, update, delete privileges for the tables within the dataset, but not allowing mutations of the dataset itself. Resource Types: Organization Project Dataset
roles/bigquery. dataOwner	When applied to a dataset, dataOwner provides permissions to: Read, update, and delete the dataset. Create, update, get, and delete the dataset's tables. When applied at the project or organization level, this role can also create new datasets. Rationale: The dataOwner role extends bigquery.dataEditor by adding the ability to modify and delete the containing dataset. Resource Types: Organization Project Dataset
roles/bigquery. admin	Permissions to manage all resources within the project. Can manage all data within the project, and can cancel jobs from other users running within the project. Rationale: This is the highest level role with the broadest responsibilities, the superuser who supports their colleagues as they perform their various analyses. Resource Types: Organization Project

Custom roles

In addition to the pre-defined roles, BigQuery also supports custom roles. For more information, see Creating and Managing Custom Roles in the Cloud IAM documentation.

Note: Currently, you cannot apply a custom role to a dataset. For more information on dataset access controls, see Controlling access to datasets.

Unsupported permissions

The following permissions can only be added to custom roles at the organization level. They have no effect at the project level or below.

• resourcemanager.projects.list

The following permissions might be changed in backward-incompatible ways and are not recommended for production use. They are not subject to any SLA or deprecation policy.

• bigquery.config.get
• bigquery.config.update

Primitive IAM roles

The primitive IAM roles map directly to the legacy BigQuery viewer/editor/owner project roles and the reader/writer/owner dataset roles.

Transitioning from primitive roles

For users more familiar with the legacy authorization setup, BigQuery exposed a combination of primitive roles as the project level permissions (Reader, Writer, Owner).

For compatibility purposes, the per-dataset level legacy permissions map directly into their equivalent predefined roles.

BigQuery Legacy Permissions	IAM Equivalent
Project - Can View	Primitive Role - Viewer
Project - Can Edit	Primitive Role - Editor
Project - Is Owner	Primitive Role - Owner
Dataset - READER	bigquery.dataViewer
Dataset - WRITER	bigquery.dataEditor
Dataset - OWNER	bigquery.dataOwner

Primitive roles for projects

By default, granting access to a project also grants access to datasets within it. Default access can be overridden on a per-dataset basis. Any user with the project Owner role has the ability to revoke or change any project role.

When a project is created, BigQuery grants the Owner role to the user who created the project.

Primitive role	Capabilities
Viewer	Can start a job in the project. Additional dataset roles are required depending on the job type. Can list and get all jobs, and update jobs that they started for the project If you create a dataset in a project that contains any viewers, BigQuery grants those users the bigquery.dataViewer predefined role for the new dataset.
Editor	Same as Viewer, plus: Can create a new dataset in the project If you create a dataset in a project that contains any editors, BigQuery grants those users the bigquery.dataEditor predefined role for the new dataset.
Owner	Same as Editor, plus: Can list all datasets in the project Can delete any dataset in the project Can list and get all jobs run on the project, including jobs run by other project users If you create a dataset, BigQuery grants all project owners the bigquery.dataOwner predefined role for the new dataset. Exception: When a user runs a query, an anonymous dataset is created to store the cached results table. Only the user that runs the query is given OWNER access to the anonymous dataset.

Primitive roles for projects are granted or revoked through the Google Cloud Platform Console. You must have Owner access to the project in order to grant or revoke a new project role.

For more information about how to grant or revoke access for project roles, see Managing project members.

Primitive roles for datasets

The primitive roles for datasets are functionally equivalent to the predefined roles described in Transitioning from primitive roles.

Dataset roles can be granted to the following entity types:

Entity type	API
Single users, by email address	access.userByEmail
A Google Group, by email address	access.groupByEmail
A predefined group of users, such as all users, or a group of users that have the same project role for the project that contains the dataset	access.specialGroup

The following primitive roles apply to datasets:

Dataset role	Capabilities
READER	Can read, query, copy or export tables in the dataset Can call get on the dataset Can call get and list on tables in the dataset Can call list on table data for tables in the dataset
WRITER	Same as READER, plus: Can edit or append data in the dataset Can call insert, insertAll, update or delete Can use tables in the dataset as destinations for load, copy or query jobs
OWNER	Same as WRITER, plus: Can call update on the dataset Can call delete on the dataset Note: A dataset must have at least one entity with the OWNER role. A user with the OWNER role can't remove their own OWNER role.

When you create a new dataset, BigQuery adds default dataset access for the following entities. Roles that you specify on dataset creation overwrite the default values.

Entity	Dataset role
All users with Viewer access to the project	READER
All users with Editor access to the project	WRITER
All users with Owner access to the project	OWNER Exception: When a user runs a query, an anonymous dataset is created to store the cached results table. Only the user that runs the query is given OWNER access to the anonymous dataset.

Dataset roles are granted or revoked by using one of following options:

• Through the BigQuery API, using update
• Through the Web UI, by clicking the dropdown next to a dataset name, and then clicking Share dataset
• Through the `bq` command-line tool by using the `bq update` command. Use the `--source` flag to specify a JSON file containing a partial `dataset` resource with the `access` field set.

Example scenarios

The following examples involve a group of data scientists who all belong to a Google Group named AnalystGroup.

Read and write access to data in a dataset

CompanyProject is a project that includes dataset1 and dataset2. AnalystGroup1 is a group of data scientists who work only on dataset1 and AnalystGroup2 is a group that works only on dataset2. The data scientists should have full access only to the dataset that they work on, including access to run queries against the data.

Read and write access to a dataset
On dataset CompanyProject:dataset1	Grant AnalystGroup1 WRITER access on dataset1. This role maps to the predefined IAM role — bigquery.dataEditor.
On dataset CompanyProject:dataset2	Grant AnalystGroup2 WRITER access on dataset2. This role maps to the predefined IAM role — bigquery.dataEditor.
On project CompanyProject	Grant AnalystGroup1 and AnalystGroup2 bigquery.user access on CompanyProject.

Giving the data scientists WRITER access at the dataset level gives them the ability to query data in the dataset's tables, but it does not give them permissions to run query jobs in the project. To be able to run query jobs against a dataset they've been given access to, the data scientist groups must be granted the project-level, predefined role — bigquery.user. The bigquery.user role grants bigquery.jobs.create permissions.

Alternatively, you can add the data scientist groups to a project-level, IAM custom role that grants bigquery.jobs.create permissions.

Full access to data in a project

AnalystGroup is a group of data scientists working on BigQuery, responsible for all facets of its use within a project named CompanyProject. The group prefers for all members to have read and write access to all data. Other groups at the organization work with other Cloud Platform products, but no one else interacts with BigQuery. AnalystGroup does not use any other Cloud Platform services.

Full access to data in a project
On project CompanyProject	Add AnalystGroup to the predefined role bigquery.admin.

Full access across an organization

CompanyA is an organization that wants a specific person, named Admin1, to be the administrator for all BigQuery data across all of their projects. MonitoringServiceAccount is a service account that's responsible for monitoring the size of all the tables across all projects in the organization.

Full access across an organization
On organization CompanyA	Add Admin1 to the predefined role bigquery.admin. Add MonitoringServiceAccount to the predefined role bigquery.dataViewer.

If the company decides that MonitoringServiceAccount should also trim the size of tables that exceed a certain size and remove data that is older than a specific time period, MonitoringServiceAccount would need to be added to the predefined role bigquery.user.

Read access to data in the same project

AnalystGroup is a set of data scientists responsible for analytics services within a project named CompanyProject. OperationsServiceAccount is a service account that's responsible for loading application logs into BigQuery via bulk load jobs to a specific CompanyProject:AppLogs dataset. The analysts are not allowed to modify the logs.

Read access to data in the same project
On project CompanyProject	Add OperationsServiceAccount to the predefined role bigquery.user. Add AnalystGroup to the predefined role bigquery.user.
On dataset CompanyProject:AppLogs	Add OperationsServiceAccount to the predefined role bigquery.dataEditor. Add AnalystGroup to the predefined role bigquery.dataViewer.

Read access to data in a different project

AnalystGroup is a set of data scientists responsible for analytics services within a project named CompanyAnalytics. The data they analyze, however, resides in a separate project named CompanyLogs. OperationsServiceAccount is a service account that's responsible for loading application logs into BigQuery via bulk load jobs to a variety of datasets in the CompanyLogs project.

AnalystGroup can only read data in the CompanyLogs project and cannot create additional storage or run any query jobs in that project. Instead, the analysts use project CompanyAnalytics to perform their work, and maintain their output within the CompanyAnalytics project.

Read access to data in a different project
On project CompanyLogs	Add OperationsServiceAccount to the predefined role bigquery.admin. Add AnalystGroup to the predefined role bigquery.dataViewer.
On project CompanyAnalytics	Add AnalystGroup to the predefined role bigquery.user.

Programmatic manipulation of roles

You can use the following methods to manipulate the predefined roles at the dataset,

project, and organization level programmatically.

• For datasets, the dataset.insert, dataset.update, and dataset.patch operations allow for fine-grained role settings on individual Datasets through the access field.

• For project-level and organization-level settings, use organizations.setIamPolicy and projects.setIamPolicy to add and remove users and service accounts from IAM roles.