Python의 번들 구성

Databricks 자산 번들용 Python은 Databricks 자산 번들을 확장하여 다음을 수행할 수 있도록 합니다.

• 작업 및 파이프라인을 Python 코드로 정의합니다. 이러한 정의는 YAML에 정의된 정의와 공존할 수 있습니다.
• 메타데이터를 사용하여 작업 또는 파이프라인을 동적으로 만듭니다. 메타데이터를 사용하여 리소스 만들기를 참조하세요.
• 번들 배포 중에 YAML 또는 Python에 정의된 작업을 수정합니다. YAML 또는 Python에 정의된 작업 수정을 참조하세요.

Databricks Asset Bundles databricks-bundles 패키지 에 대한 Python 지원에 대한 참조 설명서는 다음에서 https://databricks.github.io/cli/experimental/python/사용할 수 있습니다.

요구 사항

Databricks 자산 번들에 Python 지원을 사용하려면 먼저 다음을 수행해야 합니다.

1. Databricks CLI 버전 0.248.0 이상을 설치합니다. Databricks CLI를 설치하거나 업데이트하는 방법을참조하세요.

2. 아직 인증하지 않은 경우 Databricks 작업 영역에 인증합니다.

   databricks configure
   

3. uv를 설치합니다. uv 설치를 참조하세요. Databricks 자산 번들용 Python은 uv를 사용하여 가상 환경을 만들고 필요한 종속성을 설치합니다. 또는 venv와 같은 다른 도구를 사용하여 Python 환경을 구성할 수 있습니다.

템플릿에서 프로젝트 만들기

Databricks 자산 번들 프로젝트에 대한 새 Python 지원을 만들려면 템플릿을 사용하여 experimental-jobs-as-code 번들을 초기화합니다.

databricks bundle init experimental-jobs-as-code

메시지가 표시되면 프로젝트에 이름(예: my_jobs_as_code_project이름)을 지정하고 Notebook 및 Python 패키지 포함을 수락합니다.

이제 새 프로젝트 폴더에 새 가상 환경을 만듭니다.

cd my_jobs_as_code_project
uv sync

기본적으로 템플릿에는 파일에 Python으로 정의된 작업의 예가 resources/my_jobs_as_code_project_job.py 포함됩니다.

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 사전을 허용합니다. 데이터 클래스 구문을 사용하여 작업을 생성할 수도 있습니다.

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 파일은 experimental 섹션에 지정된 진입점을 통해 databricks.yml에서 로드됩니다.

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'

기본적으로 resources/__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.
    """

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

작업 또는 파이프라인 배포 및 실행

번들을 개발 대상에 배포하려면 번들 프로젝트 루트의 번들 배포 명령을 사용합니다.

databricks bundle deploy --target dev

이 명령은 번들 프로젝트에 대해 정의된 모든 항목을 배포합니다. 예를 들어 기본 템플릿을 사용하여 만든 프로젝트는 [dev yourname] my_jobs_as_code_project_job이라는 작업을 작업 영역에 배포합니다. Databricks 작업 영역에서 작업 및 파이프라인 으로 이동하여 해당 작업을 찾을 수 있습니다.

번들이 배포된 후 번들 요약 명령을 사용하여 배포된 모든 항목을 검토할 수 있습니다.

databricks bundle summary --target dev

마지막으로, 작업 또는 파이프라인을 실행하려면 번들 실행 명령을 사용합니다.

databricks bundle run my_jobs_as_code_project_job

기존 번들 업데이트

기존 번들을 업데이트하려면 템플릿에서 프로젝트 만들기에 설명된 대로 프로젝트 템플릿 구조를 모델링합니다. 다음 섹션을 추가하여 Python 코드로 정의된 작업 또는 파이프라인을 포함하도록 기존의 YAML 번들을 업데이트할 수 있습니다.experimental.pythondatabricks.yml

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 패키지가 포함되어야 합니다.

pip install databricks-bundles==0.248.0

리소스 폴더에는 다음 파일이 포함되어 __init__.py 야 합니다.

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으로 변환하려면 뷰를 코드 기능으로 사용할 수 있습니다. 코드로 작업 보기를 참조하세요.

1. Databricks 워크플로에서 작업 페이지를 엽니다.
2. 지금 실행 단추의 왼쪽에 있는 케밥을 클릭한 다음 코드로 보기를 클릭합니다.

3. Python을 선택한 다음, Databricks 자산 번들 선택

4. 복사를 클릭하고 생성된 Python을 번들 프로젝트의 리소스 폴더에 Python 파일로 저장합니다.

메타데이터를 사용하여 리소스 만들기

함수의 load_resources 기본 구현은 패키지에 resources 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 사용하여 번들 변수 및 배포 대상에 액세스할 수 있습니다.

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)

    ...

자세한 내용은 Resources 및 Bundle 클래스 참조를 참조하세요.

YAML 또는 Python에 정의된 작업 수정

리소스를 로드하는 함수와 유사하게 databricks.yml 작업 변경자 함수를 참조할 수 있습니다. 이 기능은 Python에 정의된 작업 로드와 별도로 사용할 수 있으며 YAML 및 Python 모두에 정의된 리소스를 변경합니다.

먼저 번들의 루트에 mutators.py을 생성한 후, 다음 내용을 포함시킵니다:

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 실행합니다. 이렇게 하면 번들에 정의된 모든 작업이 메일 알림(없는 경우)으로 업데이트됩니다. 변경자 함수는 databricks.yml에 지정해야 하며, 지정된 순서대로 실행됩니다. 작업 변경자는 번들에 정의된 모든 작업에 대해 실행되며 업데이트된 복사본 또는 수정되지 않은 입력을 반환할 수 있습니다. 변경자는 기본 작업 클러스터 또는 SQL 웨어하우스 구성과 같은 다른 필드에도 사용할 수 있습니다.

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

함수가 변경자를 실행하는 동안 예외를 던지면 번들 배포가 중단됩니다.