Pythonでの設定

備考

プレビュー

Databricks Asset Bundle の Python サポートはパブリックプレビュー段階です。

Python for Databricks Asset Bundles は、Databricks Asset Bundles を拡張して、次のことを可能にします。

ジョブとパイプラインを Python コードとして定義します。これらの定義は、YAML で定義されている定義と共存できます。
メタデータを使用してジョブまたはパイプラインを動的に作成します。メタデータを使用したリソースの作成を参照してください。
バンドルのデプロイ中に YAML または Python で定義されたジョブを変更します。「YAML または Python で定義されたジョブの変更」を参照してください。

Databricks Asset Bundles databricks-bundles パッケージの Python サポートのリファレンスドキュメントは、 https://databricks.github.io/cli/experimental/python/ で入手できます。

必要条件

Databricks アセットバンドルの Python サポートを使用するには、まず次のことを行う必要があります。

Databricks CLI バージョン 0.248.0 以降をインストールします。「Databricks CLI のインストールまたは更新」を参照してください。
Databricks ワークスペースに対して認証を行っていない場合は、認証します。
Bash
```
databricks configure
```
uvをインストールします。uv のインストールを参照してください。Python for Databricks Asset Bundles は、uv を使用して仮想環境を作成し、必要な依存関係をインストールします。または、 venv などの他のツールを使用して Python 環境を構成することもできます。

テンプレートからプロジェクトを作成する

Databricks Asset Bundles プロジェクトの新しい Python サポートを作成するには、 experimental-jobs-as-code テンプレートを使用してバンドルを初期化します。

Bash

databricks bundle init experimental-jobs-as-code

プロンプトが表示されたら、プロジェクトに名前を付け ( my_jobs_as_code_projectなど)、ノートブックと Python パッケージを含めることを受け入れます。

次に、新しいプロジェクトフォルダに新しい仮想環境を作成します。

Bash
cd my_jobs_as_code_project
uv sync

デフォルトでは、テンプレートには Python として定義されたジョブの例が resources/my_jobs_as_code_project_job.py ファイルに含まれています。

Python
from databricks.bundles.jobs import Job


my_jobs_as_code_project_job = Job.from_dict(
    {
        "name": "my_jobs_as_code_project_job",
        "tasks": [
            {
                "task_key": "notebook_task",
                "notebook_task": {
                    "notebook_path": "src/notebook.ipynb",
                },
            },
        ],
    },
)

Job.from_dict 関数は、YAML と同じ形式を使用して Python ディクショナリを受け入れます。ジョブは、データクラス構文を使用して構築することもできます。

Python
from databricks.bundles.jobs import Job, Task, NotebookTask


my_jobs_as_code_project_job = Job(
    name="my_jobs_as_code_project_job",
    tasks=[
        Task(
            task_key="notebook_task",
            notebook_task=NotebookTask(
                notebook_path="src/notebook.ipynb",
            ),
        ),
    ],
)

Python ファイルは、databricks.ymlの experimental セクションで指定されているエントリポイントを介してロードされます。

YAML
experimental:
  python:
    # Activate the virtual environment before loading resources defined in
    # Python. If disabled, it defaults to using the Python interpreter
    # available in the current shell.
    venv_path: .venv
    # Functions called to load resources defined in Python.
    # See resources/__init__.py
    resources:
      - 'resources:load_resources'

By デフォルト, resources/__init__.py には、リソースパッケージ内のすべての Python ファイルを読み込む関数が含まれています。

Python
from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


def load_resources(bundle: Bundle) -> Resources:
    """
    'load_resources' function is referenced in databricks.yml and is responsible for loading
    bundle resources defined in Python code. This function is called by Databricks CLI during
    bundle deployment. After deployment, this function is not used.
    """

    # the default implementation loads all Python files in 'resources' directory
    return load_resources_from_current_package_module()

ジョブまたはパイプラインをデプロイして実行する

バンドルを開発ターゲットにデプロイするには、バンドルプロジェクトルートから bundle deploy コマンドを使用します。

Bash
databricks bundle deploy --target dev

このコマンドは、バンドル・プロジェクトに対して定義されているすべてのものをデプロイします。たとえば、デフォルトテンプレートを使用して作成されたプロジェクトでは、 [dev yourname] my_jobs_as_code_project_job というジョブがワークスペースにデプロイされます。そのジョブを見つけるには、Databricks ワークスペースの [ワークフロー ] に移動します。

バンドルがデプロイされたら、 bundle summary コマンドを使用して、デプロイされたすべてのものを確認できます。

Bash
databricks bundle summary --target dev

最後に、ジョブまたはパイプラインを実行するには、 bundle 実行コマンドを使用します。

Bash

databricks bundle run my_jobs_as_code_project_job

既存のバンドルを更新する

既存のバンドルを更新するには、テンプレートからのプロジェクトの作成の説明に従って、プロジェクトテンプレート構造をモデル化します。YAML を含む既存のバンドルは、databricks.ymlに experimental.python セクションを追加することで、Python コードとして定義されたジョブまたはパイプラインを含むように更新できます。

YAML
experimental:
  python:
    # Activate the virtual environment before loading resources defined in
    # Python. If disabled, it defaults to using the Python interpreter
    # available in the current shell.
    venv_path: .venv
    # Functions called to load resources defined in Python.
    # See resources/__init__.py
    resources:
      - 'resources:load_resources'

指定した仮想環境には、インストールされている databricks-bundles PyPi パッケージが含まれている必要があります。

Bash
pip install databricks-bundles==0.248.0

リソースフォルダには __init__.py 次のファイルが含まれている必要があります。

Python
from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


def load_resources(bundle: Bundle) -> Resources:
    """
    'load_resources' function is referenced in databricks.yml and
    is responsible for loading bundle resources defined in Python code.
    This function is called by Databricks CLI during bundle deployment.
    After deployment, this function is not used.
    """

    # default implementation loads all Python files in 'resources' folder
    return load_resources_from_current_package_module()

既存のジョブをPythonに変換する

既存のジョブを Python に変換するには、 コードとして表示 機能を使用できます。「ジョブをコードとして表示する」を参照してください。

Databricks Workflowsでジョブページを開きます。
[ 今すぐ実行 ] ボタンの左側にあるケバブをクリックし、[ コードとして表示 ] をクリックします。

[Python ]、[ Databricks Asset Bundles] の順に選択します。

コードとして表示、Python

「コピー 」をクリックし、生成されたPythonをバンドル・プロジェクトの「リソース」フォルダーにPythonファイルとして保存します。

ヒント

また、既存のジョブとパイプラインの YAML を表示およびコピーして、バンドル構成 YAML ファイルに直接貼り付けることもできます。

メタデータを使用したリソースの作成

load_resources 関数のデフォルト実装では、resources パッケージ内の Python ファイルが読み込まれます。Python を使用して、プログラムでリソースを作成できます。たとえば、設定ファイルをロードし、ループでジョブを作成できます。

Python
from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


from databricks.bundles.jobs import Job


def create_job(country: str):
    my_notebook = {
        "task_key": "my_notebook",
        "notebook_task": {
            "notebook_path": "files/my_notebook.py",
        },
    }


    return Job.from_dict(
        {
            "name": f"my_job_{country}",
            "tasks": [my_notebook],
        }
    )


def load_resources(bundle: Bundle) -> Resources:
    resources = load_resources_from_current_package_module()


    for country in ["US", "NL"]:
        resources.add_resource(f"my_job_{country}", create_job(country))


    return resources

バンドル変数へのアクセス

bundle パラメーターを使用して、バンドル変数とデプロイメント・ターゲットにアクセスできます。

Python
from databricks.bundles.core import Bundle, Resources, Variable, variables

@variables
class Variables:
    warehouse_id: Variable[str]


def load_resources(bundle: Bundle) -> Resources:
    warehouse_id = bundle.resolve_variable(Variables.warehouse_id)

    ...

詳細については、リソースとバンドルクラスのリファレンスを参照してください。

YAML または Python で定義されたジョブを変更する

ジョブ・ミューテータ関数は、リソースをロードする関数と同様に、 databricks.ymlで参照できます。この機能は、Python で定義されたジョブの読み込みとは独立して使用でき、YAML と Python の両方で定義されたリソースを変更します。

まず、バンドルルートに次の内容の mutators.py を作成します。

Python
from dataclasses import replace


from databricks.bundles.core import Bundle, job_mutator
from databricks.bundles.jobs import Job, JobEmailNotifications


@job_mutator
def add_email_notifications(bundle: Bundle, job: Job) -> Job:
    if job.email_notifications:
        return job


    email_notifications = JobEmailNotifications.from_dict(
        {
            "on_failure": ["${workspace.current_user.userName}"],
        }
    )


    return replace(job, email_notifications=email_notifications)

次に、次の構成を使用して、バンドルのデプロイ中に add_email_notifications 関数を実行します。これにより、バンドルで定義されているすべてのジョブが不在の場合は、Eメール通知で更新されます。ミューテーター関数は databricks.ymlで指定する必要があり、指定された順序で実行されます。ジョブミューテーターは、バンドルで定義されているすべてのジョブに対して実行され、更新されたコピーまたは変更されていない入力を返すことができます。ミューテーターは、デフォルトジョブクラスタリングや SQLウェアハウスの構成など、他のフィールドにも使用できます。

YAML
experimental:
  python:
    mutators:
      - 'mutators:add_email_notifications'

ミューテーターの実行中に関数が例外をスローした場合、バンドルのデプロイは中止されます。

必要条件​

テンプレートからプロジェクトを作成する​

ジョブまたはパイプラインをデプロイして実行する​

既存のバンドルを更新する​

既存のジョブをPythonに変換する​

メタデータを使用したリソースの作成​

バンドル変数へのアクセス​

YAML または Python で定義されたジョブを変更する​