Databricks notebook interface and controls

The notebook toolbar includes menus and icons that you can use to manage and edit the notebook.

Notebook toolbar

Next to the notebook name are buttons that let you change the default language of the notebook and, if the notebook is included in a Databricks Git folder, open the Git dialog.

To view previous versions of the notebook, click the “Last edit…” message to the right of the menus.

Updated cell design

Preview

This feature is in Public Preview.

An updated cell design is available. This page includes information about how to use both versions of the cell design. For an orientation to the new UI and answers to common questions, see Orientation to the new cell UI.

To enable or disable the new cell design, open the editor settings page in the workspace. In the sidebar, click Developer. Under Experimental features, toggle New cell UI.

Notebook cells

Notebooks contain a collection of two types of cells: code cells and Markdown cells. Code cells contain runnable code. Markdown cells contain Markdown code that renders into text and graphics when the cell is executed and can be used to document or illustrate your code. You can add or remove cells to your notebook to structure your work.

You can run a single cell, a group of cells, or run the whole notebook at once. A notebook cell can contain at most 10MB. Notebook cell output is limited to 20MB.

Notebook toolbar icons and buttons

The icons and buttons at the right of the toolbar are described in the following table:

Icon

Description

Run all button Interrupt execution button

Run all cells or stop execution. The name of this button changes depending on the state of the notebook.

Notebook header compute selector

Open compute selector. When the notebook is connected to a cluster or SQL warehouse, this button shows the name of the compute resource.

Notebook header job scheduler

Open job scheduler.

Notebook header DLT selector

Open Delta Live Tables. This button appears only if the notebook is part of a Delta Live Tables pipeline.

Notebook header share button

Open permissions dialog.

Browse data

Preview

This feature is in Public Preview.

To explore tables and volumes available to use in the notebook, click notebook data icon at the left side of the notebook to open the schema browser. See Browse data for more details.

Cell actions menu

The cell actions menu lets you cut and copy cells, move cells around in the notebook, and hide code or results. The menu has a different appearance in the original UI and the new UI. This section includes instructions for both versions.

If Databricks Assistant is enabled in your workspace, you can use it in a code cell to get help or suggestions for your code. To open a Databricks Assistant text box in a cell, click the Databricks Assistant icon Databricks Assistant icon in the upper-right corner of the cell.

You can easily change a cell between code and markdown, or change the language of a code cell, using the cell language button near the upper-right corner of the cell.

Cell language button

Cell actions menu (original UI)

Cell actions menu

From this menu you can also run code cells:

Cell actions menu - run

The cell action menu also includes buttons that let you hide a cell Cell Minimize or delete a cell Delete Icon.

For Markdown cells, there is also an option to add the cell to a dashboard. For more information, see Dashboards in notebooks.

Dashboard

Work with cells in the new UI

The following screenshot describes the icons that appear at the upper-right of a notebook cell:

upper-right cell icons - new UI

Language selector: Select the language for the cell.

Databricks Assistant: Enable or disable Databricks Assistant for code suggestions in the cell.

Cell focus: Enlarge the cell to make it easier to edit.

Display cell actions menu: Open the cell actions menu. The options in this menu are slightly different for code and Markdown cells.

Cell actions menu - new UI

To run code cells in the new UI, click the down arrow at the upper-left of the code cell.

Cell run menu - new UI

After a cell has been run, a notice appears to the right of the cell run menu, showing the last time the cell was run and the duration of the run. Hover your cursor over the notice for more details.

last run image

To add a Markdown cell or a cell that has tabular results to a dashboard, select Add to dashboard from the cell actions menu. For more information, see Dashboards in notebooks.

To delete a cell, click the trash icon to the right of the cell. This icon only appears when you hover your cursor over the cell.

cell trash icon

To add a comment to code in a cell, highlight the code. To the right of the cell, a comment icon appears. Click the icon to open the comment box.

commment icon

To move a cell up or down, click and hold move cell icon outside the upper-left corner of the cell, and drag the cell to the new location. You can also select Move up or Move down from the cell actions menu.

Create cells

Notebooks have two types of cells: code and Markdown. The contents of Markdown cells are rendered into HTML. For example, this snippet contains markup for a level-one heading:

%md ### Libraries
Import the necessary libraries.

renders as shown:

rendered Markdown example

Create a cell (original UI)

To create a new cell in the original UI, hover over a cell at the top or bottom and click the Add Cell icon. You can also use the notebook cell menu: click Down Caret and select Add Cell Above or Add Cell Below.

For a code cell, just type code into the cell. To create a Markdown cell, select Markdown from the cell’s language button or type %md at the top of the cell.

Create a cell (new UI)

To create a new cell in the new UI, hover over a cell at the top or bottom. Click on Code or Text to create a code or Markdown cell, respectively.

buttons to create a new cell

Cut, copy, and paste cells

There are several options to cut and copy cells. If you are using the Safari browser, only the keyboard shortcuts are available.

  • From the cell actions menu in the original UI or the new UI, select Cut cell or Copy cell.

  • Use keyboard shortcuts: Command-X or Ctrl-X to cut and Command-C or Ctrl-C to copy.

  • Use the Edit menu at the top of the notebook. Select Cut or Copy.

After you cut or copy cells, you can paste those cells elsewhere in the notebook, into a different notebook, or into a notebook in a different browser tab or window. To paste cells, use the keyboard shortcut Command-V or Ctrl-V. The cells are pasted below the current cell.

To undo cut or paste actions, you can use the keyboard shortcut Command-Z or Ctrl-Z or the menu options Edit > Undo cut cells or Edit > Undo paste cells.

To select adjacent cells, click in a Markdown cell and then use Shift + Up or Down to select the cells above or below it. Use the edit menu to copy, cut, paste, or delete the selected cells as a group. To select all cells, select Edit > Select all cells or use the command mode shortcut Cmd+A.

Notebook table of contents

To display an automatically generated table of contents, click the icon at the upper left of the notebook (between the left sidebar and the topmost cell). The table of contents is generated from the Markdown headings used in the notebook. If you are using the new UI, cells with titles also appear in the table of contents.

Open TOC

Cell display options

There are three display options for notebooks. Use the View menu to change the display option.

  • Standard view: results are displayed immediately after code cells.

  • Results only: only results are displayed.

  • Side-by-side: code and results cells are displayed side by side.

In the new UI, actions are available from icons in the cell gutter (the area to the right and left of the cell). For example, to move a cell up or down, use the grip dots move cell icon in the left gutter. To delete a cell, use the trash can icon in the right gutter.

For easier editing, click the focus mode icon cell focus icon to display the cell at full width. To exit focus mode, click exit cell focus icon. You can also enlarge the displayed width of a cell by turning off View > Centered layout.

To automatically format all cells in the notebook to industry standard line lengths and spacing, select Edit > Format notebook.

Line and command numbers

To show or hide line numbers or command numbers, select Line numbers or Command numbers from the View menu. For line numbers, you can also use the keyboard shortcut Control+L.

If you enable line or command numbers, Databricks saves your preference and shows them in all of your other notebooks for that browser.

Line and command numbers (original UI)

Command numbers above cells link to that specific command. If you click the command number for a cell, it updates your URL to be anchored to that command. To get a URL link to a specific command in your notebook, right-click the command number and choose Copy Link Address.

Line and command numbers (new UI)

Line numbers are off by default in the new UI. To turn them on, select View > Line numbers. When a cell is in an error state, line numbers are displayed regardless of the selection.

To toggle command numbers, select View > Command numbers.

The new UI does not include cell command number links. To get a URL link to a specific command in your notebook, click cell focus icon to open focus mode, and copy the URL from the browser address bar. To exit focus mode, click exit cell focus icon.

Add a cell title

To add a title to a cell using the original UI, select Show Title from the cell actions menu.

To add a title to a cell using the new UI, do one of the following:

  • Click the cell number shown at the center of the top of the cell and type the title.

  • Select Add title from the cell actions menu.

With the new UI, cells that have titles appear in the notebook’s table of contents.

add cell title

View notebooks in dark mode

You can choose to display notebooks in dark mode. To turn dark mode on or off, select View > Theme and select Light theme or Dark theme.

Hide and show cell content

Cell content consists of cell code and the results generated by running the cell. You can hide and show the cell code and result using the cell actions menu at the upper-right of the cell.

For related functionality, see Collapsible headings.

Hide and show cell content (original UI)

To hide cell code or results, click Down Caret and select Hide Code or Hide Result. You can also select Cell Minimize to display only the first line of a cell.

To show hidden cell code or results, click the Show links:

Show hidden code and results

Hide and show cell content (new UI)

To hide cell code or results, click the kebab menu cell kebab icon at the upper-right of the cell and select Hide code or Hide result. You can also select Collapse cell to display only the first line of a cell. To expand a collapsed cell, select Expand cell.

To show hidden cell code or results, click the show icon: show icon.

Collapsible headings

Cells that appear after cells containing Markdown headings can be collapsed into the heading cell. To expand or collapse cells after cells containing Markdown headings throughout the notebook, select Collapse all headings from the View menu. The rest of this section describes how to expand or collapse a subset of cells.

For related functionality, see Hide and show cell content.

Expand and collapse headings (original UI)

The image shows a level-two heading MLflow setup with the following two cells collapsed into it.

Collapsed cells in original UI

To expand and collapse headings, click the + and -.

Expand and collapse headings (new UI)

The image shows a level-two heading MLflow setup with the following two cells collapsed into it.

Collapsed cells in new UI

To expand and collapse headings, hover your cursor over the Markdown cell. Click the arrow that appears to the left of the cell.

Compute resources for notebooks

This section covers the options for notebook compute resources. You can run a notebook on a Databricks cluster, or, for SQL commands, you also have the option to use a SQL warehouse, a type of compute that is optimized for SQL analytics.

Attach a notebook to a cluster

To attach a notebook to a cluster, you need the CAN ATTACH TO cluster-level permission.

Important

As long as a notebook is attached to a cluster, any user with the CAN RUN permission on the notebook has implicit permission to access the cluster.

To attach a notebook to a cluster, click the compute selector in the notebook toolbar and select a cluster from the dropdown menu.

The menu shows a selection of clusters that you have used recently or that are currently running.

Attach notebook

To select from all available clusters, click More…. Click on the cluster name to display a dropdown menu, and select an existing cluster.

more clusters dialog

You can also create a new cluster by selecting Create new resource… from the dropdown menu.

Important

An attached notebook has the following Apache Spark variables defined.

Class

Variable Name

SparkContext

sc

SQLContext/HiveContext

sqlContext

SparkSession (Spark 2.x)

spark

Do not create a SparkSession, SparkContext, or SQLContext. Doing so will lead to inconsistent behavior.

Use a notebook with a SQL warehouse

When a notebook is attached to a SQL warehouse, you can run SQL and Markdown cells. Running a cell in any other language (such as Python or R) throws an error. SQL cells executed on a SQL warehouse appear in the SQL warehouse’s query history. The user who ran a query can view the query profile from the notebook by clicking the elapsed time at the bottom of the output.

Running a notebook requires a Pro or Serverless SQL warehouse. You must have access to the workspace and the SQL warehouse.

Widgets work differently when a notebook is attached to a SQL warehouse. For details, see Use Databricks widgets on a SQL warehouse.

To attach a notebook to a SQL warehouse do the following:

  1. Click the compute selector in the notebook toolbar. The dropdown menu shows compute resources that are currently running or that you have used recently. SQL warehouses are marked with SQL warehouse label.

  2. From the menu, select a SQL warehouse.

    To see all available SQL warehouses, select More… from the dropdown menu. A dialog appears showing compute resources available for the notebook. Select SQL Warehouse, choose the warehouse you want to use, and click Attach.

    more cluster dialog with SQL warehouse selected

You can also select a SQL warehouse as the compute resource for a SQL notebook when you create a workflow or scheduled job.

Limitations of SQL warehouses include:

  • When attached to a SQL warehouse, execution contexts have an idle timeout of 8 hours.

  • The maximum size for returned results is 10,000 rows or 2MB, whichever is smaller.

Detach a notebook

To detach a notebook from a compute resource, click the compute selector in the notebook toolbar and hover over the attached cluster or SQL warehouse in the list to display a side menu. From the side menu, select Detach.

Detach notebook

You can also detach notebooks from a cluster using the Notebooks tab on the cluster details page.

When you detach a notebook, the execution context is removed and all computed variable values are cleared from the notebook.

Tip

Databricks recommends that you detach unused notebooks from clusters. This frees up memory space on the driver.

Use web terminal and Databricks CLI

To open the web terminal in a notebook, click reopen bottom panel at the bottom of the right sidebar.

Use Databricks CLI in a web terminal

Starting with Databricks Runtime 15.0, you can use the Databricks CLI from the web terminal in the notebook.

Requirements

  • The notebook must be attached to a cluster in Single user or No isolation shared access mode.

  • The CLI is not available in workspaces enabled for PrivateLink.

The installed CLI is always the latest version. Authentication is based on the current user.

You cannot use the CLI from a notebook cell. Commands like %sh databricks ... in a notebook do not work with Databricks Runtime 15.0 or above.