Manage notebooks

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

This document also describes how to view and manage notebook metadata inDataplex Universal Catalog.

Notebooks areBigQuery Studiocode assets powered byDataform.

Before you begin

1. Create a notebook.
2. To manage notebook metadata in Dataplex Universal Catalog,ensure that theDataplex API is enabledin 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 IAMroles:

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

To work with notebook revisions, you need the following IAMroles:

• 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, seeAccess control with IAM.

To manage notebook metadata in Dataplex Universal Catalog,ensure that you have the requiredDataplex Universal Catalog roles.

Grant access to notebooks

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

Important: Users who have access to the notebook can see all outputgenerated by code in the notebook, even if this output contains data fromtables 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 theBigQuery page.

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

   If you don't see the left pane, clicklast_pageExpand left pane to open the pane.

3. In theExplorer pane, expand your project and clickNotebooks.

4. Find the notebook that you want to grant access to.

5. Clickmore_vertOpen actions next to the notebook, and then clickShare.

6. In theShare permissions pane, clickAdd user/group.

7. In theNew principals field, enter a principal.

8. In theRole list, select one ofthe following roles:

   • Code Owner: Canperform any action on the notebook, including deleting or sharing it.
   • Code Editor: Canedit the notebook.
   • Code Viewer: Canview the notebook.
   Note: The principal must also have theNotebook Runtime User (roles/aiplatform.notebookRuntimeUser) andBigQuery User (roles/bigquery.user)roles to run the notebook.

9. Optional: To view a complete list of roles and advanced sharing settings,clickAdvanced sharing.

10. ClickSave.

11. To return to the notebook information page, clickClose.

Share notebooks

To share a notebook with other users, you can generate and share a link tothe notebook. For other users to see the notebook you share, you mustfirstgrant access to the notebook.

To run a notebook, users must have access to the data that the notebookaccesses. For more information, seeGrant access to a dataset.

Important: Users who have access to the notebook can see all outputgenerated by code in the notebook, even if this output contains data fromtables 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 theBigQuery page.

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

   If you don't see the left pane, clicklast_pageExpand left pane to open the pane.

3. In theExplorer pane, expand your project and clickNotebooks.

4. Find the notebook that you want to share. You can use thesearch feature or filters to find your notebook.

5. Clickmore_vertView actions next to the notebook, and then clickShare>Copy link.

6. 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 theBigQuery page.

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

   If you don't see the left pane, clicklast_pageExpand left pane to open the pane.

3. In theExplorer pane,clickmore_vertView actions next toNotebooks, and then do one of the following:

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

View notebook metadata

To view notebook metadata, follow these steps:

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and clickNotebooks.

4. Click the name of the notebook that you want to view metadata for.

5. Look at the summary details to see information about the notebook such astheregion ituses for data and the date it was last modified.

Work with notebook versions

You can choose to create a notebook either inside of or outside ofarepository. Notebook versioningis handled differently based on where the notebook is located.

Notebook versioning in repositories

Repositories are Git repositories that reside either in BigQueryor with a third-party provider. You can useworkspaces in repositories to performversion control on notebooks. For more information, seeUse version control with a file.

Notebook versioning outside of repositories

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

View notebook versions

To view notebook versions, follow these steps:

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and clickNotebooks. Clickthe name of the notebook you want to view version history for.

4. To see a list of the notebook versions in descending order by date,clickscheduleVersion history.

Compare notebook versions

To compare notebook versions, follow these steps:

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and clickNotebooks.

4. Click the name of the notebook that you want to compare version information for.

5. ClickscheduleVersion history.

6. Clickmore_vertView actions next to a notebook version and then clickCompare.The comparison pane opens, comparing the notebook version that you selectedwith the current notebook version.

7. Optional: To compare the versions inline instead of in separate panes, clickCompare and then clickInline.

8. Optional: To compare the source code of versions, clickCompare and thenclickShow raw source.

9. Optional: To hide the command output in the notebook, clickCompare andthen deselectShow output.

Restore a notebook version

Restoring a notebook version fromthe comparison pane lets you compare the current and previousversions of the notebook before choosing to restore the previous version.Restoring a notebook creates a new version of a notebook instead of overwritingthe current version. No version history is lost.

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and clickNotebooks.

4. Click the name of the notebook that you want to restore a previous version of.

5. ClickscheduleVersion history.

6. Clickmore_vertView actions next to the version and then clickCompare.The comparison pane opens, comparing the notebook version that youselected with the most recent notebook version.

7. If you want to restore the previous notebook version after comparison,clickRestore.

8. ClickConfirm.

Download a notebook

To download a notebook, follow these steps:

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and clickNotebooks.

4. Click the name of the notebook that you want to download. You can use thesearch feature or filters to find your notebook.

5. Expand the menu bar and go to theFile menu:

   

6. SelectDownload, and then select the file type in which you want todownload the file.

Delete notebooks

To delete a notebook, follow these steps:

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

   Go to BigQuery

2. In the left pane, clickexploreExplorer:

   

3. In theExplorer pane, expand your project and clickNotebooks.

4. Find the notebook that you want to delete.

5. Clickmore_vertView actions next to the notebook and then clickDelete.

6. To confirm deletion, typedelete in the dialog.

7. ClickDelete.

Manage metadata in Dataplex Universal Catalog

Dataplex Universal Catalog lets you store andmanage metadata fornotebooks. Notebooks are available in Dataplex Universal Catalogby default, without additional configuration.

You can use Dataplex Universal Catalog to manage notebooksin allBigQuery locations.Managing notebooks in Dataplex Universal Catalogis subject toDataplex Universal Catalog quotas and limitsandDataplex Universal Catalog pricing.

Dataplex Universal Catalog automatically retrievesthe following metadata from notebooks:

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

Dataplex Universal Catalog logs notebooks asentries with the followingentry values:

System entry group

Thesystem entry groupfor notebooks is@dataform. To view details of notebook entriesin Dataplex Universal Catalog, you need to view thedataform system entry group.For instructions about how to view a list of all entries in an entry group, seeView details of an entry groupin the Dataplex Universal Catalog documentation.

System entry type

Thesystem entry typefor notebooks isdataform-code-asset. To view details of notebooks,you need to view thedataform-code-asset system entry type,filter the results with an aspect-based filter,andset thetype field insidedataform-code-asset aspect toNOTEBOOK.Then, select an entry of the selected notebook.For instructions about how to view details of a selected entry type, seeView details of an entry typein the Dataplex Universal Catalog documentation.For instructions about how to view details of a selected entry, seeView details of an entryin the Dataplex Universal Catalog documentation.

System aspect type

Thesystem aspect typefor notebooks isdataform-code-asset. Toprovide additional context to notebooks in Dataplex Universal Catalogby annotating notebook entries withaspects,view thedataform-code-asset aspect type,filter the results with an aspect-based filter,andset thetype field insidedataform-code-asset aspect toNOTEBOOK.For instructions about how to annotate entries with aspects, seeManage aspects and enrich metadatain the Dataplex Universal Catalog documentation.

Type

The type for data canvases isNOTEBOOK.This type lets you filter notebooks in thedataform-code-assetsystem entry type and thedataform-code-asset aspect type by using theaspect:dataplex-types.global.dataform-code-asset.type=NOTEBOOKquery in anaspect-based filter.

For instructions about how to search for assets in Dataplex Universal Catalog, seeSearch for data assets in Dataplex Universal Catalogin the Dataplex Universal Catalog documentation.

Troubleshooting

For more information, seeTroubleshoot Colab Enterprise.

What's next

• Learn more aboutColab Enterprise notebooks in BigQuery.
• Learn how tocreate notebooks.
• Learn how toschedule notebooks.