More than 1 year has passed since last update.

Databricksノートブックによるソフトウェアエンジニアリングのベストプラクティスのウォークスルー

Last updated at 2022-06-29Posted at 2022-06-29

Software engineering best practices for notebooks | Databricks on AWS [2022/6/15時点]の翻訳です。

本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。

本書では、お使いのDatabrikcsノートブックに対して、バージョン管理、コード共有、テスト、オプションとして継続的インテグレーション、継続的開発、デリバリー(CI/CD)を含むソフトウェアエンジニアリングのベストプラクティスをどのように適用するのかを説明するハンズオンのウォークスルーを提供します。

このウォークスルーでは以下のことを行います。

バージョン管理のためにノートブックをDatabricks Reposに追加
ノートブックの一つから共有可能なモジュールを作成するためにコードの一部を抽出
共有コードのテスト
Databricks Jobsからノートブックの実行
オプションとして、共有コードにCI/CDを適用

要件

このウォークスルーを完了するには以下のリソースが必要です。

Databricks ReposによるGit連携の要件を満たすGitプロバイダーのリポジトリ。本書のウォークスルーではGitHubを使用します。このウォークスルーでは、皆様がbest-notebooksという名前のGitHubリポジトリを持っていることを前提としています。(リポジトリに別の名前をつけることができます。)持っていない場合にはGitHubのリポジトリを作成してください。
Databricksのワークスペース。お持ちでない場合にはワークスペースを作成してください。
ワークスペース上のDatabricks all-purposeクラスター。設計フェーズでノートブックを実行するために、稼働中のall-purposeクラスターにノートブックをアタッチします。あとで、このウォークスルーではこのクラスター上でのノートブックの実行を自動化するためにDatabricksジョブを使用します。(また、ジョブの生存期間中のみ存在するジョブクラスターでジョブを実行することもできます。)お持ちでない場合には、all-purposeクラスターを作成してください。

注意
Databricks Reposでファイルを操作するためには、使用するクラスターではDatabricksランタイム8.4以降がインストールされている必要があります。これらのクラスターにおいては、Databricksランタイム10.4LTSのような最新の長期サポート(LTS)バージョンをインストールすることをお勧めします。

ウォークスルー

このウォークルスルーでは、以下のことを行います。

既存のGitHubリポジトリをDatabricks Reposに接続します。
既存のノートブックをリポジトリ(repo)に追加し、一回目としてノートブックを実行します。
ノートブックのいくつかのコードを共有モジュールに移行します。期待通りにノートブックが共有コードを呼び出すことを確認するために、二回目のノートブックの実行を行います。
最初のノートブックを再度実行することなしに、共有コードを別にテストするために2つ目のノートブックを使用します。
2つのノートブックをオンデマンドあるいは定期的なスケジュールで自動で実行するおゆにDatabrikcsジョブを作成します。
リポジトリでプルリクエストが作成された際に、共有コードをテストする2番目のノートブックを実行するようにリポジトリを設定します。
自動でテストを起動する共有コードを変更するプルリクエストを作成します。

以下のステップでは、これらそれぞれのアクティビティをウォークスルーします。

ステップ

ステップ 1: Databricks Reposのセットアップ
ステップ 2: ノートブックのインポート及び実行
ステップ 3: コードを共有モジュールに移行
ステップ 4: 共有コードのテスト
ステップ 5: ノートブックを実行するジョブの作成
(オプション)ステップ 6: コードの変更があった際に自動でコードをテストしノートブックを実行するようにリポジトリをセットアップ
(オプション)ステップ 7: テストを起動するためにGitHubの共有コードを更新

ステップ 1: Databricks Reposのセットアップ

このステップでは、既存のDatabricksワークスペースのDatabricks Reposに既存のGitHubのリポジトリを接続します。

お使いのワークスペースからGitHubリポジトリに接続できるようにするためには、まだ設定していない場合には最初にワークスペースにGitHubの認証情報を提供する必要があります。

ステップ 1.1: GitHub認証情報の提供

ワークスペースのサイドバーのData Science & EngineeringあるいはDatabricks Machine Learning環境で、Settings > User Settingsをクリックします。
User SettingsページでGit integrationをクリックします。
Git integrationタブのGit providerでGitHubを選択します。
Git provider username or emailに、GitHubのユーザー名を入力します。
TokenにはGitHubのパーソナルアクセストークンを入力します。トークンにはrepoの権限が含まれている必要があります。
Saveをクリックします。

ステップ 1.2: GitHubリポジトリへの接続

サイドバーのData Science & EngineeringあるいはDatabricks Machine Learning環境で、Reposをクリックします。
ReposペインでAdd Repoをクリックします。
1. Clone remote Git repoをクリックします。
2. Git repository URLに、お使いのGitHubリポジトリのGitHubのClone with HTTPSのURLを入力します。本書では、URLの最後がbest-notebooks.gitであることを前提としています。例えば、https://github.com/<your-GitHub-username>/best-notebooks.gitとなります。
3. Git repository URLの隣のドロップダウンでGitHubを選択します。
4. お使いのリポジトリの名前に設定されるRepo nameはそのままにしておきます。例えば、best-notebooksとなります。
5. Createをクリックします。

ステップ 2: ノートブックのインポート及び実行

このステップでは、お使いのリポジトリに既存の外部ノートブックをインポートします。このウォークスルーのために自身のノートブックを作成することができますが、クイックに物事を進められるように、こちらではノートブックを準備しています。

ステップ 2.1: リポジトリで作業用ブランチを作成

このサブステップでは、リポジトリ上にedaという名前のブランチを作成します。このブランチを用いることで、ソフトウェアエンジニアリングのベストプラクティスに従い、リポジトリのmainブランチとは独立してファイルやコードを操作することができます。(ブランチに別の名前をつけることもできます)

Reposペインが表示されていない場合、サイドバーのData Science & EngineeringあるいはDatabricks Machine Learning環境で、Reposをクリックします。
Reposペインに上のステップで接続したリポジトリが表示されていない場合、あなたのワークスペース上のユーザー名を選択し、以前のステップで接続したリポジトリ名を選択します。
リポジトリ名の隣のドロップダウンの矢印をクリックし、Gitをクリックします。
best-notebooksダイアログで + (Create branch) ボタンをクリックします。

注意
リポジトリの名前がbest-notebooksではない場合、ダイアログのタイトルやこのウォークスルーを通じて表示される内容は異なります。
edaを入力しEnterを押します。
ダイアログを閉じます。

ステップ 2.2: リポジトリにノートブックをインポート

このサブステップでは、別のリポジトリからお使いのリポジトリに既存のノートブックをインポートします。このノートブックは以下の処理を行います。

ワークスペース上のクラスターにowid/covid-19-data GitHubリポジトリからCSVファイルをコピーします。このCSVファイルには世界中のCOVID-19による入院患者数、集中治療のメトリクスに関する公開データが含まれています。
CSVファイルの中身をpandasデータフレームに読み込みます。
アメリカのメトリクスのみを含むようにデータをフィルタリングします。
データのグラフを表示します。
pandasデータフレームをPandas API on Sparkデータフレームとして保存します。
Pandas API on Sparkデータフレームに対するデータクレンジングを実行します。
Pandas API on SparkデータフレームをワークスペースにDeltaテーブルとして保存します。
Deltaテーブルの中身を表示します。

ここで、リポジトリに自分でノートブックを作成することもできますが、ウォークスルーのスピードを上げるためにここでは既存のノートブックをインポートします。このブランチでノートブックを作成する、ノートブックをインポートするのではなくこのブランチに既存のノートブックを移動するには、Databricks Reposにおけるノートブックやプロジェクトファイルの取り扱いをご覧ください。

リポジトリのReposペインで、リポジトリ名の隣のドロップダウンの矢印をクリックし、Create > Folderをクリックします。
New Folder Nameダイアログでnotebooksと入力し、Create Folderをクリックします。
Reposペインで、リポジトリの名前をクリックし、notebooksフォルダの隣のドロップダウンの矢印をクリックし、Importをクリックします。
Import Notebooksダイアログで、
1. Import fromでは、URLを選択します。
2. GitHubのdatabricks/notebook-best-practicesリポジトリのcovid_eda_rawノートブックの生のコンテンツのURLを入力します。URLを取得するには、
  1. https://github.com/databricks/notebook-best-practices に移動します。
  2. notebooksフォルダをクリックします。
  3. covid_eda_raw.pyファイルをクリックします。
  4. Rawをクリックします。
  5. ブラウザのアドレスバーに表示される完全なURLをコピーし、Import Notebooksダイアログに貼り付けます。
3. Importをクリックします。

ステップ 2.3: ノートブックの実行

ノートブックが表示されていない場合、お使いのリポジトリのReposペインでnotebooksフォルダーの中にあるcovid_eda_rawノートブックをダブルクリックして開きます。
ノートブックでは、Fileの隣のドロップダウンリストから、このノートブックをアタッチするクラスターを選択します。
Run Allをクリックします。
プロンプトが表示された場合には、Attach & RunあるいはStart, Attach & Runをクリックします。
ノートブックの処理が終わるのを待ちます。

ノートブックが処理を終えると、ノートブック上でデータのグラフを確認でき、Deltaテーブルには600行以上の生データが格納されます。このノートブックの実行を開始した際、クラスターが起動していない場合、結果を表示するまでに数分かかることがあります。

ステップ 2.4: ノートブックのチェックイン、マージ

このサブステップでは、これまでの作業内容をGitHubのリポジトリに保存します。そして、作業用ブランチからリポジトリのmainブランチにノートブックをマージします。

リポジトリのReposペインでedaブランチをクリックします。
best-notebooksダイアログのChangesタブで、notebooks/covid_eda_raw.pyファイルが選択されていることを確認します。
Summary (required) にはAdded raw notebookと入力します。
Description (optional) にはThis is the first version of the notebookと入力します。
Commit & Pushをクリックします。
Historyをクリックし、ポップアップのCreate a pull request on your git providerリンクをクリックします。
GitHubで、Pull requestsタブをクリックし、プルリクエストを作成し、プルリクエストをmainブランチにマージします。
Databricksワークスペースに戻り、best-notebooksダイアログが表示されている場合には閉じます。

ステップ 3: コードを共有モジュールに移行

このステップでは、ノートブックのいくつかのコードを、ノートブックから一連の共有関数に移動します。これによって、これらの関数を他の同様のノートブックから使用することができ、今後のコーディングを加速し、より予測可能で一貫性のあるノートブック結果を保証する助けとなります。また、このコードを共有することで、これらの関数をより簡単にテストできるようになり、今後もこのコードの全体的な品質を高めるソフトウェアエンジニアリングのベストプラクティスに従うことができます。

ステップ 3.1: リポジトリで別の作業用ブランチを作成

ワークスペースで、お使いのリポジトリのReposペインでedaブランチをクリックします。
best-notebooksダイアログで、edaブランチの隣のドロップダウンの矢印をクリックし、mainを選択します。
Pullボタンをクリックします。プルを実行するプロンプトが表示されたらConfirmをクリックます。
+ (Create branch) ボタンをクリックします。
first_modulesを入力しEnterを押します。(ブランチに別の名前をつけることもできます)
ダイアログを閉じます。

ステップ 3.2: リポジトリにノートブックをインポート

このウォークスルーをスピードアップするために、このサブステップではあなたのリポジトリに既存の別のノートブックをインポートします。このノートブックは、ノートブックの外に保存されている共有コードの関数を呼び出すことを除き、以前のノートブックと同じこと行います。繰り返しになりますが、ここでも自分のリポジトリに自分のコードを作成し、実際のコードを自分で共有することができます。

Reposペインで、リポジトリの名前をクリックし、notebooksフォルダの隣のドロップダウンの矢印をクリックし、Importをクリックします。
Import Notebooksダイアログで、
1. Import fromでは、URLを選択します。
2. GitHubのdatabricks/notebook-best-practicesリポジトリのcovid_eda_modularノートブックの生のコンテンツのURLを入力します。URLを取得するには、
  1. https://github.com/databricks/notebook-best-practices に移動します。
  2. notebooksフォルダをクリックします。
  3. covid_eda_modular.pyファイルをクリックします。
  4. Rawをクリックします。
  5. ブラウザのアドレスバーに表示される完全なURLをコピーし、Import Notebooksダイアログに貼り付けます。
3. Importをクリックします。

注意
新しいcovid_eda_modularノートブックは最初のノートブックの共有バージョンであるため、この時点で既存のcovid_eda_rawノートブックを削除することができます。しかし、以前のノートブックを使わないとしても、比較のために以前のノートブックを保持しておいても構いません。

ステップ 3.3: ノートブックサポート用の共有コード関数を追加

リポジトリのReposペインで、リポジトリ名の隣のドロップダウンの矢印をクリックして、Create > Folderをクリックします。

注意
notebooksフォルダの隣のドロップダウンの矢印をクリックしないでください。代わりにリポジトリ名の隣のドロップダウンの矢印をクリックしてください。notebooksフォルダの中ではなく、リポジトリのルートにフォルダを作成します。
New Folder Nameダイアログでcovid_analysisを入力し、Create Folderをクリックします。
リポジトリのReposペインで、covid_analysisの隣のドロップダウンの矢印をクリックして、Create > Fileをクリックします。
New File Nameダイアログでtransforms.pyを入力し、Create Fileをクリックします。
リポジトリのReposペインで、covid_analysisフォルダをクリックし、transforms.pyをクリックします。

エディタウィンドウで以下のコードを入力します。

Python

import pandas as pd

# Filter by country code.
def filter_country(pdf, country="USA"):
  pdf = pdf[pdf.iso_code == country]
  return pdf

# Pivot by indicator, and fill missing values.
def pivot_and_clean(pdf, fillna):
  pdf["value"] = pd.to_numeric(pdf["value"])
  pdf = pdf.fillna(fillna).pivot_table(
    values="value", columns="indicator", index="date"
  )
  return pdf

# Create column names that are compatible with Delta tables.
def clean_spark_cols(pdf):
  pdf.columns = pdf.columns.str.replace(" ", "_")
  return pdf

# Convert index to column (works with pandas API on Spark, too).
def index_to_col(df, colname):
  df[colname] = df.index
  return df

ティップス
他のコード共有のテクニックに関しては、ノートブックでコードを共有するをご覧ください。

ステップ 3.4: 共有コードの依存関係の追加

上のコードでは、コードが適切に動作するためにいくつかのPythonパッケージの依存関係を含んでいます。このサブステップでは、これらのパッケージの依存関係を宣言します。

リポジトリのReposペインで、リポジトリ名の隣のドロップダウンの矢印をクリックして、Create > Fileをクリックします。

注意
notebooksフォルダやcovid_analysisフォルダの隣のドロップダウンの矢印をクリックしないでください。代わりにリポジトリ名の隣のドロップダウンの矢印をクリックしてください。notebooksフォルダやcovid_analysisフォルダの中ではなく、リポジトリのルートにパッケージ依存関係のリストを作成します。
New File Nameダイアログでrequirements.txtと入力しCreate Fileをクリックします。

リポジトリのReposペインで、requirements.txtをクリックし、以下のコードを入力します。

注意
requirements.txtファイルが見えない場合、ブラウザをリフレッシュしてください。

-i https://pypi.org/simple
attrs==21.4.0
cycler==0.11.0
fonttools==4.33.3
iniconfig==1.1.1
kiwisolver==1.4.2
matplotlib==3.5.1
numpy==1.22.3
packaging==21.3
pandas==1.4.2
pillow==9.1.0
pluggy==1.0.0
py==1.11.0
py4j==0.10.9.3
pyarrow==7.0.0
pyparsing==3.0.8
pyspark==3.2.1
pytest==7.1.2
python-dateutil==2.8.2
pytz==2022.1
six==1.16.0
tomli==2.0.1
wget==3.2

注意
上のファイルは固有のパッケージのバーションを列挙しています。互換性を高めるために、ご自身のall-puporseクラスターにインストールされているバージョンとこれらのバージョンを相互参照させることができます。Databricks runtime releasesにあるお使いのDatabricksランタイムバージョンの「System environment」セクションを参照ください。

これで、あなたのリポジトリの構成は以下のようになっているはずです。

|-- covid_analysis
|   `-- transforms.py
|-- notebooks
|   |-- covid_eda_modular
|   `-- covid_eda_raw (optional)
`-- requirements.txt

ステップ 3.5: リファクタリングしたノートブックの実行

このサブステップでは、covid_analysis/transforms.pyにある共有コードを呼び出すcovid_eda_modularノートブックを実行します。

リポジトリのReposペインで、notebooksフォルダの中にあるcovid_eda_modularノートブックをダブルクリックします。
Fileの隣のドロップダウンリストから、このノートブックをアタッチするクラスターを選択します。
Run Allをクリックします。
プロンプトが表示された場合には、Attach & RunあるいはStart, Attach & Runをクリックします。
ノートブックの処理が終わるのを待ちます。

ノートブックが処理を終えると、covid_eda_rawノートブックと同じ結果を確認することができます。ノートブック上でデータのグラフを確認でき、Deltaテーブルには600行以上の生データが格納されます。このノートブックの実行を開始した際、クラスターが起動していない場合、結果を表示するまでに数分かかることがあります。

ステップ 3.6: ノートブックと関連コードのチェックイン

リポジトリのReposペインでfirst_modulesブランチをクリックします。
best-notebooksダイアログのChangesタブで以下が選択されていることを確認します。
- requirements.txt
- covid_analysis/transforms.py
- notebooks/covid_eda_modular.py
Summary (required) にはAdded refactored notebookと入力します。
Description (optional) にはThis is the second version of the notebookと入力します。
Commit & Pushをクリックします。
Historyをクリックし、ポップアップのCreate a pull request on your git providerリンクをクリックします。
GitHubで、Pull requestsタブをクリックし、プルリクエストを作成し、プルリクエストをmainブランチにマージします。
Databricksワークスペースに戻り、best-notebooksダイアログが表示されている場合には閉じます。

ステップ 4: 共有コードのテスト

このステップでは、上のステップの共有コードをテストします。しかし、covid_eda_modularノートブック自身を実行することなしに、このコードをテストしたいと考えています。これは、もし共有コードが実行に失敗するのであれば、まず間違いなくノートブック自身の処理も失敗するためです。後でメインのノートブックが失敗する前に、最初に共有コードで失敗を捕捉したいと考えます。このテストテクニックはソフトウェアエンジニアリングのベストプラクティスです。

ステップ 4.1: リポジトリで別の作業用ブランチを作成

ワークスペースで、お使いのリポジトリのReposペインでfirst_modulesブランチをクリックします。
best-notebooksダイアログで、first_modulesブランチの隣のドロップダウンの矢印をクリックし、mainを選択します。
Pullボタンをクリックします。プルを実行するプロンプトが表示されたらConfirmをクリックます。
+ (Create branch) ボタンをクリックします。
first_testsを入力しEnterを押します。(ブランチに別の名前をつけることもできます)
ダイアログを閉じます。

ステップ 4.2: テストの追加

このサブステップでは、あなたの共有コードをテストするためにpytestフレームワークを使用します。これらのテストにおいては、特定のテスト結果が達成されたかどうかをassertします。あるテストが期待しない結果を出した際には、その特定のテストはアサーションに失敗し、テスト自体が失敗します。

リポジトリのReposペインで、リポジトリ名の隣のドロップダウンの矢印をクリックし、Create > Folderをクリックします。
New Folder Nameダイアログでtestsを入力し、Create Folderをクリックします。
リポジトリのReposペインで、testsの隣のドロップダウンの矢印をクリックして、Create > Fileをクリックします。
New File Nameダイアログでtestdata.csvを入力し、Create Fileをクリックします。
リポジトリのReposペインで、testフォルダをクリックし、testdata.csvをクリックします。

エディタウィンドウで以下のテストデータを入力します。

entity,iso_code,date,indicator,value
United States,USA,2022-04-17,Daily ICU occupancy,
United States,USA,2022-04-17,Daily ICU occupancy per million,4.1
United States,USA,2022-04-17,Daily hospital occupancy,10000
United States,USA,2022-04-17,Daily hospital occupancy per million,30.3
United States,USA,2022-04-17,Weekly new hospital admissions,11000
United States,USA,2022-04-17,Weekly new hospital admissions per million,32.8
Algeria,DZA,2022-04-18,Daily ICU occupancy,1010
Algeria,DZA,2022-04-18,Daily ICU occupancy per million,4.5
Algeria,DZA,2022-04-18,Daily hospital occupancy,11000
Algeria,DZA,2022-04-18,Daily hospital occupancy per million,30.9
Algeria,DZA,2022-04-18,Weekly new hospital admissions,10000
Algeria,DZA,2022-04-18,Weekly new hospital admissions per million,32.1

注意
テストデータを利用することはソフトウェアエンジニアリングのベストプラクティスです。これによって、本当のデータと同じフォーマットを持つ小規模のデータを用いて、迅速にテストを実行することができます。もちろん、テストを実行する前に、このテストデータが本当のデータを正確に表現していることを常に確認すべきです。

リポジトリのReposペインで、testsフォルダの隣のドロップダウンの矢印をクリックして、Create > Fileをクリックします
New File Nameダイアログでtransforms_test.pyを入力し、Create Fileをクリックします。
リポジトリのReposペインで、testフォルダをクリックし、transforms_test.pyをクリックします。

エディタウィンドウで以下のコードを入力します。これらのテストでは、標準的なpytestのfixturesとダミーのインメモリpandasデータフレームを使用します。

Python

# Test each of the transform functions.
import pytest
from textwrap import fill
import os
import pandas as pd
import numpy as np
from covid_analysis.transforms import *
from pyspark.sql import SparkSession

@pytest.fixture
def raw_input_df() -> pd.DataFrame:
  """
  Create a basic version of the input dataset for testing, including NaNs.
  """
  return pd.read_csv('tests/testdata.csv')

@pytest.fixture
def colnames_df() -> pd.DataFrame:
  df = pd.DataFrame(
    data=[[0,1,2,3,4,5]],
    columns=[
      "Daily ICU occupancy",
      "Daily ICU occupancy per million",
      "Daily hospital occupancy",
      "Daily hospital occupancy per million",
      "Weekly new hospital admissions",
      "Weekly new hospital admissions per million"
    ]
  )
  return df

# Make sure the filter works as expected.
def test_filter(raw_input_df):
  filtered = filter_country(raw_input_df)
  assert filtered.iso_code.drop_duplicates()[0] == "USA"

# The test data has NaNs for Daily ICU occupancy; this should get filled to 0.
def test_pivot(raw_input_df):
  pivoted = pivot_and_clean(raw_input_df, 0)
  assert pivoted["Daily ICU occupancy"][0] == 0

# Test column cleaning.
def test_clean_cols(colnames_df):
  cleaned = clean_spark_cols(colnames_df)
  cols_w_spaces = cleaned.filter(regex=(" "))
  assert cols_w_spaces.empty == True

# Test column creation from index.
def test_index_to_col(raw_input_df):
  raw_input_df["col_from_index"] = raw_input_df.index
  assert (raw_input_df.index == raw_input_df.col_from_index).all()

これで、あなたのリポジトリの構成は以下のようになっているはずです。

|-- covid_analysis
|   `-- transforms.py
|-- notebooks
|   |-- covid_eda_modular
|   `-- covid_eda_raw (optional)
|-- requirements.txt
`-- tests
    |-- testdata.csv
    `-- transforms_test.py

ステップ 4.3: テストの実行

このウォークスルーをスピードアップするために、このサブステップでは上述のテストを実行するためにインポートされたノートブックを使用します。このノートブックは、テストが依存するPythonパッケージをダウンロードし、お使いのワークスペースにインストールし、テストを実行し、テストの結果をレポートします。お使いのクラスターのwebターミナルからpytestを実行することもできますが、ノートブックから実行した方が便利です。

Reposペインで、リポジトリの名前をクリックし、notebooksフォルダの隣のドロップダウンの矢印をクリックし、Importをクリックします。
Import Notebooksダイアログで、
1. Import fromでは、URLを選択します。
2. GitHubのdatabricks/notebook-best-practicesリポジトリのrun_unit_testsノートブックの生のコンテンツのURLを入力します。URLを取得するには、
  1. https://github.com/databricks/notebook-best-practices に移動します。
  2. notebooksフォルダをクリックします。
  3. run_unit_tests.pyファイルをクリックします。
  4. Rawをクリックします。
  5. ブラウザのアドレスバーに表示される完全なURLをコピーし、Import Notebooksダイアログに貼り付けます。
3. Importをクリックします。
ノートブックが表示されていない場合、リポジトリのReposペインでnotebooksフォルダをクリックし、run_unit_testsノートブックをダブルクリックします。
Fileの隣のドロップダウンリストからノートブックをアタッチするクラスターを選択します。
Run Allをクリックします。
プロンプトが表示された場合には、Attach & RunあるいはStart, Attach & Runをクリックします。
ノートブックの処理が終わるのを待ちます。

ノートブックの処理が終わると、ノートブックには他の関連情報とともに通過したテストの数、失敗したテストの数に関する情報を確認することができます。このノートブックの実行を開始した際、クラスターが起動していない場合、結果を表示するまでに数分かかることがあります。

これで、リポジトリの構造は以下のようになっているはずです。

|-- covid_analysis
|   `-- transforms.py
|-- notebooks
|   |-- covid_eda_modular
|   |-- covid_eda_raw (optional)
|   `-- run_unit_tests
|-- requirements.txt
`-- tests
    |-- testdata.csv
    `-- transforms_test.py

ステップ 4.4: ノートブックと関連テストのチェックイン

リポジトリのReposペインでfirst_testsブランチをクリックします。
best-notebooksダイアログのChangesタブで以下が選択されていることを確認します。
- tests/transforms_test.py
- notebooks/run_unit_tests.py
- tests/testdata.csv
Summary (required) にはAdded testsと入力します。
Description (optional) にはThese are the unit tests for the shared code.と入力します。
Commit & Pushをクリックします。
Historyをクリックし、ポップアップのCreate a pull request on your git providerリンクをクリックします。
GitHubで、Pull requestsタブをクリックし、プルリクエストを作成し、プルリクエストをmainブランチにマージします。
Databricksワークスペースに戻り、best-notebooksダイアログが表示されている場合には閉じます。

ステップ 5: ノートブックを実行するジョブの作成

上のステップでは、共有コードを手動でテストし、手動でノートブックを実行しました。このステップでは、オンデマンドあるいは定期的なスケジュールで、自動でノートブックを実行し、共有コードをテストするためにDatabricksジョブを使用します。

ステップ 5.1: ノートブックのテストを実行するジョブタスクの作成

Data Science & EngineeringあるいはDatabricks Machine Learning環境のサイドバーでWorkflowsをクリックします。
JobsタブでCreate Jobをクリックします。
Add a name for your jobにはcovid_reportを入力します。
Task nameにはrun_notebook_testsを入力します。
TypeではNotebookを選択します。
SourceではGitを選択します。
Add a git referenceをクリックします。
Git informationダイアログで、
1. Git repository URLにはお使いのGitHubリポジトリのGitHubClone with HTTPSのURLを入力します。本書では、URLの最後がbest-notebooks.gitであることを前提としています。例えば、https://github.com/<your-GitHub-username>/best-notebooks.gitとなります。
2. Git providerではGitHubを選択します。
3. Git reference (branch / tag / commit) にはmainと入力します。
4. Git reference (branch / tag / commit) の隣ではbranchを選択します。
5. Confirmをクリックします。
Pathにはnotebooks/run_unit_testsを入力します。ファイルの拡張子.pyを含めないでください。
Clusterには、以前のステップで使用したクラスターを選択します。
Createをクリックします。

注意
このシナリオでは、このノートブックを定期的に実行するために、ジョブをスケジュールするためにノートブックのスケジュールで説明されているように、ノートブック上のスケジュールボタンを使用することはお勧めしません。これは、スケジュールボタンがワークスペースのリポジトリにあるノートブックの最新の作業中のコピーを用いたジョブを作成するためです。そうではなく、レポジトリ上でコミットされた最新のノートブックのバージョンを用いたジョブを作成する上述の指示に従うことをお勧めします。

ステップ 5.2: メインのノートブックを実行するジョブタスクの作成

+ (Add more tasks to your job here) アイコンをクリックします。
Task nameにはrun_main_notebookを入力します。
TypeではNotebookを選択します。
Pathにはnotebooks/covid_eda_modularを入力します。ファイルの拡張子.pyを含めないでください。
Clusterには、以前のステップで使用したクラスターを選択します。
Create taskをクリックします。

ステップ 5.3: ジョブの実行

Run nowをクリックします。
ポップアップでView runをクリックします。
注意
すぐにポップアップが消える場合、以下を実施してください。
1. Data Science & EngineeringあるいはDatabricks Machine Learning環境のサイドバーでWorkflowsをクリックします。
2. Job runsタブで、Jobsカラムのcovid_reportの最新のジョブのStart timeをクリックします。
ジョブの結果を確認するには、run_notebook_testsタイル、run_main_notebookタイル、あるいは両方をクリックします。

注意
このジョブはオンデマンドです。このジョブを定期的に実行するにはジョブのスケジュールを参照ください。

(オプション)ステップ 6: コードの変更があった際に自動でコードをテストしノートブックを実行するようにリポジトリをセットアップ

以前のステップでは、ある時点、あるいは繰り返しベースで自動的に共有コードをテストし、ノートブックを実行するためにジョブを使用しました。しかし、変更がお使いのGitHubリポジトリにマージされた際に、自動でテストを起動することを好むかもしれません。GitHub ActionsのようなCI/CDプラットフォームを用いることで、この自動化を実現することができます。

ステップ 6.1: ワークスペースに対するGitHubアクセスのセットアップ

このサブステップでは、変更がリポジトリにマージされた際にワークスペースでジョブを実行するGitHub Actionsワークフローをセットアップします。アクセスできるようにするために、GitHubにユニークなDatabricksのトークンを指定します。

セキュリティ上の理由から、DatabricksワークスペースのユーザーのパーソナルアクセストークンをGitHubに提供することはお勧めしません。代わりに、GitHubにはDatabricksのサービスプリンシパルに関連づけられているDatabricksのアクセストークンを提供することをお勧めします。手順に関しては、GitHub ActionsマーケットプレースのRun Databricks Notebook GitHub ActionのAWSセクションをご覧ください。

重要！
ノートブックは、トークンに関連づけられているアイデンティティのワークスペースのアクセス権を用いて実行されますので、サービスプリンシパルを使うことをお勧めします。個人的な探索目的のみで、かつ、このやり方が非推奨であるセキュリテイ上の理由を理解しているのであれば、DatabricksワークスペースのユーザーのパーソナルアクセストークンをGitHubに提供したい場合は、ワークスペースのユーザーのパーソナルアクセストークンの作成の手順をご覧ください。

ステップ 6.2: GitHub Actionsワークフローの追加

このサブステップでは、リポジトリにプルリクエストがあった場合にrun_unit_testsノートブックを実行するために、GitHub Actionsワークフローを追加します。

このサブステップでは、お使いのGitHubリポジトリの複数のフォルダ階層に格納されるファイルにGitHub Actionsワークフローを格納します。GitHub Actionsが適切に動作するためには、GitHub Actionsは特定のネストされたフォルダ階層に存在する必要があります。Databricks Reposのユーザーインタフェースでは、ネストされたフォルダ階層を作成できないので、このステップを完了するためにはGitHubリポジトリのウェブサイトを使用する必要があります。

GitHubリポジトリのウェブサイトでCodeをクリックします。
Switch branches or tagsドロップダウンリストで、選択されていない場合にはmainを選択します。
Switch branches or tagsドロップダウンリストで、Find or create a branchボックスが表示されていない場合には、再度mainをクリックします。
Find or create a branchボックスでは、adding_github_actionsを入力します。
Create branch: adding_github_actions from ‘main’ をクリックします。
Add file > Create new fileをクリックします。
Name your fileには、.github/workflows/databricks_pull_request_tests.ymlを入力します。

エディタウィンドウに以下のコードを入力します。このコードはrun_unit_testsノートブックを実行するためにRun Databricks Notebook GitHub Actionを使用するためのpull_requestフックを宣言して使用ます。

下のコードでは、以下を置換してください。

<your-workspace-instance-URL>をお使いのDatabricksインスタンス名で置き換え
<your-access-token>を上で生成したトークンで置き換え
<your-cluster-id>をターゲットのクラスターIDで置き換え

YAML

name: Run pre-merge Databricks tests

on:
  pull_request:

env:
  # Replace this value with your workspace instance name.
  DATABRICKS_HOST: https://<your-workspace-instance-name>

jobs:
  unit-test-notebook:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout repo
        uses: actions/checkout@v2
      - name: Run test notebook
        uses: databricks/run-notebook@main
        with:
          databricks-token: <your-access-token>

          local-notebook-path: notebooks/run_unit_tests.py

          existing-cluster-id: <your-cluster-id>

          git-commit: "${{ github.event.pull_request.head.sha }}"

          # Grant all users view permission on the notebook's results, so that they can
          # see the result of the notebook, if they have related access permissions.
          access-control-list-json: >
            [
              {
                "group_name": "users",
                "permission_level": "CAN_VIEW"
              }
            ]
          run-name: "EDA transforms helper module unit tests"

Create a new branch for this commit and start a pull requestを選択します。
Propose new fileをクリックします。
Pull requestsタブをクリックし、プルリクエストを作成します。
プルリクエストページで、Run pre-merge Databricks tests / unit-test-notebook (pull_request) の隣のアイコンが緑のチェックマークになるのを待ちます。(アイコンが表示されるまでにしばらくの時間を要します)緑のチェックマークではなく X が表示された場合、原因を探るためにDetailsをクリックします。アイコンやDetailsが表示されない場合、Show all checksをクリックします。
緑のチェックマークが表示されたら、プルリクエストをmainブランチにマージします。

(オプション)ステップ 7: テストを起動するためにGitHubの共有コードを更新

このステップでは、共有コードに変更を加え、変更をGitHubリポジトリにプッシュすることで、上のステップで設定したGitHub Actionsに基づき、即座に自動でテストを起動します。

ステップ 7.1: リポジトリで別の作業用ブランチを作成

ワークスペースで、お使いのリポジトリのReposペインでfirst_testsブランチをクリックします。
best-notebooksダイアログで、first_testsブランチの隣のドロップダウンの矢印をクリックし、mainを選択します。
Pullボタンをクリックします。プルを実行するプロンプトが表示されたらConfirmをクリックます。
+ (Create branch) ボタンをクリックします。
trigger_testsを入力しEnterを押します。(ブランチに別の名前をつけることもできます)
ダイアログを閉じます。

ステップ 7.2: 共有コードの変更

ワークスペースでお使いのリポジトリのReposペインで、covid_analysis/transforms.pyファイルをダブルクリックします。
このファイルの3行目でコードを変更します。

Python

# Filter by country code.

を

Python

# Filter by country code. If not specified, use "USA."

に変更します。

ステップ 7.3: テストを起動するために変更をチェックイン

リポジトリのReposペインでtrigger_testsブランチをクリックします。
best-notebooksダイアログのChangesタブでcovid_analysis/transforms.pyが選択されていることを確認します。
Summary (required) にはUpdated commentと入力します。
Description (optional) にはThis updates the comment for filter_country.と入力します。
Commit & Pushをクリックします。
Historyをクリックし、ポップアップのCreate a pull request on your git providerリンクをクリックします。
GitHubで、Pull requestsタブをクリックし、プルリクエストを作成し、プルリクエストをmainブランチにマージします。
プルリクエストページで、Run pre-merge Databricks tests / unit-test-notebook (pull_request) の隣のアイコンが緑のチェックマークになるのを待ちます。(アイコンが表示されるまでにしばらくの時間を要します)緑のチェックマークではなく X が表示された場合、原因を探るためにDetailsをクリックします。アイコンやDetailsが表示されない場合、Show all checksをクリックします。
緑のチェックマークが表示されたら、プルリクエストをmainブランチにマージします。

Databricks 無料トライアル

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up