BigQuery IAM roles and permissions
This document provides information on Identity and Access Management (IAM) roles and permissions for BigQuery. IAM lets you grant granular access to specific BigQuery resources and helps prevent access to other resources. IAM lets you apply the security principle of least privilege, which states that nobody should have more permissions than they actually need.
When a principal (a user, group, or service account) calls a Google Cloud API, that principal must have the appropriate IAM permissions to use the resource. To give a principal the required permissions, you grant an IAM role to the principal.
This document describes how to use predefined and custom IAM roles to allow principals to access BigQuery resources.
To familiarize yourself with managing access in Google Cloud in general, see IAM overview.
IAM role types
A role is a collection of permissions. You can use the following types of roles in IAM to provide access to BigQuery resources:
- Predefined roles are managed by Google Cloud and support common use cases and access control patterns.
- Custom roles provide access according to a user-specified list of permissions.
To determine if one or more permissions are included in a role, you can use one of the following methods:
- The IAM permissions search reference
- The
gcloud iam roles describecommand - The
roles.get()method in the IAM API
When you assign multiple role types to a user, the permissions granted are a union of each role's permissions.
For additional information on using IAM to access resources, see Granting, changing, and revoking access to resources in the IAM documentation.
For information on creating custom roles, see Creating and managing custom roles in the IAM documentation.
IAM roles in BigQuery
Permissions are not assigned directly to users, groups, or service accounts. Instead, users, groups, or service accounts are granted access to one or more predefined or custom roles to give them permissions to perform actions on resources.
You can grant access at the following BigQuery resource levels:
- Organizations, folders, or projects
- Connections
- Datasets
- Tables or views
- Policy tags, row access policies, or BigQuery data policies
Roles applied at an organization or Google Cloud project level
When you assign roles at the organization and project level, you provide permission to run BigQuery jobs or to access all of a project's BigQuery resources.
Roles applied at a dataset level
You can assign roles at the dataset level to provide access to a specific dataset, without providing complete access to the project's resources. In the IAM resource hierarchy, BigQuery datasets are child resources of projects. For more information on assigning roles at the dataset level, see Controlling access to datasets.
Roles applied to individual resources within datasets
You can assign roles individually to certain types of resources within datasets, without providing complete access to the dataset's resources.
Roles can be applied to individual resources of the following types:
- tables
- views
Roles cannot be applied to individual resources of the following types:
- routines
- models
For more information on assigning roles at the table or view level, see Controlling access to tables or views.
BigQuery predefined IAM roles
The following table lists the predefined BigQuery IAM roles with a corresponding list of all the permissions each role includes. Note that each permission is applicable to a particular resource type.
| Role | Permissions |
|---|---|
BigQuery Admin( Provides 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. Lowest-level resources where you can grant this role:
|
|
BigQuery Connection Admin( |
|
BigQuery Connection User( |
|
BigQuery Data Editor( When applied to a table or view, this role provides permissions to:
This role cannot be applied to individual models or routines. When applied to a dataset, this role provides permissions to:
When applied at the project or organization level, this role can also create new datasets. Lowest-level resources where you can grant this role:
|
|
BigQuery Data Owner( When applied to a table or view, this role provides permissions to:
This role cannot be applied to individual models or routines. When applied to a dataset, this role provides permissions to:
When applied at the project or organization level, this role can also create new datasets. Lowest-level resources where you can grant this role:
|
|
BigQuery Data Viewer( When applied to a table or view, this role provides permissions to:
This role cannot be applied to individual models or routines. When applied to a dataset, this role provides permissions to list all of the resources in the dataset (such as tables, views, snapshots, models, and routines) and to read their data and metadata with applicable APIs and in queries. 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. Lowest-level resources where you can grant this role:
|
|
BigQuery Filtered Data Viewer( Access to view filtered table data defined by a row access policy |
|
BigQuery Job User( Provides permissions to run jobs, including queries, within the project. Lowest-level resources where you can grant this role:
|
|
BigQuery Metadata Viewer( When applied to a table or view, this role provides permissions to:
This role cannot be applied to individual models or routines. When applied to a dataset, this role provides permissions to:
When applied at the project or organization level, this role provides permissions to:
Additional roles are necessary to allow the running of jobs. Lowest-level resources where you can grant this role:
|
|
BigQuery ObjectRef Admin( Administer ObjectRef resources that includes read and write permissions |
|
BigQuery ObjectRef Reader( Role for reading referenced objects via ObjectRefs in BigQuery |
|
BigQuery Read Session User( Provides the ability to create and use read sessions. Lowest-level resources where you can grant this role:
|
|
BigQuery Resource Admin( Administers BigQuery workloads, including slot assignments, commitments, and reservations. |
|
BigQuery Resource Editor( Manages BigQuery workloads, but is unable to create or modify slot commitments. |
|
BigQuery Resource Viewer( Can view BigQuery workloads, but cannot create or modify slot reservations or commitments. |
|
BigQuery Studio Admin( Combination role of BigQuery Admin, Dataform Admin, Notebook Runtime Admin and Dataproc Serverless Editor. |
|
BigQuery Studio User( Combination role of BigQuery Job User, BigQuery Read Session User, Dataform Code Creator, Notebook Runtime User and Dataproc Serverless Editor. |
|
BigQuery User( When applied to a dataset, this role provides the ability to read the dataset's metadata and list tables in the dataset. When applied to a project, this role also provides the ability to run jobs, including queries, within the project. A principal with this 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 Data Owner role ( Lowest-level resources where you can grant this role:
|
|
BigQuery Data Policy Admin( Role for managing Data Policies in BigQuery |
|
Masked Reader( Masked read access to sub-resources tagged by the policy tag associated with a data policy, for example, BigQuery columns |
|
Raw Data Reader Beta( Raw read access to sub-resources associated with a data policy, for example, BigQuery columns |
|
BigQuery Data Policy Viewer( Role for viewing Data Policies in BigQuery |
|
Custom IAM roles for BigQuery
To create a custom IAM role for BigQuery, follow the steps outlined for IAM custom roles using the BigQuery permissions.
BigQuery basic roles
For information on BigQuery basic roles, see BigQuery basic roles and permissions.
BigQuery permissions
The following table describes the permissions available in BigQuery. These are included in predefined roles and can be used in custom role definitions.
| Permission | Description |
|---|---|
bigquery.bireservations.get | Read BI Engine reservations. |
bigquery.bireservations.update | Update BI Engine reservations. |
bigquery.capacityCommitments.create | Create capacity commitments in the project. |
bigquery.capacityCommitments.delete | Delete a capacity commitment. |
bigquery.capacityCommitments.get | Retrieve details about a capacity commitment. |
bigquery.capacityCommitments.list | List all capacity commitments in a project. |
bigquery.capacityCommitments.update | Update all capacity commitments in a project. |
bigquery.config.update | Create a configuration. |
bigquery.config.get | Get details about a configuration. |
bigquery.connections.create | Create new connections in a project. |
bigquery.connections.delete | Delete a connection. |
bigquery.connections.get | Get connection metadata. Credentials are excluded. |
bigquery.connections.list | List connections in a project. |
bigquery.connections.update | Update a connection and its credentials. |
bigquery.connections.updateTag | Update tags for a connection. |
bigquery.connections.use | Use a connection configuration to connect to a remote data source. |
bigquery.connections.delegate | Delegate connection to create authorized external tables and remote functions. |
bigquery.dataPolicies.create | Create new data policies. |
bigquery.dataPolicies.delete | Delete data policies. |
bigquery.dataPolicies.get | Get metadata about data policies. |
bigquery.dataPolicies.getIamPolicy | Read a data policy's IAM permissions. |
bigquery.dataPolicies.list | List data policies in a project. |
bigquery.dataPolicies.maskedGet | View the masked data of a column that has a policy tag associated with a data policy. |
bigquery.dataPolicies.setIamPolicy | Set a data policy's IAM permissions. |
bigquery.dataPolicies.update | Update metadata for a data policy. |
bigquery.datasets.create | Create new empty datasets. |
bigquery.datasets.createTagBinding | Create resource tag bindings on a dataset. |
bigquery.datasets.delete | Delete a dataset. |
bigquery.datasets.deleteTagBinding | Delete resource tag bindings on a dataset. |
bigquery.datasets.get | Get metadata and permissions about a dataset. Viewing permissions in Google Cloud console also requires the bigquery.datasets.getIamPolicy permission. |
bigquery.datasets.getIamPolicy | Required by the Google Cloud console to give the user the option of getting a dataset's IAM permissions. Fails open. The ability to actually perform the operation of getting the permissions is gated by the bigquery.datasets.get permission. |
bigquery.datasets.link | Create a linked dataset. |
bigquery.datasets.listTagBindings | List resource tag bindings on a dataset. |
bigquery.datasets.setIamPolicy | Required by the Google Cloud console to give the user the option of setting a dataset's IAM permissions. Fails open. The ability to actually perform the operation of setting the permissions is gated by the bigquery.datasets.update permission. |
bigquery.datasets.update | Update metadata and permissions for a dataset. Granting permissions in Google Cloud console also requires the bigquery.datasets.setIamPolicy permission. |
bigquery.datasets.updateTag | (Deprecated) Update Data Catalog tags for a dataset. |
bigquery.jobs.create | Run jobs (including queries) within the project. |
bigquery.jobs.get | Get data and metadata on any job.1 |
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.listAll | List all jobs and retrieve metadata on any job submitted by any user. The bigquery.jobs.list permission is also required. |
bigquery.jobs.listExecutionMetadata | List all job execution metadata (without sensitive information) on any job submitted by any user. It can only be applied at the organization level and is used by Admin UI. |
bigquery.jobs.delete | Delete metadata for a job. |
bigquery.jobs.update | Cancel any job.1 |
bigquery.models.create | Create new machine learning models. |
bigquery.models.delete | Delete machine learning models. |
bigquery.models.getData | Get machine learning model data. To get model metadata, you need bigquery.models.getMetadata. |
bigquery.models.getMetadata | Get machine learning model metadata. To get model data, you need bigquery.models.getData. |
bigquery.models.list | List machine learning models and metadata on models. |
bigquery.models.updateData | Update machine learning model data. To update model metadata, you need bigquery.models.updateMetadata. |
bigquery.models.updateMetadata | Update machine learning model metadata. To update model data, you need bigquery.models.updateData. |
bigquery.models.export | Export machine learning models. |
bigquery.models.updateTag | Update Data Catalog tags for a model. |
bigquery.readsessions.create | Create a new read session using the Storage Read API. |
bigquery.readsessions.getData | Read data from a read session using the Storage Read API. |
bigquery.readsessions.update | Update a read session using the Storage Read API. |
bigquery.reservations.create | Create a slot reservation in an administration project. |
bigquery.reservations.delete | Delete a slot reservation. |
bigquery.reservations.get | Retrieve details about a slot reservation. |
bigquery.reservations.list | List all slot reservations in an administration project. |
bigquery.reservations.update | Update the properties of a slot reservation. |
bigquery.reservations.use | Allow use of the specified slot reservation in a job. This permission is required on the reservation owner's resource. |
bigquery.reservationAssignments.create | Create a reservation assignment. This permission is required on the owner project and assignee resource. |
bigquery.reservationAssignments.delete | Delete a reservation assignment. This permission is required on the owner project and assignee resource. |
bigquery.reservationAssignments.list | List all reservation assignments in a project. |
bigquery.reservationAssignments.search | Find a reservation assignment for a given project, folder, or organization. |
bigquery.rowAccessPolicies.create | Create a new row-level access policy on a table. |
bigquery.rowAccessPolicies.delete | Delete a row-level access policy from a table. |
bigquery.rowAccessPolicies.getFilteredData | Get data in a table that you want to be visible only to the principals in a row-level access policy's grantee list. We recommend this permission only be granted on a row-level access policy resource. |
bigquery.rowAccessPolicies.list | List all row-level access policies on a table. |
bigquery.rowAccessPolicies.overrideTimeTravelRestrictions | Access historical data for a table that has, or has previously had, row-level access policies. |
bigquery.rowAccessPolicies.getIamPolicy | Get a row access policy's IAM permissions. |
bigquery.rowAccessPolicies.setIamPolicy | Set the row access policy's IAM permissions. |
bigquery.rowAccessPolicies.update | Re-create a row-level access policy. |
bigquery.routines.create | Create new routines (functions and stored procedures). |
bigquery.routines.delete | Delete routines. |
bigquery.routines.get | Get routine definitions and metadata. |
bigquery.routines.list | List routines and metadata on routines. |
bigquery.routines.update | Update routine definitions and metadata. |
bigquery.routines.updateTag | Update Data Catalog tags for a routine. |
bigquery.savedqueries.create | Create saved queries. |
bigquery.savedqueries.delete | Delete saved queries. |
bigquery.savedqueries.get | Get metadata on saved queries. |
bigquery.savedqueries.list | List saved queries. |
bigquery.savedqueries.update | Update saved queries. |
bigquery.tables.create | Create new tables. |
bigquery.tables.createIndex | Create search indexes on tables. |
bigquery.tables.createSnapshot | Create new table snapshots. |
bigquery.tables.createTagBinding | Create resource tag bindings on a table. |
bigquery.tables.delete | Delete tables. |
bigquery.tables.deleteIndex | Drop search indexes on tables. |
bigquery.tables.deleteSnapshot | Delete table snapshots. |
bigquery.tables.deleteTagBinding | Delete resource tag bindings on a table. |
bigquery.tables.export | Export table data out of BigQuery. |
bigquery.tables.get | Get table metadata. To get table data, you need bigquery.tables.getData. |
bigquery.tables.getData | Get table data. This permission is required for querying table data. To get table metadata, you need bigquery.tables.get. |
bigquery.tables.getIamPolicy | Read a table's IAM policy. |
bigquery.tables.list | List tables and metadata on tables. |
bigquery.tables.listEffectiveTags | List effective tag bindings with the Cloud Resource Manager API. Checked when the --effective flag is used. |
bigquery.tables.listTagBindings | List tag bindings with the Cloud Resource Manager API. |
bigquery.tables.replicateData | Replicate table data. This permission is required for creating replica materialized views. |
bigquery.tables.restoreSnapshot | Restore table snapshots. |
bigquery.tables.setCategory | Set policy tags in table schema. |
bigquery.tables.setIamPolicy | Change a table's IAM policy. |
bigquery.tables.update | Update table metadata. |
bigquery.tables.updateData | Update table data. |
bigquery.tables.updateTag | Update Data Catalog tags for a table. |
bigquery.transfers.get | Get transfer metadata. |
bigquery.transfers.update | Create, update, and delete transfers. |
1 For any job you create, you automatically have the equivalent of the bigquery.jobs.get and bigquery.jobs.update permissions for that job.
Permissions for BigQuery ML tasks
The following table describes the permissions needed for common BigQuery ML tasks.
| Permission | Description |
|---|---|
bigquery.jobs.createbigquery.models.createbigquery.models.getDatabigquery.models.updateData | Create a new model using CREATE MODEL statement |
bigquery.jobs.createbigquery.models.createbigquery.models.getDatabigquery.models.updateDatabigquery.models.updateMetadata | Replace an existing model using CREATE OR REPLACE MODEL statement |
bigquery.models.delete | Delete model using models.delete API |
bigquery.jobs.createbigquery.models.delete | Delete model using DROP MODEL statement |
bigquery.models.getMetadata | Get model metadata using models.get API |
bigquery.models.list | List models and metadata on models using models.list API |
bigquery.models.updateMetadata | Update model metadata using models.delete API. If setting or updating a non-zero expiration time for Model, bigquery.models.delete permission is also needed |
bigquery.jobs.createbigquery.models.getData | Perform evaluation, prediction and model and feature inspections using functions such as ML.EVALUATE, ML.PREDICT, ML.TRAINING_INFO, and ML.WEIGHTS. |
bigquery.jobs.createbigquery.models.export | Export a model |
bigquery.models.updateTag | Update Data Catalog tags for a model. |
What's next
- For more information about assigning roles at the dataset level, see Controlling access to datasets.
- For more information about assigning roles at the table or view level, see Controlling access to tables and views.
