Manage notebooks

Note: BigQuery Studio notebooks will begin charging in General Availability after April 11, 2024. You will begin seeing usage-based charges for BigQuery Studio notebooks in your invoice.

This document describes how to manage Colab Enterprise notebooks in BigQuery. Notebooks are BigQuery Studio code assets powered by Dataform.

To use notebooks, you must first Enable BigQuery Studio for asset management.

Important: In March 2024, APIs supporting BigQuery Studio capabilities were automatically enabled for all existing BigQuery projects. New BigQuery projects have these APIs enabled by default. For more information, see Automatic enablement of BigQuery Studio APIs.

Required permissions

To share notebooks, you need the following Identity and Access Management (IAM) roles:

• Bigquery Job User (roles/bigquery.jobUser)
• Bigquery Read Session User (roles/bigquery.readSessionUser)
• Code Owner (roles/dataform.codeOwner) at the resource level.

To save and delete notebooks, you need the following IAM roles:

• Bigquery Job User (roles/bigquery.jobUser)
• Bigquery Read Session User (roles/bigquery.readSessionUser)
• Code Owner (roles/dataform.codeOwner) or Code Editor (roles/dataform.codeEditor)

To work with notebook revisions, you need the following IAM roles:

• Bigquery Job User (roles/bigquery.jobUser)
• Bigquery Read Session User (roles/bigquery.readSessionUser)

• Any one of the following roles:

  • Code Owner (roles/dataform.codeOwner)
  • Code Editor (roles/dataform.codeEditor)
  • Code Viewer (roles/dataform.codeViewer)

For more information about BigQuery IAM, see Access control with IAM.

Grant access to notebooks

To grant other users access to a notebook, add those users to an appropriate IAM role.

Important: Users who have access to the notebook can see all output generated by code in the notebook, even if this output contains data from tables they don't have access to. To prevent saved output from being shared, disable notebook output saving.

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, the Shared notebooks folder. Find the notebook that you want to grant access to.

3. Click View actions next to the notebook, and then click Share > Manage Permissions.

4. In the Manage permissions pane, click Add user/group.

5. In the New principals field, enter a principal.

6. In the Role list, select one of the following roles:

   • Code Owner: Can perform any action on the notebook, including deleting or sharing it.
   • Code Editor: Can edit the notebook.
   • Code Viewer: Can view the notebook.
   Note: The principal must also have the Notebook Runtime User (roles/aiplatform.notebookRuntimeUser) and BigQuery User (roles/bigquery.user) roles to run the notebook.

7. Optional: To view a complete list of roles and advanced sharing settings, click Advanced sharing.

8. Click Save.

9. To return to the notebook information page, click Close.

Share notebooks

To share a notebook with other users, you can generate and share a link to the notebook. For other users to see the notebook you share, you must first grant access to the notebook.

To run a notebook, users must have access to the data that the notebook accesses. For more information, see Grant access to a dataset.

Important: Users who have access to the notebook can see all output generated by code in the notebook, even if this output contains data from tables they don't have access to. To prevent saved output from being shared, disable notebook output saving.

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, expand the Shared notebooks folder. Find the notebook that you want to share.

3. Click View actions next to the notebook, and then click Share > Copy link.

4. Share the link with other users.

View all notebooks

To view a list of all notebooks in your project, do the following:

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, click View actions next to Notebooks, and then do one of the following:

• To open the list in the current tab, click Show all.
• To open the list in a new tab, click Show all in > New tab.
• To open the list in a split tab, click Show all in > Split tab.

View notebook metadata

To view notebook metadata, follow these steps:

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, the Shared notebooks folder. Click the name of the notebook that you want to view metadata for.

3. Look at the Summary pane to see information about the notebook such as the region it uses for data and the date it was last modified.

Work with notebook versions

Use the following sections to learn how to view, compare, and restore versions of a notebook.

View notebook versions

To view notebook versions, follow these steps:

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, the Shared notebooks folder. Click the name of the notebook you want to view activity for.

3. Click the Activity tab to see a list of the notebook versions in descending order by date.

Compare notebook versions

To compare notebook versions, follow these steps:

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, the Shared notebooks folder. Click the name of the notebook that you want to compare version information for.

3. In the Activity tab, click View actions next to a notebook version and then click Compare.

4. In the Revision history pane, use the Version drop-downs to choose versions to compare.

5. Optional: To compare the notebook source code, select the Raw source checkbox.

6. Optional: To compare the versions inline instead of in separate panes, select the Inline diff checkbox.

7. Optional: To hide command output in the notebook, clear the Show output checkbox.

Restore a notebook version

Use one of the following options to restore a notebook version. Restoring from the Revision history pane lets you to compare the current and previous versions of the notebook before choosing to restore the previous version. Restoring a notebook creates a new version of a notebook instead of overwriting the current version. No version history is lost.

Activity pane

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, expand the Shared notebooks folder. Click the name of the notebook that you want to restore a previous version of.

3. Select the Activity pane.

4. Click View actions next to the version of the notebook that you want to restore and then click Restore.

5. Click Confirm.

Revision history

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, expand the Shared notebooks folder. Click the name of the notebook that you want to restore a previous version of.

3. Select the Activity pane.

4. Click View actions next to a notebook version and then click Compare.

5. In the Revision history pane, click View actions next to the Version drop-down and then click Restore revision.

6. Click Confirm.

Download a notebook

To download a notebook, follow these steps:

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, the Shared notebooks folder. Click the name of the notebook that you want to download.

3. Click Download.

Delete notebooks

To delete a notebook, follow these steps:

1. In the Google Cloud console, go to the BigQuery page.

   Go to BigQuery

2. In the Explorer pane, expand your project and the Notebooks folder, and if necessary, expand the Shared notebooks folder. Find the notebook that you want to delete.

3. Click View actions next to the notebook and then click Delete.

4. To confirm deletion, type delete in the dialog.

5. Click Delete.

Troubleshooting

For more information, see Troubleshoot Colab Enterprise.

What's next

• Learn more about Colab Enterprise notebooks in BigQuery.
• Learn how to create notebooks.