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

Импорт данных в параметры: технические детали

Для базовой информации и инструкций по UI см. статью для администратора.

Импорт из файлов (CSV, XLSX)

  • Используется функция import_data из модуля core.parameters.libs.import_data.
  • Поддерживаются форматы CSV и XLSX.
  • Файл должен содержать заголовки, соответствующие ключам измерений и мер параметра.
  • Коды иерархии сопоставляются по shortname (кодам), а не по id.

Пример вызова: 

from planiqum.core.parameters.libs.import_data import import_data
import_data(data="facts.csv", parameter="demand_plan_tech_week")

Пример с запуском триггеров: 

import_data(data="facts.csv", parameter="demand_plan_tech_week", execute_triggers=True)

Импорт из pandas.DataFrame

  • Можно передать напрямую объект pandas.DataFrame вместо файла.
  • Это удобно для генерации или трансформации данных программно.

Пример: 

import pandas as pd
from planiqum.core.parameters.libs.import_data import import_data

df = pd.DataFrame([
    {"activity": "BASE", "dpu": "DPU1", "horizon__tech_week": "2024-01-W01", "value": 100},
    {"activity": "BASE", "dpu": "DPU2", "horizon__tech_week": "2024-01-W01", "value": 200},
])
import_data(data=df, parameter="demand_plan_tech_week")

Внимание: В будущем рекомендуется переходить к импорту через чистый SQL и загрузку из CSV-файлов для повышения производительности и отказа от промежуточных DataFrame.

Техническая реализация

  • Основная функция: import_data из модуля core.parameters.libs.import_data
  • Определяет формат файла, преобразует в DataFrame (если нужно).
  • Сопоставляет коды иерархии с внутренними id через mapping.
  • Валидирует структуру и значения.
  • Записывает данные в таблицу фактов через ORM и bulk-операции.
  • При execute_triggers=True запускает связанные триггеры после успешного импорта.

  • В случае ошибок формирует подробный отчёт (ImportResult).

  • Вспомогательные функции:

  • df_to_facts — преобразует DataFrame в структуру для записи фактов.
  • import_df — выполняет запись фактов в базу.

  • get_df — универсальный загрузчик данных из файла/DataFrame.

  • Все операции логируются, результаты фиксируются в журнале импортов (модель ImportResult).

Запуск триггеров при импорте

  • Параметр execute_triggers (по умолчанию False) позволяет запускать связанные триггеры после успешного импорта данных.
  • Триггеры выполняются для всех мер параметра, которые имеют связанные триггеры с auto_run=True.
  • Выполнение триггеров происходит после записи данных, но до финального сохранения изменений.
  • Используется тот же механизм, что и при корректировке данных через fact_manager.run_scripts().
  • Параметр trigger_mode позволяет выбрать режим запуска триггеров:
  • 'facts' - запуск триггеров от фактов (перебирает каждое измененное измерение отдельно)
  • 'revision' - запуск триггеров от ревизий (собирает все измененные измерения в набор)
  • None (по умолчанию) - использует системную настройку TRIGGER_BY_FACTS

Примеры использования:

# Импорт без триггеров (по умолчанию)
import_data(data="facts.csv", parameter="demand_plan_tech_week")

# Импорт с запуском триггеров (использует системную настройку)
import_data(data="facts.csv", parameter="demand_plan_tech_week", execute_triggers=True)

# Импорт с триггерами от фактов
import_data(data="facts.csv", parameter="demand_plan_tech_week", execute_triggers=True, trigger_mode='facts')

# Импорт с триггерами от ревизий
import_data(data="facts.csv", parameter="demand_plan_tech_week", execute_triggers=True, trigger_mode='revision')

Management команда: 

# Импорт без триггеров
python manage.py import_data parameter_key file.csv

# Импорт с триггерами (использует системную настройку)
python manage.py import_data parameter_key file.csv --execute-triggers

# Импорт с триггерами от фактов
python manage.py import_data parameter_key file.csv --execute-triggers --trigger-mode facts

# Импорт с триггерами от ревизий
python manage.py import_data parameter_key file.csv --execute-triggers --trigger-mode revision

Алгоритмы и структуры данных

  • Для сопоставления кодов используется DataFrame с mapping-таблицами по каждому измерению.
  • Bulk-операции выполняются через pandas и Django ORM.
  • Ошибки и некорректные строки не блокируют импорт остальных данных (если не задано строгое поведение).

Примеры кода

Импорт из файла: 

import_data(data="facts.xlsx", parameter="demand_plan_tech_week", source_file_type="xlsx")

Импорт из DataFrame: 

import_data(data=df, parameter="demand_plan_tech_week")

Импорт с триггерами: 

# Использует системную настройку TRIGGER_BY_FACTS
import_data(data="facts.csv", parameter="demand_plan_tech_week", execute_triggers=True)

# Принудительно использует режим от фактов
import_data(data="facts.csv", parameter="demand_plan_tech_week", execute_triggers=True, trigger_mode='facts')

# Принудительно использует режим от ревизий
import_data(data="facts.csv", parameter="demand_plan_tech_week", execute_triggers=True, trigger_mode='revision')

Импорт с дополнительными параметрами: 

import_data(
    data="facts.csv", 
    parameter="demand_plan_tech_week",
    execute_triggers=True,
    ignore_errors=True,
    flush=False
)

Ограничения и best practices

  • Не используйте DataFrame для больших объёмов данных — переходите на SQL и прямой импорт из CSV.
  • Всегда проверяйте структуру файла и коды иерархии перед импортом.
  • Для тестов и отладки используйте отдельные приложения с тестовыми данными.
  • Используйте execute_triggers=True только когда необходимо автоматически обновить связанные данные после импорта.
  • Триггеры могут значительно увеличить время выполнения импорта, особенно для больших объёмов данных.

Ссылки