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 inherit permissions from the dataset that contains it.

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, whereas dataset roles affect the ability access or modify the data inside of a project.

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	user	admin
List/get tables
Read tables/metadata
Modify/delete tables
List/get datasets
Create new datasets
Modify/delete datasets
Create jobs/queries
Cancel jobs				Self-created jobs	Any jobs

Permissions

The following table describes the permissions available in BigQuery.

Permission	Description
bigquery.jobs.create	Create new jobs.
bigquery.jobs.list	List all jobs and retrieve metadata on any job.*
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.list	List datasets and metadata on 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.

* For any job you create, you automatically have the equivalent of the bigquery.jobs.list, 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.insert
datasets.list	bigquery.datasets.list Also 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 You can get your own jobs without this permission.
jobs.insert	bigquery.jobs.create to start the job Additional permissions might be necessary to complete the job.
jobs.list	bigquery.jobs.list
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.

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.dataViewer	resourcemanager.projects.get	Organization
	bigquery.datasets.list	Project
	bigquery.datasets.get	Dataset
	bigquery.tables.list	Dataset
	bigquery.tables.get	Dataset
	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
	pubsub.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
	bigquery.jobs.create	Project
	bigquery.jobs.list	Project
	bigquery.datasets.create	Project
	bigquery.datasets.list	Project
	bigquery.datasets.get	Project
	bigquery.tables.list	Project
roles/bigquery.admin	all permissions from other roles

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. 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 Dataset
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

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 Is granted the bigquery.dataViewer role by default for any new dataset in the project
Editor	Same as Viewer, plus: Can create a new dataset in the project Is granted the bigquery.dataEditor role by default for any new dataset in the project
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 Is granted the bigquery.dataOwner role by default for any new dataset in the project

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	Project 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

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

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 access only to the dataset that they work on and should not be able to run queries.

Full access to a dataset
On dataset CompanyProject:dataset1	Add AnalystGroup1 to the predefined role bigquery.dataOwner.
On dataset CompanyProject:dataset2	Add AnalystGroup2 to the predefined role bigquery.dataOwner.

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 CompanyProject. 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.