Настройка пакета в Python

Поддержка Python для пакетов активов Databricks расширяет пакеты ресурсов Databricks с дополнительными возможностями, которые применяются во время развертывания пакета, чтобы можно было:

• Определите ресурсы в коде Python. Эти определения могут сосуществовать с ресурсами, определенными в YAML.

• Динамически создавайте ресурсы во время развертывания пакета с помощью метаданных. См. статью "Создание ресурсов с помощью метаданных".

• Измените ресурсы, определенные в YAML или Python во время развертывания пакета. См. статью "Изменение ресурсов", определенных в YAML или Python.

  Подсказка

  Вы также можете изменить ресурсы пакета во время выполнения с помощью таких функций, как if/else condition_task или for_each_task для заданий.

Справочная документация по поддержке Python для пакета databricks Asset Bundles databricks-packages доступна по адресу https://databricks.github.io/cli/python/.

Требования

Чтобы использовать поддержку Python для пакетов ресурсов Databricks, сначала необходимо:

1. Установите интерфейс командной строки Databricks версии 0.275.0 или более поздней. См. установите или обновите CLI Databricks.

2. Авторизуйтесь в рабочей области Databricks, если вы еще этого не сделали.

   databricks configure
   

3. Установите uv. См. статью об установке uv. Пакеты ресурсов Python для Databricks используют инструмент uv для создания виртуальной среды и установки необходимых зависимостей. Кроме того, вы можете настроить среду Python с помощью других средств, таких как venv.

Создание проекта из шаблона

Чтобы создать новую Python-поддержку для проекта Databricks Asset Bundles, инициализируйте пакет, используя шаблон pydabs.

databricks bundle init pydabs

При появлении запроса присвойте проекту имя, например my_pydabs_project, и примите включение записной книжки и пакета Python.

Теперь создайте виртуальную среду в новой папке проекта:

cd my_pydabs_project
uv sync

По умолчанию шаблон содержит пример задания, определенного как Python в resources/my_pydabs_project_job.py файле:

from databricks.bundles.jobs import Job


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

Функция Job.from_dict принимает словарь Python с тем же форматом, что и YAML. Ресурсы также можно создать с помощью синтаксиса класса данных:

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


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

Файлы Python загружаются через точку входа, указанную в python разделе databricks.yml.

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_pydabs_project_job в вашей рабочей области. Это задание можно найти, перейдя к заданиям и конвейерам в рабочей области Databricks.

После развертывания пакета можно использовать команду сводки пакета для просмотра всего развернутого пакета:

databricks bundle summary --target dev

Наконец, чтобы запустить задание или конвейер, используйте команду выполнения пакета:

databricks bundle run my_pydabs_project_job

Обновление существующих пакетов

Чтобы обновить существующие пакеты, смоделируйте структуру шаблона проекта, как описано в разделе "Создание проекта из шаблона". Существующие пакеты с YAML можно обновить, чтобы включить ресурсы, определенные как код Python, добавив python раздел в databricks.yml:

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'

Указанная виртуальная среда должна содержать установленный пакет PyPi databricks-packages .

pip install databricks-bundles==0.275.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 Asset Bundles

   

4. Нажмите кнопку "Копировать " и сохраните созданный Python в виде файла Python в папке ресурсов проекта пакета.

   Подсказка

   Вы также можете просматривать и копировать YAML для существующих заданий и конвейеров, которые можно вставить непосредственно в файлы конфигурации пакета YAML.

Создание ресурсов с помощью метаданных

Реализация функции по умолчанию load_resources загружает файлы Python в resources пакете. Вы можете использовать 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

Доступ к переменным пакета

Подстановки пакетов и пользовательские переменные обеспечивают динамическое извлечение значений, чтобы параметры можно было определить во время развертывания пакета и запуска в целевом объекте. Сведения о переменных пакета см. в разделе "Пользовательские переменные".

В Python определите переменные, а затем используйте bundle параметр для доступа к ним. См. @variables декоратор, Переменные, Пакеты и Ресурсы.

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

@variables
class Variables:
    # Define a variable
    warehouse_id: Variable[str]


def load_resources(bundle: Bundle) -> Resources:
    # Resolve the variable
    warehouse_id = bundle.resolve_variable(Variables.warehouse_id)

    ...

К переменным также можно обращаться в Python с помощью подстановок.

sample_job = Job.from_dict(
    {
        "name": "sample_job",
        "tasks": [
            {
                "task_key": "my_sql_query_task",
                "sql_task": {
                    "warehouse_id": "${var.warehouse_id}",
                    "query": {
                        "query_id": "11111111-1111-1111-1111-111111111111",
                    },
    ...

Используйте переопределения целевых параметров, чтобы задать значения переменных для различных целевых параметров развертывания.

Изменение ресурсов, определенных в 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.

python:
  mutators:
    - 'mutators:add_email_notifications'

Если функции вызывают исключение во время выполнения мутатора, развертывание пакета прерывается.

Подсказка

Чтобы настроить предустановки для целевых объектов (например, для отмены расписания для целевого prod объекта), используйте режимы развертывания и предустановки. См. пользовательские предустановки.

Дополнительные ресурсы

• Примеры конфигурации пакета
• Добавление задач в задания в пакетах ресурсов Databricks
• Переопределение с параметрами целевого объекта
• bundle группа команд