Databricksノートブックを管理する

> [Databricksクイックスタートガイド](https://qiita.com/taka_yayoi/items/125231c126a602693610)のコンテンツです。

[Manage notebooks \| Databricks on AWS](https://docs.databricks.com/notebooks/notebooks-manage.html) [2022/8/11時点]の翻訳です。

UI、CLI、Workspace APIを用いてノートブックを管理することができます。本記事では主にUIを用いたノートブックに対する操作を説明します。他の方法に関しては、[Databricks CLI](https://docs.databricks.com/dev-tools/cli/index.html)、[Workspace API 2\.0](https://docs.databricks.com/dev-tools/api/latest/workspace.html)を参照ください。

# ノートブックの作成

## 作成ボタンを使う

あなたのデフォルトフォルダーで新規ノートブックを作成する最も簡単な方法は**Create**ボタンを使うことです。

1. サイドバーの![](https://docs.databricks.com/_images/create-icon.png)**Create**をクリックし、メニューから**Notebook**を選択します。ノートブック作成ダイアログが表示されます。
1. 名前を入力し、ノートブックのデフォルト言語を選択します。
1. 稼働中のクラスターがある場合は、**Cluster**ドロップダウンが表示されます。[ノートブックをアタッチ](#クラスターにノートブックをアタッチする)したいクラスターを選択します。
1. **Create**をクリックします。

## 任意のフォルダーにノートブックを作成する

以下の手順を踏むことで、任意のフォルダー(**Shared**フォルダーなど)に新規ノートブックを作成することができます。

1. サイドバーの![](https://docs.databricks.com/_images/workspace-icon.png)**Workspace**をクリックします。以下のいずれかを行います。
    - 任意のフォルダーの右にある![](https://docs.databricks.com/_images/menu-dropdown.png)をクリックし、**Create > Notebook**を選択します。
![](https://docs.databricks.com/_images/create-notebook1.png)
    - ワークスペースかユーザーフォルダーで、![](https://docs.databricks.com/_images/menu-dropdown.png)をクリックし、**Create > Notebook**を選択します。
1. [作成ボタンを使う](#作成ボタンを使う)のステップ2からステップ4を行います。

# ノートブックを開く

ワークスペースで、![](https://docs.databricks.com/_images/notebook.png)をクリックします。ノートブックのタイトルにマウスカーソルを持っていくとノートブックのパスが表示されます。

# ノートブックの削除

ワークスペースメニューにどのようにアクセスしてノートブックや他の項目を削除するのかに関しては、[フォルダー](https://qiita.com/taka_yayoi/items/e469dded5ee83ae42d24#%E3%83%95%E3%82%A9%E3%83%AB%E3%83%80%E3%83%BC)と[ワークスペースオブジェクトの操作](https://qiita.com/taka_yayoi/items/e469dded5ee83ae42d24#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9%E3%81%AE%E3%82%AA%E3%83%96%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%AE%E3%82%AA%E3%83%9A%E3%83%AC%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3)を参照ください。

# ノートブックのパスのコピー

ノートブックのファイルパスをコピーするには、ノートブック名を右クリックするか、ノートブック名の右の![](https://docs.databricks.com/_images/menu-dropdown.png)をクリックして、**Copy File Path**を選択します。
![](https://docs.databricks.com/_images/copy-file-path.png)

# ノートブックの名前の変更

開いているノートブックのタイトルをクリックしてタイトルを変更するか、**File > Rename**をクリックします。

# ノートブックのアクセス制御

Databricksの[Premium plan](https://databricks.com/product/aws-pricing)を契約している場合には、ノートブックのアクセス権を設定できる[ワークスペースオブジェクトのアクセスコントロール](https://qiita.com/taka_yayoi/items/2dd6711b7b254505e4a3)を利用できます。

# ノートブックの外部フォーマット

Databricksはいくつかの外部フォーマットをサポートしています：

- ソースファイル： `.scala`、`.py`、`.sql`、`.r`の拡張子を持つソースコード
- HTML: `.html`の拡張子を持つDatabricksノートブック
- DBCアーカイブ: [Databricksアーカイブ](#ノートブックの配布)
- IPythonノートブック: `.ipynb`の拡張子を持つ[Jupyter notebook](https://jupyter-notebook.readthedocs.io/en/stable/)
- RMarkdown: `.Rmd`の拡張子を持つ[R Markdown document](https://rmarkdown.rstudio.com/)

本章では以下を説明します：

- [ノートブックのインポート](#ノートブックのインポート)
- [ファイルをノートブックに変換する](#ファイルをノートブックに変換する)
- [ノートブックのエクスポート](#ノートブックのエクスポート)
- [フォルダーのすべてのノートブックのエクスポート](#フォルダーのすべてのノートブックのエクスポート)
- [ノートブックのパブリッシュ](#ノートブックのパブリッシュ)

## ノートブックのインポート

URLかファイルから外部ノートブックをインポートできます。また、Databricksワークスペースから[バルクでエクスポート](#フォルダーのすべてのノートブックのエクスポート)されたノートブックのZIPアーカイブをインポートすることができます。

1. サイドバーの**Workspace**ボタン![](https://docs.databricks.com/_images/workspace-icon.png)をクリックします。以下のいずれかを行います。 
    - フォルダーの右側にある![](https://docs.databricks.com/_images/menu-dropdown.png)をクリックして、**Import**を選択します。
    - ワークスペース、ユーザーフォルダーで![](https://docs.databricks.com/_images/down-caret.png)をクリックし、**Import**を選択します。
![](https://docs.databricks.com/_images/import-notebook.png)

1. URLを指定するか、サポートされている外部フォーマットのファイル、DatabricksのワークスペースからエクスポートされたZIPアーカイブを選択します。
1. **Import**をクリックします。
    - 単一のノートブックを選択すると、現在のフォルダーにインポートされます。
    - DBCかZIPアーカイブを選択すると、現在のフォルダーにフォルダー構造が再作成され、それぞれのノートブックがインポートされます。

## ファイルをノートブックに変換する

ファイルの最初のセルにコメントを追加することで、既存のPython、SQL、Scala、Rスクリプトを単一セルのノートブックに変換することができます。

```py:Python
# Databricks notebook source
```

```sql:SQL
-- Databricks notebook source
```

```scala:Scala
// Databricks notebook source
```

```r:R
# Databricks notebook source
```

Databricksノートブックは、セルを定義するために空白で囲まれた特殊なコメントを使用します。

```py:Python
# COMMAND ----------
```

```sql:SQL
-- COMMAND ----------
```

```scala:Scala
// COMMAND ----------
```

```r:R
# COMMAND ----------
```

## ノートブックのエクスポート

ノートブックツールバーで、**File > Export**を選択し、[フォーマット](#ノートブックの外部フォーマット)を指定します。

:::note 
**注意**
HTML、IPythonノートブック、アーカイブ(DBC)としてノートブックをエクスポートする際に、[実行結果をクリア](https://qiita.com/taka_yayoi/items/dfb53f63aed2fbd344fc#%E3%83%8E%E3%83%BC%E3%83%88%E3%83%96%E3%83%83%E3%82%AF%E3%81%AE%E7%8A%B6%E6%85%8B%E3%81%A8%E7%B5%90%E6%9E%9C%E3%81%AE%E3%82%AF%E3%83%AA%E3%82%A2)していない場合にはエクスポートしたものに実行結果も含まれます。
:::

## フォルダーのすべてのノートブックのエクスポート

:::note 
**注意**
HTML、IPython、アーカイブ(DBC)としてノートブックをエクスポートする際、結果を[クリア](https://qiita.com/taka_yayoi/items/dfb53f63aed2fbd344fc#%E3%83%8E%E3%83%BC%E3%83%88%E3%83%96%E3%83%83%E3%82%AF%E3%81%AE%E7%8A%B6%E6%85%8B%E3%81%A8%E7%B5%90%E6%9E%9C%E3%81%AE%E3%82%AF%E3%83%AA%E3%82%A2)していない場合には、ノートブックの実行結果が含まれます。
:::

ファクスペースフォルダーのすべてのノートブックをZIPアーカイブとしてエクスポートするには、以下を行います。

1. サイドバーの![](https://docs.databricks.com/_images/workspace-icon.png)**ワークスペース**をクリックします。以下のいずれを行います。
    - 任意のフォルダーの隣にある右端の![](https://docs.databricks.com/_images/menu-dropdown.png)をクリックし、**Export**をクリックします。
    - ワークスペースあるいはユーザーフォルダーで、![](https://docs.databricks.com/_images/down-caret.png)をクリックして、**Export**を選択します。
1. エクスポートフォーマットを選択します。
    - **DBCアーカイブ**: メタデータとノートブックコマンドの結果を含むバイナリーフォーマットであるDatabricksアーカイブをエクスポートします。 
    - **ソースファイル**: Databricksワークスペースにインポート可能なノートブックソースファイルのZIPアーカイブをエクスポートします。それぞれのノートブックのデフォルト言語のソースファイルとして参照したり、CI/CDパイプラインで使用できます。
    - **HTMLアーカイブ**: HTMLファイルのZIPアーカイブをエクスポートします。それぞれのノートブックのHTMLファイルは、Databricksワークスペースにインポートでき、HTMLとして参照できます。ノートブックコマンド結果が含まれます。

## ノートブックのパブリッシュ

Databricksコミュニティエディションを使用している場合には、ノートブックのURLを共有するために、ノートブックをパブリッシュすることができます。以降のパブリッシュアクションでノートブックのURLはパブリッシュ用のものに更新されます。

# ノートブックとクラスター

ノートブックにおけるあらゆる作業を行う前に、まず最初にノートブックをクラスターにアタッチする必要があります。本章では、どのようにクラスターに対してノートブックをアタッチ、デタッチ(切り離し)するのか、その際に背後では何が起きているのかを説明します。

本章では以下を説明します。

- [実行コンテキスト](#実行コンテキスト)
- [クラスターにノートブックをアタッチする](#クラスターにノートブックをアタッチする)
- [クラスターからノートブックをデタッチする](#クラスターからノートブックをデタッチする)
- [クラスターにアタッチされているノートブックを参照する](#クラスターにアタッチされているノートブックを参照する
)

## 実行コンテキスト

クラスターにノートブックをアタッチした際には、Databricksは実行コンテキストを生成します。実行コンテキストには、サポートされているプログラミング言語: Python、R、Scala、SQLそれぞれに対応する[REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)環境の状態が含まれます。ノートブック上のセルが実行されると、コマンドは適切な言語のREPL環境にディスパッチされて実行されます。

また、[REST 1\.2 API](https://docs.databricks.com/dev-tools/api/1.2/index.html)を用いて実行コンテキストを作成し、コマンドを実行コンテキストに送信して実行することもできます。同様に、コマンドは適切な言語のREPL環境にディスパッチされて実行されます。

クラスターには最大実行コンテキスト数(145)があります。実行コンテキストの数がこの最大値に達すると、ノートブックをクラスターにアタッチしたり、新たな実行コンテキストを作成することができなくなります。

### アイドル状態の実行コンテキスト

最後のコマンドが実行された後、特定のアイドル期間を過ぎた時に実行コンテキストはアイドル状態にあると考えられます。アイドル期間とは、最後のコマンド実行時からノートブックを自動的にデタッチするまでの時間となります。デフォルトのアイドル期間は24時間です。

クラスターが最大実行コンテキスト数に達した場合には、必要に応じてDatabricksは、アイドル状態の実行コンテキストを(最も最後に利用されたものから)削除します。実行コンテキストが削除された場合には、該当コンテキストを利用していたノートブックは依然としてクラスターにアタッチされており、クラスターのノートブックリストに表示されます。実行中のストリーム処理があるノートブックの実行コンテキストは、ストリーム処理が終了するまで決して削除されません。アイドル状態のコンテキストが削除された際には、実行コンテキストを使用していたノートブックに対して、アイドル状態にあったため実行コンテキストを使っていたノートブックがデタッチされたことを知らせるメッセージが表示されます。
![](https://docs.databricks.com/_images/notebook-context-evicted.png)

実行コンテキスト数が最大に達しているクラスターにノートブックをアタッチしようとした際、アイドルの実行コンテキストがない場合(あるいは自動削除が無効化されている場合)には、最大実行コンテキスト数に達していること、ノートブックはデタッチされたままであることが通知されます。
![](https://docs.databricks.com/_images/notebook-detached.png)

プロセスをフォークした際、フォークプロセスが終了しても、アイドル状態の実行コンテキストは依然としてアイドル状態と考えられます。なお、Sparkにおいて別プロセスのフォークは推奨されません。

### 実行コンテキスト自動削除の設定

実行コンテキスト自動削除は[Sparkプロパティ](https://qiita.com/taka_yayoi/items/8d951b660cd87c6c5f18#spark%E3%81%AE%E8%A8%AD%E5%AE%9A)の`spark.databricks.chauffeur.enableIdleContextTracking false`で設定できます。

## クラスターにノートブックをアタッチする

:::note warn
**重要！**
クラスターにノートブックがアタッチされている限り、[ノートブックにCan Run権限](https://docs.databricks.com/security/access-control/workspace-acl.html#notebook-permissions)を持つ任意のユーザーは、暗黙的にクラスターにアクセスする権限を持ちます。
:::

ノートブックをクラスターにアタッチするには以下を行います。

1. ノートブックノートブックツールバーで![](https://docs.databricks.com/_images/notebook-cluster-icon.png)**Detached**![](https://docs.databricks.com/_images/down-arrow.png)をクリックします。
1. ドロップダウンから、[クラスター](https://qiita.com/taka_yayoi/items/c5d99cd77fe4bfcf69f0)を選択します。

:::note warn
**重要!**
アタッチされたノートブックでは、以下のApache Spark変数を利用できます。

| クラス | 変数名 |
|:--|:--|
|SparkContext   |sc   |
|SQLContext/HiveContext   |sqlContext   |
|SparkSession (Spark 2.x)   |spark   |

独自にSparkSession、SparkContext、SQLContextを作成しないでください。作成すると動作に一貫性がなくなります。
:::

### SparkとDatabricksランタイムバージョンを確認する

ノートブックをアタッチしたクラスターのSparkバージョンを確認するには、以下を実行します。

```py:Python
spark.version
```

ノートブックをアタッチしたクラスターのDatabricksランタイムのバージョンを確認するには、以下を実行します。

```py:Python
spark.conf.get("spark.databricks.clusterUsageTags.sparkVersion")
```

:::note
**注意**
[Clusters API](https://docs.databricks.com/dev-tools/api/latest/clusters.html)、[Jobs API](https://docs.databricks.com/dev-tools/api/latest/jobs.html)のエンドポイントで必要となる `sparkVersion`タグと`spark_version`プロパティに関しては、[Databricks Runtime version(英語)](https://docs.databricks.com/dev-tools/api/latest/index.html#programmatic-version)を参照ください。これはSparkのバージョンとは異なります。
:::

## クラスターからノートブックをデタッチする

1. ノートブックツールバーの![](https://docs.databricks.com/_images/notebook-cluster-icon.png)**Attached `<cluster-name>`**![](https://docs.databricks.com/_images/down-arrow.png)をクリックします。
1. **Detach**を選択します。

![](https://docs.databricks.com/_images/cluster-detach.png)

クラスター詳細ページの**Notebooks**タブで、クラスターからノートブックをデタッチすることもできます。

クラスターからノートブックをデタッチした際には、[実行コンテキスト](#実行コンテキスト)が削除され、ノートブック上の全ての変数の値はクリアされます。

:::note
**ティップス**
使用していないノートブックはクラスターからデタッチすることをお勧めします。これによりドライバーノードのメモリーを解放できます。
:::

### クラスターにアタッチされているノートブックを参照する

クラスター詳細ページの**Notebooks**タブには、クラスターにアタッチされたノートブックが表示されます。また、それぞれのノートブックで、最後のコマンドが実行された時刻とノートブックの状態が表示されます。
![](https://docs.databricks.com/_images/notebooks.png)

# ノートブックのスケジュール

定期的にノートブックの実行をスケジュールするには：

1. ノートブックツールバーで、右上の![](https://docs.databricks.com/_images/schedule-button.png)ボタンをクリックします。このノートブックのジョブが存在しない場合、スケジュールダイアログが表示されます。
![](https://docs.databricks.com/_images/schedule-dialog.png)
    すでに、ノートブックのジョブが存在している場合にはジョブ一覧が表示されます。スケジュールダイアログを表示するには、**Add a schedule**をクリックします。
![](https://docs.databricks.com/_images/job-list-dialog.png)
1. スケージュールダイアログでは、オプションとしてジョブの名前を入力します。デフォルト名はノートブック名となります。
1. マニュアルでのみジョブを実行するのであれば**Manual**を選択し、ジョブ実行のスケジュールを定義するには**Scheduled**を選択します。**Scheduled**を選択する場合、頻度、時刻、タイムゾーンを指定するためにドロップダウンを使用します。
1. **Cluster**ドロップダウンで、タスクを実行するクラスターを選択します。

    **Allow Cluster Creation**権限を持っているのであれば、デフォルトでジョブは[新規ジョブクラスター](https://qiita.com/taka_yayoi/items/b3275a1983c51a8bbe1a#%E3%82%B8%E3%83%A7%E3%83%96%E3%81%AB%E9%81%A9%E3%81%97%E3%81%9F%E3%82%AF%E3%83%A9%E3%82%B9%E3%82%BF%E3%83%BC%E3%82%BF%E3%82%A4%E3%83%97%E3%81%AE%E9%81%B8%E6%8A%9E)で実行されます。デフォルトジョブクラスターの設定を行うには、[クラスター設定ダイアログ](https://qiita.com/taka_yayoi/items/8d951b660cd87c6c5f18)を表示するためにフィールドの右の**Edit**をクリックします。

    **Allow Cluster Creation**権限を持っていない場合は、デフォルトでジョブはノートブックがアタッチされているクラスターで実行されます。ノートブックがクラスターにアタッチされていない場合、**Cluster**ドロップダウンからクラスターを選択する必要があります。

1. オプションで、ジョブに引き渡す任意の**Parameter**を入力します。**Add**をクリックし、それぞれのパラメーターのキーと値を指定します。パラメーターは、パラメーターのキーによって指定される[ノートブックウィジェット](https://qiita.com/taka_yayoi/items/4df1fd723bdab9a99b08)の値を設定します。パラメーターの値の一部として、動的な値の限定的なセットを引き渡すには[タスクパラメーター変数](https://qiita.com/taka_yayoi/items/b3275a1983c51a8bbe1a#%E3%83%91%E3%83%A9%E3%83%A1%E3%83%BC%E3%82%BF%E3%83%BC%E5%A4%89%E6%95%B0)を使用します。
1. オプションで、ジョブイベントの**Alert**を受け取るメールアドレスを指定します。[通知](https://qiita.com/taka_yayoi/items/b3275a1983c51a8bbe1a#%E3%82%B8%E3%83%A7%E3%83%96%E3%82%A2%E3%83%A9%E3%83%BC%E3%83%88)をご覧ください。
1. **Submit**をクリックします。

# スケジュールされたノートブックジョブの管理

このノートブックに関連づけられているジョブを表示するには、**Schedule**ボタンをクリックします。ジョブ一覧ダイアゴルが表示され、このノートブックに現在定義されているすべてのジョブが表示されます。ジョブを管理するには、リストのジョブの右にある![](https://docs.databricks.com/_images/jobs-vertical-ellipsis.png)をクリックします。
![](https://docs.databricks.com/_images/job-list-menu.png)
このメニューから、スケジュールされたジョブを編集、クローン、参照、停止、再開、削除することができます。

スケジュールされたジョブをクローンすると、オリジナルと同じパラメーターが設定された新規ジョブが作成されます。新規ジョブはリスト上に`“Clone of <initial job name>”`という名前で表示されます。

ジョブの編集方法は、ジョブのスケジュールの複雑度によります。[スケジュールダイアログ](#ノートブックのスケジュール)か[ジョブ詳細パネル](https://qiita.com/taka_yayoi/items/b3275a1983c51a8bbe1a#%E3%82%B8%E3%83%A7%E3%83%96%E3%81%AE%E7%B7%A8%E9%9B%86)が表示され、スケジュール、クラスター、パラメーターなどを編集することができます。

# ノートブックの配布

容易に[ノートブック](#ノートブックの外部フォーマット)を配布できるように、Databricksは単体のノートブックや複数のノートブックを格納するフォルダーをパッケージできるDatabricksアーカイブ形式をサポートしています。Databricksアーカイブは、`.dbc`の拡張子を持った追加メタデータを含むJARファイルです。アーカイブに含まれるノートブックは、Databricksの内部フォーマットに変換されています。

## アーカイブのインポート

1. ノートブック、フォルダーの右にある![](https://docs.databricks.com/_images/down-caret.png)か![](https://docs.databricks.com/_images/menu-dropdown.png)をクリックし、**Import**を選択します。
1. **File**か**URL**を選択します。
1. Databricksアーカイブをドラッグ&ドロップします。
1. **Import**をクリックします。Databricksにアーカイブがインポートされます。アーカイブにフォルダーが含まれている場合には、Databricksでフォルダーが作成されます。

## アーカイブのエクスポート

ノートブック、フォルダーの右にある![](https://docs.databricks.com/_images/down-caret.png)か![](https://docs.databricks.com/_images/menu-dropdown.png)をクリックし、**Export > DBC Archive**を選択します。`<[folder|notebook]-name>.dbc`という形式でファイルがダウンロードされます。

### Databricks 無料トライアル

[Databricks 無料トライアル](https://databricks.com/jp/try-databricks)