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

* 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
`roles/bigquery.jobUser`	`resourcemanager.projects.get`	Organization
`roles/bigquery.jobUser`	`bigquery.jobs.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. 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.

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

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.

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

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.

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

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.