Controlling access to tables and views

This page shows you how to use BigQuery Table ACL to control access to tables and views. For an overview of BigQuery Table ACL, see Introduction to table access controls.

After you create a table or view, you can set its policy in the following ways:

using the BigQuery web UI
using the bq set-iam-policy command
calling the tables.setIamPolicy method

You can use BigQuery Table ACL to set access on both logical views and dataset-level authorized views. A logical view can also reference other source tables and views that you shared using BigQuery Table ACL.

Before you begin

Create the table or view that you want to use with BigQuery Table ACL.
Grant the BigQuery Data Owner (roles/bigquery.dataOwner) role or the BigQuery Admin (roles/bigquery.admin) role to the person that will perform the steps in this topic.

Creating an access policy

To create an access policy on a table or view:

Console

Open the BigQuery web UI in the Cloud Console.

Go to the Cloud Console
In the navigation panel, in the Resources section, select your project.
Select the dataset that contains the table or view.
Select the table or view.
If you are modifying access for a table, click Share table. If you are modifying access for a view, click Share view.
The Table permissions or View permissions page opens. For Add members, enter the email address of the user that will receive access to the table or view.
From the Select a role dropdown, select the role that you want to grant to the user. The following shows granting joe@example.com to the BigQuery Data Viewer (roles/bigquery.dataViewer) role.
Click Done.

bq

Retrieve the existing policy to a local file.
```
bq get-iam-policy --format=prettyjson \
 project-id:dataset.table_or_view \
 > policy.json
```
where:
- project-id is your project ID.
- dataset is the name of the dataset that contains the table that you are updating.
- table_or_view is the name of the table or view that you are updating.
If you haven't yet added any members to the policy, the contents of policy.json will contain an etag and no other fields.
To add the first member, add a bindings field to the policy. For example, to grant the BigQuery Data Viewer (roles/bigquery.dataViewer) role to joe@example.com:
```
"bindings": [
 {
   "members": [
     "user:joe@example.com"
   ],
   "role": "roles/bigquery.dataViewer"
 }
]
```
If you need to add more members to an existing binding, just add the member. This example shows granting jane@example.com the BigQuery Data Viewer (roles/bigquery.dataViewer) role, for a binding that already exists.
```
"members": [
       "user:joe@example.com",
       "user:jane@example.com"
     ],
     "role": "roles/bigquery.dataViewer"
   }
```

Update the policy.

bq set-iam-policy \
 project-id:dataset.table_or_view \
 policy.json

API

Call tables.getIamPolicy to retrieve the current policy.
Edit the policy to add members and/or bindings. See the bq example for the format of the policy.
Call tables.setIamPolicy to write the new policy.

After you create a policy, subsequent retrieval of the policy will show that its version field is 1. Do not change the version number. This version number refers to the IAM policy schema version, not your version of the table policy. For information about IAM policy schema versions, see Policy versions.

For more information about Identity and Access Management policies, see Understanding policies and the Policy reference topic.

Updating an access policy

To update an access policy on a table or view:

Console

Open the BigQuery web UI in the Cloud Console.

Go to the Cloud Console
In the navigation panel, in the Resources section, select your project.
Select the dataset that contains the table or view.
Select the table or view.
If you are modifying access for a table, click Share table. If you are modifying access for view, click Share view.
The Table permissions or View permissions page opens.
- If you want to add new members, use the same technique shown in Creating an access policy.
- If you want to remove access for a user, search for the user by using the Search members field. For each group where you want to remove the user, expand the group, and then click the Delete button for the user.
- If you want to change group membership for a user, make additions and/or deletions as described in the immediate 2 steps above.
Repeat as needed for other users whose access you want to add, modify, or remove. When you are done, click Done.

bq

Retrieve the existing policy to a local file.
```
bq get-iam-policy --format=prettyjson \
 project-id:dataset.table_or_view \
 > policy.json
```
where:
- project-id is your project ID.
- dataset is the name of the dataset that contains the table that you are updating.
- table_or_view is the name of the table or view you are updating.
Modify policy.json as needed.

For the format required for the policy, see the Policy reference topic.

Use the same etag value that was in the policy that you retrieved. Note that the version number remains 1. This version number refers to the IAM policy schema version, not your version of the table policy. For information about IAM policy schema versions, see Policy versions.

Update the policy.

bq set-iam-policy \
 project-id:dataset.table_or_view \
 policy.json

API

Call tables.getIamPolicy to retrieve the current policy.
Edit the policy to add members and/or bindings.

For the format required for the policy, see the Policy reference topic.

Use the same etag value that was in the policy that you retrieved. Note that the version number remains 1. This version number refers to the IAM policy schema version, not your version of the table policy. For information about IAM policy schema versions, see Policy versions.
Call tables.setIamPolicy to write the updated policy.

For more information about Identity and Access Management policies, see Understanding policies and the Policy reference topic.

What's next

Read the FAQ.
Learn about audit logging of BigQuery Table ACL admin activities at Audit logging.