Перейти к содержанию

Кодовые модели

Доступность

Кодовые модели доступны начиная с версии AW BI 1.39.

Кодовая модель — это модель данных AW BI, трансформация данных в которой описывается исходным кодом на языке Python. Код хранится не в AW BI, а во внешнем git-репозитории, который подключается к экземпляру AW BI.

Из чего состоит кодовая модель

Кодовая модель располагается в отдельной папке репозитория и состоит из двух файлов:

  • model.py — исходный код модели на Python. В нём определяется функция main(), которая с помощью операций строит граф вычислений: получает данные из источников, соединяет их, применяет SQL-запросы и произвольные python-функции, добавляет вычисляемые поля;
  • model.yml — метаданные модели: человекочитаемое название, описание источников данных, полей и иерархий.

Рядом с ними можно разместить файл тестов test_<имя модели>.py для локальной проверки модели.

my-repo/
├── model_shop/
│   ├── model.py
│   ├── model.yml
│   └── test_model_shop.py
└── model_orders/
    ├── model.py
    └── model.yml

Одна папка репозитория соответствует одной кодовой модели. Папки с моделями могут быть вложены в подпапки — AW найдёт модели на любой глубине.

При загрузке репозитория AW просматривает все папки и считает моделью ту, которая удовлетворяет правилам:

  • в папке есть оба файла — model.py и model.yml; папка только с одним из них моделью не считается;
  • внутри папки нет подпапок. Служебные папки, начинающиеся с точки или подчёркивания (__pycache__, .venv и т.п.), при загрузке игнорируются и подпапками не считаются;
  • имя папки не начинается с точки или подчёркивания — в такие папки AW не заглядывает;
  • имя папки уникально в пределах репозитория: имя папки становится идентификатором модели в AW. Если две папки моделей называются одинаково, загрузится только одна из них.

Модель может молча не загрузиться

Папку, не соответствующую правилам выше, AW молча пропускает — репозиторий подключается без ошибок, а модели в нём просто нет. Так, если внутри папки модели появится обычная подпапка, AW перестанет распознавать модель, а ранее загруженная модель удалится из AW при следующем обновлении репозитория.

Жизненный цикл кодовой модели

  • Разработка

    Разработчик создаёт git-репозиторий, настраивает рабочее место (IDE и клиентская библиотека analytic-workspace-client) и пишет код модели, проверяя его локальными тестами.

  • Публикация

    Готовый код мержится в production-ветку репозитория (например, master).

  • Подключение

    Технический администратор указывает ссылку на репозиторий в аккаунте AW. Ссылка формируется по правилам из раздела Git-репозитории. Подробное описание действий технического администратора приведено в руководстве пользователя.

  • Актуализация

    Изменения, смерженные в production-ветку, AW подхватывает автоматически. Также можно зайти в нужную кодовую модель и нажать «Обновить структуру».

Кодовые модели и etl-скрипты

Кодовые модели и etl-скрипты решают схожую задачу — кастомизация трансформации данных модели на Python. Ключевые отличия:

Кодовые модели ETL-скрипты
Где хранится код Во внешнем git-репозитории, версионирование через git Внутри AW BI, в самой модели
Кому доступно Разработчикам с доступом к репозиторию Авторам моделей прямо в интерфейсе AW
Тестирование Локальные автоматические тесты (pytest) Ручной запуск в редакторе
Workflow разработки Git-ветки, code review, merge в production-ветку Сразу в рабочей модели

Общее правило выбора: если трансформация должна жить по правилам разработки ПО (версии, ревью, тесты) — выбирайте кодовые модели.

Разделы руководства

  • Настройка рабочего места

    Python, Java, виртуальное окружение, VS Code и клиентская библиотека

    Открыть

  • Метаданные модели

    Файл model.yml: источники данных, поля и иерархии

    Открыть

  • Код модели

    Файл model.py: функция main() и построение графа вычислений

    Открыть

  • Операции (API)

    Справочник всех операций кодовых моделей: use_data_source, apply_sql, apply_join и др.

    Открыть

  • Тесты

    Локальный запуск моделей с помощью pytest

    Открыть

  • Git-репозитории

    Создание репозитория, формат ссылки для подключения, ветки и merge

    Открыть

  • Примеры

    Сквозной пример разработки кодовой модели

    Открыть