# Manage notebooks

This document describes how to manage
[Colab Enterprise notebooks in BigQuery](https://docs.cloud.google.com/bigquery/docs/programmatic-analysis),
including how to view, compare, restore, and delete notebooks.

This document also describes how to view and manage notebook metadata in
[Knowledge Catalog](https://docs.cloud.google.com/knowledge-catalog/docs/introduction).

Notebooks are [BigQuery Studio](https://docs.cloud.google.com/bigquery/docs/query-overview#bigquery-studio)
code assets powered by [Dataform](https://docs.cloud.google.com/dataform/docs/overview).

## Before you begin

1. [Create a notebook](https://docs.cloud.google.com/bigquery/docs/create-notebooks).
2. To manage notebook metadata in Knowledge Catalog, ensure that the [Dataplex API](https://docs.cloud.google.com/knowledge-catalog/docs/enable-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`)](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.jobUser)
- [BigQuery Read Session User (`roles/bigquery.readSessionUser`)](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.readSessionUser)
- [Code Owner (`roles/dataform.codeOwner`)](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeOwner) at the resource level.

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

- [BigQuery Job User (`roles/bigquery.jobUser`)](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.jobUser)
- [BigQuery Read Session User (`roles/bigquery.readSessionUser`)](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.readSessionUser)
- [Code Owner (`roles/dataform.codeOwner`)](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeOwner) or [Code Editor (`roles/dataform.codeEditor`)](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeEditor)

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

- [BigQuery Job User (`roles/bigquery.jobUser`)](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.jobUser)
- [BigQuery Read Session User (`roles/bigquery.readSessionUser`)](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.readSessionUser)
- Any one of the following roles:

  - [Code Owner (`roles/dataform.codeOwner`)](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeOwner)
  - [Code Editor (`roles/dataform.codeEditor`)](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeEditor)
  - [Code Viewer (`roles/dataform.codeViewer`)](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeViewer)

For more information about BigQuery IAM, see
[Access control with IAM](https://docs.cloud.google.com/bigquery/docs/access-control).

To manage notebook metadata in Knowledge Catalog,
ensure that you have the required
[Knowledge Catalog roles](https://docs.cloud.google.com/knowledge-catalog/docs/iam-roles).

## Grant access to notebooks

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

> [!IMPORTANT]
> **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](https://docs.cloud.google.com/bigquery/docs/manage-notebooks#disable_output_saving).

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

   [Go to BigQuery](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)

   If you don't see the left pane, click **Expand left pane** to open the pane.
3. In the **Explorer** pane, expand your project and click **Notebooks**.

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

5. Click
   **Open actions** next to the notebook, and then click **Share**.

6. In the **Share permissions** pane, click **Add user/group**.

7. In the **New principals** field, enter a principal.

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

   - [**Code Owner**](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeOwner): Can perform any action on the notebook, including deleting or sharing it.
   - [**Code Editor**](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeEditor): Can edit the notebook.
   - [**Code Viewer**](https://docs.cloud.google.com/dataform/docs/access-control#dataform.codeViewer): Can view the notebook.

   > [!NOTE]
   > **Note:** The principal must also have the [Notebook Runtime User (`roles/aiplatform.notebookRuntimeUser`)](https://docs.cloud.google.com/vertex-ai/docs/general/access-control#aiplatform.notebookRuntimeUser) and [BigQuery User (`roles/bigquery.user`)](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.user) roles to run the notebook.

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

10. Click **Save**.

11. 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](https://docs.cloud.google.com/bigquery/docs/manage-notebooks#grant_access_to_notebooks) 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](https://docs.cloud.google.com/bigquery/docs/control-access-to-resources-iam#grant_access_to_a_dataset).

> [!IMPORTANT]
> **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](https://docs.cloud.google.com/bigquery/docs/manage-notebooks#disable_output_saving).

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

   [Go to BigQuery](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)

   If you don't see the left pane, click **Expand left pane** to open the pane.
3. In the **Explorer** pane, expand your project and click **Notebooks**.

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

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

6. Share the link with other users.

## Disable notebook output saving

You can prevent sharing saved notebook output
with other users who have access to the notebook file
by disabling notebook output saving.

When you disable output saving for a selected notebook,
BigQuery deletes all output saved in the notebook file
and doesn't save the output of subsequent runs.

However, users who have
[access to the notebook](https://docs.cloud.google.com/bigquery/docs/manage-notebooks#grant_access_to_notebooks)
can still view its output in the following ways:

- Run the notebook to view its current output. This output is not saved.
- View an archival version of the notebook and its output in revision history.

To disable saving of output for a selected notebook, follow these steps:

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

   [Go to BigQuery](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)

   If you don't see the left pane, click **Expand left pane** to open the pane.
3. In the **Explorer** pane, expand your project and click **Notebooks**.

4. Click the notebook for which you want to disable saving output.

5. To expand the menu bar, click keyboard_arrow_down **Toggle header visibility**.

6. Click **Edit \> Notebook settings**.

7. In the **Notebook settings** window, select
   **Omit code cell output when saving this notebook**.

8. Click **Save**.

9. Click **Reload**.

## Resolve conflicts

If you and another user make conflicting changes in a notebook, the service
raises the error `Automatic saving failed. This file was updated remotely or
in another tab.` and provides a `Show diff` link. To resolve the conflict,
follow these steps:

1. Click the `Show diff` link. The **Review remote changes** dialog opens.
2. Optional: To compare the notebook source code, select the **Raw source** checkbox.
3. Optional: To compare the versions inline instead of in separate panes, select the **Inline diff** checkbox.
4. Review the changes and decide which to keep, revising your input if necessary.
5. Click **Save your changes**.

## 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](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)

   If you don't see the left pane, click **Expand left pane** to open the pane.
3. 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](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)
3. In the **Explorer** pane, expand your project and click **Notebooks**.

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 as
   the [region](https://docs.cloud.google.com/bigquery/docs/notebooks-introduction#supported_regions) it
   uses 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 of
a [repository](https://docs.cloud.google.com/bigquery/docs/repository-intro). Notebook versioning
is handled differently based on where the notebook is located.

### Notebook versioning in repositories

Repositories are Git repositories that reside either in BigQuery
or with a third-party provider. You can use
[workspaces](https://docs.cloud.google.com/bigquery/docs/workspaces-intro) in repositories to perform
version control on notebooks. For more information, see
[Use version control with a file](https://docs.cloud.google.com/bigquery/docs/workspaces#use_version_control_with_a_file).

### Notebook versioning outside of repositories

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](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)
3. In the **Explorer** pane, expand your project and click **Notebooks**. Click
   the 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,
   click **Version history**.

#### Compare notebook versions

To compare notebook versions, follow these steps:

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

   [Go to BigQuery](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)
3. In the **Explorer** pane, expand your project and click **Notebooks**.

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

5. Click **Version history**.

6. Click

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

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

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

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

#### Restore a notebook version

Restoring a notebook version 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.

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

   [Go to BigQuery](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)
3. In the **Explorer** pane, expand your project and click **Notebooks**.

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

5. Click **Version history**.

6. Click
   **View actions** next to the version and then click **Compare**.
   The comparison pane opens, comparing the notebook version that you
   selected with the most recent notebook version.

7. If you want to restore the previous notebook version after comparison,
   click **Restore**.

8. Click **Confirm**.

## Rename a notebook

To rename a notebook, follow these steps:

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

   [Go to BigQuery](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)
3. In the **Explorer** pane, expand your project and click **Notebooks**.

4. Click the notebook that you want to rename.

5. Click keyboard_arrow_down **Toggle header visibility**
   to expand the menu bar.

6. Click **File \> Rename**.

7. In the **Rename notebook** dialog, type a name for the notebook, and then
   click **Rename**.

## Download a notebook

To download a notebook, follow these steps:

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

   [Go to BigQuery](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)
3. In the **Explorer** pane, expand your project and click **Notebooks**.

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

5. Expand the menu bar and go to the **File** menu:

   ![The notebook menu bar](https://docs.cloud.google.com/static/bigquery/images/notebook-menu-bar.png)
6. Select **Download**, and then select the file type in which you want to
   download the file.

## Delete notebooks

To delete a notebook, follow these steps:

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

   [Go to BigQuery](https://console.cloud.google.com/bigquery)
2. In the left pane, click **Explorer**:

   ![Highlighted button for the Explorer pane.](https://docs.cloud.google.com/static/bigquery/images/explorer-tab.png)
3. In the **Explorer** pane, expand your project and click **Notebooks**.

4. Find the notebook that you want to delete.

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

6. To confirm deletion, type `delete` in the dialog.

7. Click **Delete**.

## Manage metadata in Knowledge Catalog

[Knowledge Catalog](https://docs.cloud.google.com/knowledge-catalog/docs/introduction) lets you store and
manage metadata for
notebooks. Notebooks are available in Knowledge Catalog
by default, without additional configuration.

You can use Knowledge Catalog to manage notebooks
in all [BigQuery locations](https://docs.cloud.google.com/bigquery/docs/locations).
Managing notebooks in Knowledge Catalog
is subject to [Knowledge Catalog quotas and limits](https://docs.cloud.google.com/knowledge-catalog/docs/quotas)
and [Knowledge Catalog pricing](https://cloud.google.com/dataplex/pricing).

Knowledge Catalog automatically retrieves
the following metadata from notebooks:

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

Knowledge Catalog logs notebooks as
[entries](https://docs.cloud.google.com/knowledge-catalog/docs/ingest-custom-sources#entries) with the following
entry values:

System entry group
:   The [system entry group](https://docs.cloud.google.com/knowledge-catalog/docs/ingest-custom-sources#entry-groups)
    for notebooks is `@dataform`. To view details of notebook entries
    in Knowledge Catalog, 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](https://docs.cloud.google.com/knowledge-catalog/docs/ingest-custom-sources#entry-group-details)
    in the Knowledge Catalog documentation.

System entry type
:   The [system entry type](https://docs.cloud.google.com/knowledge-catalog/docs/ingest-custom-sources#entry-types)
    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`](https://docs.cloud.google.com/knowledge-catalog/docs/search-syntax#aspect-search).
    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](https://docs.cloud.google.com/knowledge-catalog/docs/ingest-custom-sources#entry-type-details)
    in the Knowledge Catalog documentation.
    For instructions about how to view details of a selected entry, see
    [View details of an entry](https://docs.cloud.google.com/knowledge-catalog/docs/search-assets#view-entry-details)
    in the Knowledge Catalog documentation.

System aspect type
:   The [system aspect type](https://docs.cloud.google.com/knowledge-catalog/docs/enrich-entries-metadata#aspect-types)
    for notebooks is `dataform-code-asset`. To
    provide additional context to notebooks in Knowledge Catalog
    by annotating notebook entries with
    [aspects](https://docs.cloud.google.com/knowledge-catalog/docs/enrich-entries-metadata#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`](https://docs.cloud.google.com/knowledge-catalog/docs/search-syntax#aspect-search).
    For instructions about how to annotate entries with aspects, see
    [Manage aspects and enrich metadata](https://docs.cloud.google.com/knowledge-catalog/docs/enrich-entries-metadata)
    in the Knowledge Catalog 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](https://docs.cloud.google.com/knowledge-catalog/docs/search-syntax#aspect-search).

For instructions about how to search for assets in Knowledge Catalog, see
[Search for data assets in Knowledge Catalog](https://docs.cloud.google.com/knowledge-catalog/docs/search-assets)
in the Knowledge Catalog documentation.

## Troubleshooting

For more information, see
[Troubleshoot Colab Enterprise](https://docs.cloud.google.com/colab/docs/troubleshooting).

## What's next

- Learn more about [Colab Enterprise notebooks in BigQuery](https://docs.cloud.google.com/bigquery/docs/notebooks-introduction).
- Learn how to [create notebooks](https://docs.cloud.google.com/bigquery/docs/create-notebooks).
- Learn how to [schedule notebooks](https://docs.cloud.google.com/bigquery/docs/orchestrate-notebooks).