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

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
On dataset CompanyProject:AppLogs

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
On project CompanyAnalytics

Programmatic manipulation of roles

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

project, and organization level programmatically.

Send feedback about...

BigQuery Documentation