Manage notebooks

This document describes how to manage Colab Enterprise notebooks in BigQuery, including how to view, compare, restore, and delete notebooks.

This document also describes how to view and manage notebook metadata in Dataplex.

Notebooks are BigQuery Studio code assets powered by Dataform.

Before you begin

1. Create a notebook.
2. To manage notebook metadata in Dataplex, ensure that the Dataplex API is enabled in your Google Cloud project.

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.

To manage notebook metadata in Dataplex, ensure that you have the required Dataplex roles.

Grant access to notebooks

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

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

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.

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 more_vert 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 more_vert 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 more_vert View actions next to a notebook version and then click Compare. The comparison pane opens, comparing the notebook version that you selected with the current notebook version.

4. Optional: To compare the versions inline instead of in separate panes, click Compare and then click Inline.

5. Optional: To compare the source code of versions, click Compare and then click Show raw source.

6. Optional: To hide the command output in the notebook, click Compare and then deselect Show output.

Restore a notebook version

Use one of the following options to restore a notebook version. Restoring from the comparison pane lets you 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.

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 more_vert View actions next to the notebook and then click Delete.

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

5. Click Delete.

Manage metadata in Dataplex

Dataplex lets you store and manage metadata for notebooks. Notebooks are available in Dataplex by default, without additional configuration.

You can use Dataplex to manage notebooks in all BigQuery locations. Managing notebooks in Dataplex is subject to Dataplex quotas and limits and Dataplex pricing.

Dataplex automatically retrieves the following metadata from notebooks:

• Data asset name
• Data asset parent
• Data asset location
• Data asset type
• Corresponding Google Cloud project

Dataplex logs notebooks as entries with the following entry values:

System entry group

The system entry group for notebooks is @dataform. To view details of notebook entries in Dataplex, you need to view the dataform system entry group. For instructions about how to view a list of all entries in an entry group, see View details of an entry group in the Dataplex documentation.

System entry type

The system entry type for notebooks is dataform-code-asset. To view details of notebooks, you need to view the dataform-code-asset system entry type, filter the results with an aspect-based filter, and set the type field inside dataform-code-asset aspect to NOTEBOOK. Then, select an entry of the selected notebook. For instructions about how to view details of a selected entry type, see View details of an entry type in the Dataplex documentation. For instructions about how to view details of a selected entry, see View details of an entry in the Dataplex documentation.

System aspect type

The system aspect type for notebooks is dataform-code-asset. To provide additional context to notebooks in Dataplex by annotating notebook entries with aspects, view the dataform-code-asset aspect type, filter the results with an aspect-based filter, and set the type field inside dataform-code-asset aspect to NOTEBOOK. For instructions about how to annotate entries with aspects, see Manage aspects and enrich metadata in the Dataplex documentation.

Type

The type for data canvases is NOTEBOOK. This type lets you filter notebooks in the dataform-code-asset system entry type and the dataform-code-asset aspect type by using the aspect:dataplex-types.global.dataform-code-asset.type=NOTEBOOK query in an aspect-based filter.

For instructions about how to search for assets in Dataplex, see Search for data assets in Dataplex in the Dataplex documentation.

Troubleshooting

For more information, see Troubleshoot Colab Enterprise.

What's next

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