11 ノートブック

この章では、ワークスペースでのノートブックの使用および管理について説明します。

トピック:

ノートブックでのコードの開発

データ・エンジニアとデータ・サイエンティストは、Oracle AI Data Platform Workbenchのノートブックをインタラクティブにコードを開発し、データを探索するための共通ツールとして使用できます。

Oracle AI Data Platform Workbenchは現在、ノートブックでPython、SQLおよびScala言語をサポートしています。ノートブックは、ワークフローの一部として実行するようにスケジュールまたは構成できます。ノートブックを実行するには、コンピュート・クラスタをアタッチする必要があります。

AIデータ・プラットフォーム・ワークベンチには、統合されたマネージド・ノートブックが付属しており、直感的な開発者エクスペリエンスを提供します。

ノートブックで使用できるコードの例については、Oracle AI Data Platform WorkbenchサンプルGitリポジトリのサンプル・コードを使用できます。

自動の保存

ノートブックは2分ごとに自動的に保存されます。

ノートブックのインポートおよびエクスポート

現在、ノートブック・ファイル(*.ipynb)をローカル・マシンからワークスペースにインポートできます。

ノートブックのエクスポートは現在サポートされていません。

ノートブックを作成します

管理者権限を持つ任意のワークスペースにノートブックを作成できます。

  1. ホーム・ページで、ワークスペースに移動します。
  2. 「作成」、「ノートブック」の順にクリックします。
  3. 名前と説明を入力し、「作成」をクリックします。

ノートブックへの既存のクラスタのアタッチ

ノートブックでは、開発されたコードの計算能力を提供するために、クラスタがアタッチされている必要があります。

  1. ホーム・ページで、ワークスペースに移動し、ノートブックを開きます。
  2. 「アクション」をクリックし、「既存のクラスタのアタッチ」をクリックします。
  3. 使用するクラスタをリストからクリックします。
    ノートブックが正常にアタッチされると、「クラスタ: (ClusterName)実行中」が表示されます。これには数分かかる場合があります。

ノートブックのクラスタの作成

ノートブック・インタフェースから直接新しいクラスタを作成し、すぐにアタッチできます。

詳細は、コンピュート・クラスタについてを参照してください。
  1. ホーム・ページで、ワークスペースに移動し、ノートブックを開きます。
  2. 「処理」、「クラスタの作成」の順にクリックします。
  3. 「ランタイム・バージョン」を選択します。
  4. クラスタのドライバ・オプションを選択します。
  5. クラスタのワーカー・オプションを選択します。これらのオプションは、すべてのクラスタ・ワーカーに適用されます。
  6. 就業者数が静的か自動的にスケーリングかを選択します。
    • [固定額]の場合は、従業員数を指定します。
    • 「自動スケール」の場合は、クラスタがスケーリングできるワーカーの最小数および最大数を指定します。
  7. 「実行期間」で、設定した非アクティブ期間後にクラスタの実行を停止するかどうかを選択します。「アイドル・タイムアウト」を選択した場合は、クラスタがタイムアウトするまでのアイドル時間を分単位で指定します。
  8. 「作成」をクリックします。

デフォルト言語

ノートブックを使用して、Python、SQLまたはScalaでApache Sparkコードを開発および実行できます。

ノートブックのデフォルト言語はPythonです。ノートブック全体または個々のセルのデフォルト言語をSQL、Scala、Markdownまたはrawテキストに変更できます。Python、SQLおよびScalaコードを同じノートブック内の異なるセルに結合できます。

ノートブックには、Python、SQLおよびScalaの構文ハイライトがあります。ノートブックのデフォルト言語に基づいて、新しいノートブック・セルが作成されます。

ノートブックの管理

独自のノートブックの名前を変更および削除できます。ノートブックをクローニングして、そのコンテンツをコピーし、新しいノートブックでそのコードを操作することもできます。

ノートブックの名前を変更し、ワークスペースのアクション・メニューから削除します。ノートブックを開くと、「ファイル」メニューから「クローン」オプションを選択することで、ノートブックをクローニングします。

ノートブックの名前を変更します

ノートブックの名前が役に立たなくなったり、関連性がなくなった場合は、いつでも変更できます。

  1. ホーム・ページで、ワークスペースに移動します。
  2. 名前を変更するノートブックの横で、「アクション」、「名前変更」の順にクリックします。
  3. 新しい名前を入力し、「保存」をクリックします。
  4. オプション: 開いているノートブックの名前を変更するには、名前をクリックして新しいノートブックを入力します。

ノートブックの削除

管理者権限を持つノートブックを削除できます。

  1. ワークスペースに移動します。
  2. 削除するノートブックの横にある「アクション」、「削除」の順にクリックします。
  3. 「削除」をクリックします

ノートブックのクローニング

既存のノートブックをクローニングして、元のノートブックの保持中に変更できるノートブックのコンテンツのコピーを作成できます。

  1. クローニングするノートブックをオープンします。
  2. ノートブック・ツールバーで、「ファイル」、「クローン」の順にクリックします。
  3. クローニングしたノートブックの新しい名前を入力します。
  4. 「参照」をクリックして、クローニングされたノートブックを保存するワークスペース・フォルダを選択します。フォルダが選択されていない場合は、クローニングするノートブックと同じフォルダにクローニングされたノートブックが作成されます。
  5. 出力を含めるかどうかを選択します。デフォルトでは、出力が含まれます。出力を除外するには、選択をクリアします。
  6. 「クローンの作成」をクリックします。クローニングされたノートブックは、指定したワークスペース・フォルダに作成されます。

ノートブック編集中のリソースの参照

ノートブックにいるときは、ノートブックを離れることなく、左側のカタログまたはワークスペース・オブジェクトを参照できます。

オブジェクトを左側のペインからノートブックにドラッグ・アンド・ドロップすると、オブジェクト名またはフルパスがコピーされ、ノートブック・セルに貼り付けられます(コンテキストによって異なります)。


ノートブックが開き、オブジェクトがノートブックにドラッグ・アンド・ドロップされます

左側のペインの各カタログまたはワークスペース・オブジェクトに使用できるボタンおよびコンテキスト・メニュー・オプションもあります。左側のナビゲーションのコンテキスト・メニューには、サンプル・コード、コピー名またはコピー・パスをコピーするオプションがあり、ノートブック・セルに貼り付けることができます。


ノートブックの左ペインに表示されるコンテキスト・メニュー・オプション

ノートブックの実行

所有しているノートブックまたは共有されているノートブックからコードを実行できます。

コードは、オンデマンドの実行、1回かぎりの手動実行としての実行、スケジュールされたノートブック・ジョブの作成の3つの方法を使用して、ノートブックから実行できます。オンデマンドで実行されるジョブは、1回のみ実行されます。

ノートブック内でのターミナル・コマンドの実行

ノートブック内で基本的なターミナル・コマンドまたはシェル・コマンドを実行するには、接頭辞'!'を付けます。たとえば、unzipコマンドを使用して、ワークスペース内のZIPファイルから抽出できます。


unzipコマンドの使用例

シェル・スクリプトの実行には、Pythonでサブプロセス・モジュールを使用することもできます。


使用中のサブプロセス・コマンドの例

シェル・コマンドの代替としてファイルを解凍するなどのタスクには、zipfileなどのネイティブPythonモジュールを使用することもできます。

制限事項

現在、Oracle AI Data Platform Workbenchでは、pip install、CI/CD、Gitまたはversion controlシステムのネイティブ・サポートが提供されていません。

ノートブック・セルの実行オプション

ノートブックの「実行」メニューには、ノートブックでセルを実行するためのオプションが用意されています。

<ここにセクション・タイトルを入力してください>

ノートブックのセルを実行するためのすべてのオプションは、ノートブックの上部にある「実行」メニューから検索できます。


ノートブックの「実行」メニューが開き、ノートブックのセルを実行するためのオプションが表示されます

表11-1ノートブック・セルの実行オプション

オプション 説明
すべて実行 ノートブック内のすべてのセルを順番に実行します。
選択したセルの実行 現在選択されている1つ以上のセルを実行します。
上記すべてを実行 現在選択されているセルと、ノートブックで現在選択されているセルの上に表示されるセルを実行します。
次のすべてを実行 現在選択されているセルと、ノートブックで現在選択されているセルの下に表示されるセルを実行します。
選択されたテキストの実行 選択したコードのセグメントをセルで実行します。
最終実行セルに移動 ノートブックで最近実行されたセルに移動します。
すべてのセル出力をクリア ノートブック内のすべてのセルから出力を削除します。

ノートブックからのコードの実行

ノートブックで開発されたすべてのコードを一度に実行するか、一度に1つのセルを実行するかを選択できます。

ノートブックでコードを実行するためのキーボード・ショートカットは次のとおりです。
  • MacOS: Cmd + Return
  • Windows: [Ctrl]+[Enter]

ノートブック再生ボタン 「再生」ボタンをクリックして1つのセルでコードを実行することも、「すべて実行」をクリックしてノートブック全体を実行することもできます。

  1. ホーム・ページで、「ワークスペース」をクリックします。
  2. ノートブックに移動します。
  3. 「すべて実行」をクリックします。
  4. 「ワークフロー」、「ジョブ実行」の順にクリックして、ノートブック・ジョブ実行のステータスを確認します。

別のノートブックからコードを実行

ノートブックで%run magicコマンドを使用すると、別のノートブックからのコードを含めることができます。

次の例では、called-notebook.ipynbという名前のノートブックからノートブックcaller-notebook.ipynbにコードを取り込みます。
  1. nbconvert Pythonライブラリをインストールします。
  2. 次の例に示すように、セルで%runコマンドを使用します。
    %run /Workspace/folder1/called-notebook.ipynb

これらのステップに従うと、called-notebook.ipynbという名前のノートブックは、ユーザー・プリンシパル(caller-notebook.ipynbなど)を使用してただちに実行され、caller-notebook.ipynbの接続されたクラスタが使用されます。called-notebook.ipynbに定義されているすべての関数および変数が、すぐにcaller-notebook.ipynbという名前のノートブックで使用できるようになります。

oidlUtilsによるノートブック出力の共有

oidlUtilsで使用可能なユーティリティを使用して、ノートブック・タスクによるコンテンツ出力を取得および共有できます。

oidlUtilsは、Oracle AI Data Platform Workbenchのすべてのユーザーが使用できるユーティリティのセットです。ノートブック間でコンテンツを共有する場合、oidlUtilsをコールして1つのノートブックに引数を渡し、コール元のノートブックに出力を戻すことができます。また、ノートブックのジョブ・タスクでコールして、出力を親タスク(ノートブックでコールするタスク)に戻すことができます。この方法を使用すると、ノートブック・タスクによって返された構造化出力を取得して使用できます。

ノートブックでは、次のoidlUtilsモジュールを使用できます。

モジュール 説明 例
ノート ノートブック・タスク実行を編成し、単一の構造化結果(通常はJSON文字列)をコール元に返します。 
oidlUtils.notebook.run(
    notebook_path: str,
    timeout_seconds: int = 0, (Optional)
    parameters: dict (Optional)
) -> str
ノート ノートブックがタスク実行を終了し、単一の文字列結果(通常はJSONペイロード)をコール元のノートブックまたはジョブ/タスク出力APIに戻すことを許可します。 
oidlUtils.notebook.exit(value: str)

例1: ノートブックとノートブックの共有

この例では、ノートブックAを使用してノートブックBを呼び出します。ノートブックBは、ノートブックAが取得および使用するように設定されている結果ペイロードを返します。

ノートブックA

result = oidlUtils.notebook.run("NotebookB", 0)
print("Output from Notebook B:", result)
ノートブックB
import json

payload = {
"status": "SUCCESS",
"rows_processed": 1234,
"output_table": "sales_gold",
"run_id": "run_2026_02_11"
}

json_payload = json.dumps(payload)
oidlUtils.notebook.exit(str(json_payload))

ノートブックBからの出力

{"status": "SUCCESS", "rows_processed": 1234, "output_table": "sales_gold", "run_id": "run_2026_02_11"}

例2: ジョブ・タスクを介した出力の受渡し

この例では、ノートブックがタスクとして実行されたときにJSONファイルを返します: oidlUtils.notebook.exit(json.dumps(payload))。 

import json

payload = {
    "status": "SUCCESS",
    "output_table": "sales_gold",
    "rows_processed": 1234
}

oidlUtils.notebook.exit(json.dumps(payload))

次に、ノートブック・タスクを使用してジョブを実行し、APIコールを介してタスク出力を取得します: endpoint = f"https://<workspace-url>/jobs/runs/get-output?run_id={task_run_id}" and response = requests.get(endpoint, headers=headers).json()。 

import requests

task_run_id = "<task_run_id>"

endpoint = f"https://<workspace-url>/jobs/runs/get-output?run_id={task_run_id}"
response = requests.get(endpoint, headers=headers).json()

最後に、ノートブックによって返された出力をjob_result = response['notebook_output']['result']で取得します。 

job_result = response["notebook_output"]["result"]
payload = json.loads(job_result)

print(payload["output_table"])   # Output : sales_gold
print(payload["rows_processed"]) # Output : 1234

ノートブック・ナビゲーション

ノートブックを編成およびナビゲートするために使用できる目次を作成および保守できます。

ノートブックの左上にある目次アイコンをクリックして、ノートブック・アウトラインを表示できます。目次は、作成可能な値下げ見出しに基づいて自動的に生成されるため、編成とナビゲーションが容易になります。

書式設定されたテキスト、見出し、リストおよびドキュメントをマークダウンとして追加して、自分および他のユーザーのノートブック・コンテンツを編成および説明できます。

値下げセルの作成

マークダウン・セルを作成して、ノートブックの目次に見出しを提供することで、編成とナビゲーションが容易になります。

  1. 「ホーム」ページからノートブックにナビゲートします。
  2. セル・タイプのドロップダウン・リストから、「Markdown」を選択します。
  3. セルに値下げを追加します。
    • マークダウン・セルには、書式設定されたテキスト、見出し、リストおよびその他のドキュメントを含めることができます。
    • 見出しを作成するには、#のあとにスペースを付けて行を開始します。見出し1は1つの #を使用し、見出し2は ##を使用します。追加の見出しレベルごとに#を追加します。

ノートブックの出力および結果

ノートブック出力が表示され、コードを含むセルの直後に新しいセルが表示されます。

セルの進行中は、セルの実行を取り消すことができます。ノートブックをワークフロー・ジョブとして実行した場合、出力は同じノートブックに表示されません。その場合、出力は対応するワークフロー・ジョブ実行の出力領域に表示されます。

出力セルからCSVまたはExcelファイルとして出力をダウンロードできます。出力セルの内容をクリップボードに直接コピーすることもできます。


「コピー」および「ダウンロード」ボタンが強調表示されたノートブック内の出力セル。「Download」メニューが開き、「Download CSV」および「Download Excel」オプションが表示されます。

ノートブック出力のダウンロード

結果パネルからノートブック・セルの結果出力を直接ダウンロードできます。

  1. 出力をダウンロードするセルの右上で、「ダウンロード」をクリックします。
  2. メニューから、出力をダウンロードする形式を選択します。

ノートブック出力のコピー

結果パネルからノートブック・セルの結果出力を直接コピーできます。

  1. 出力をダウンロードするセルの右上で、「コピー」をクリックします。
  2. 出力セルの内容がクリップボードに直接コピーされます。ノートブック内の他の場所または外部の場所に貼り付けることができます。

ノートブックの外観

左側のナビゲーション・パネルを最小化するか、ノートブック・ビューを展開することで、ノートブックでの作業に使用できる画面領域を変更できます。

ノートブックでの作業中にOracle AI Data Platform Workbenchの左側のナビゲーション・パネルを最小化して、ナビゲーション・パネルの右下にある「最小化」パネルをクリックすると、使用可能な画面領域を増やすことができます。


「Minimum Panel」アイコンが強調表示された「AI Data Platform Workbench」の左側のナビゲーションペイン

ノートブックの右上にある「展開」をクリックして、使用可能な領域を拡張し、より大きなセルおよび出力を読みやすくすることで、ノートブックを展開することもできます。


ノートブックが開き、「展開」アイコンが強調表示されています

セル実行番号

各ノートブック・セルには、セルの実行順序を示す実行番号が表示されます。この数値は、セルが実行されるたびに更新されます。セルは任意の順序で実行できるため、実行番号がノートブック内のセルの物理的な順序と一致しない場合があります。

ジョブ実行を管理

ジョブ実行を作成して、ノートブックからコードを実行する方法とタイミングを管理できます。

手動ジョブ実行は、再度実行することも、後でスケジュールに従って実行するように設定することもできます。スケジュールされたジョブ実行は、設定したスケジュールに基づいて自動的にトリガーされます。スケジュールが構成されていないかぎり、手動ジョブは1回のみ実行されます。

ノートブックからの手動実行ジョブの作成

ノートブックで開発したコードから手動で実行できる未スケジュール・ジョブを作成できます。

  1. ホーム・ページで、「ワークスペース」をクリックします。
  2. ノートブックに移動します。
  3. 「アクション」をクリックし、「スケジュール」をクリックします。
  4. ジョブの名前と説明を入力します。
  5. 「参照」をクリックして、ジョブを格納する場所を選択します。「選択」をクリックします。
  6. 「クラスタ」ドロップダウンからコンピュート・クラスタを選択します。
  7. 「スケジュール」で、「手動実行」を選択します。
  8. 「作成」をクリックします。

ノートブックからのスケジュール済ジョブ実行の作成

ノートブックで開発したコードから自動的に実行されるスケジュール済ジョブを作成できます。

  1. ホーム・ページで、「ワークスペース」をクリックします。
  2. ノートブックに移動します。
  3. 「アクション」をクリックし、「スケジュール」をクリックします。
  4. ジョブの名前と説明を入力します。
  5. 「参照」をクリックして、ジョブを格納する場所を選択します。「選択」をクリックします。
  6. 「クラスタ」ドロップダウンからコンピュート・クラスタを選択します。
  7. 「スケジュール」で、「スケジュール」を選択します。
  8. 「スケジュール・ステータス」を選択します。
    • スケジュールをすぐに有効にする場合は、「アクティブ」を選択します。
    • 後でスケジュール済実行を手動で有効にする場合は、「一時停止」を選択します。
  9. スケジュールの基準となるタイム・ゾーンを指定します。
  10. 「スケジュール・タイプ」を選択します。
    • 「カレンダ」には、頻度とスケジュールを繰り返す時間または日数を指定する必要があります。
    • Cron式の場合は、cron式の形式でスケジュールを指定する必要があります。
  11. 下部のリストされたランタイムをチェックして、スケジュールが正しいことを確認します。「作成」をクリックします。

ノートブックのキーボード・ショートカット

キーボード・ショートカットを使用すると、ノートブックでのコマンドの使用を簡素化できます。

ウィンドウ macOS アクション
[Ctrl]+[Enter] コマンド+返品 セルの実行
[Shift]+[Enter] [Shift]+[Return] セルを実行し、次のセルに進みます
[Ctrl]+[S] [Cmd]+[S] ノートブックの保存
[Ctrl]+[N] [Ctrl]+[N] 新規ノートブック
[Ctrl]+[Z] コマンド+ Z 元に戻す
[Ctrl]+[Y] コマンド+ Y やり直し
[Ctrl]+[C] コマンド+ C コピー
[Ctrl]+[X] コマンド+X 切取り
[Ctrl]+[V] コマンド+ V 貼付け
Ctrl + Alt + F [Ctrl]+[Option]+[F] 検索と置換
Ctrl + Shift + A Ctrl + Shift + A 上のセルを挿入
[Ctrl] + [Shift] + [B] [Ctrl] + [Shift] + [B] 下にセルを挿入
[Ctrl]+[Alt]+[↑] [Ctrl]+[Option]+[↑] セルを上に移動
[Ctrl]+[Alt]+[↓] [Ctrl]+[Option]+[Down] セルを下に移動
[Ctrl]+[D] [Ctrl]+[D] セルを削除
[Alt]+[Shift]+[Enter] オプション+シフト+返品 すべて実行
[Alt]+[Shift]+[↑] オプション+シフト+上へ 上のすべてのセルを実行

既存のApache SparkコードのOracle AI Data Platform Workbenchへの移行

Apache SparkコードをOracle AI Data Platform Workbenchノートブックで使用できるように移行できます。

既存のSparkコードを他のプラットフォームから移行する場合は、次のガイドラインを使用して、ノートブックで使用するようにコードを調整できます。

表11-2 Apache SparkからAIデータ・プラットフォームへの移行のガイドライン

ガイドライン Details
SparkSession作成コマンドの削除 AIデータ・プラットフォーム・ワークベンチは、コンピュート・クラスタごとにSparkContextを自動的に作成します。セッション作成コマンドを削除するか、SparkSession.builder().getOrCreate()に置き換えることをお薦めします。
sys.exit()やspark.stop()などのセッション終了コマンドを削除します。 目的のすべてのコンピュート・クラスタは共有クラスタであるため、いずれかのユーザーがSparkSessionを停止する場合、たとえばsys.exit()またはspark.stop()を使用して、すべてのユーザーに対してクラスタを再起動する必要があります。中断を回避するために、ノートブック内のこれらのコマンドは避けることをお薦めします。