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

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

Для базовой информации и инструкций по 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 только когда необходимо автоматически обновить связанные данные после импорта.
  • Триггеры могут значительно увеличить время выполнения импорта, особенно для больших объёмов данных.

Экспорт данных из параметров

Экспорт данных позволяет выгрузить значения показателей (фактов) из параметров в файлы CSV или Excel (XLSX).

Базовое использование

Используется функция export_data из модуля core.parameters.libs.import_data.

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

from planiqum.core.parameters.libs.import_data import export_data

# Экспорт в CSV
export_data(parameter="demand_plan_tech_week", path="export.csv")

# Экспорт в Excel
export_data(parameter="demand_plan_tech_week", path="export.xlsx", data_type="xlsx")

Экспорт с использованием PostgreSQL COPY (PLQM-1193)

Для больших объёмов данных доступен более эффективный метод экспорта через PostgreSQL COPY TO STDOUT, который не загружает все данные в память.

Активация через переменную окружения: 

USE_SQL_COPY_FOR_EXPORT=True

Или через параметр функции: 

export_data(
    parameter="demand_plan_tech_week",
    path="export.csv",
    use_sql_copy=True
)

Важно: Метод use_sql_copy=True работает только если: - data_type="csv" (или не указан, т.к. по умолчанию CSV) - columns=None (без агрегации по колонкам) - uom=None (без конвертации единиц измерения) - currency=None (без конвертации валют)

Если условия не выполнены, используется стандартный метод через pandas to_csv.

Преимущества использования PostgreSQL COPY: - Не загружает все данные в память - Быстрее для больших объёмов данных - Использует потоковую передачу данных напрямую из базы данных

Логирование: При использовании copy_to_csv в логах будет видно: - INFO: начало экспорта с указанием параметра и пути - DEBUG: длина SQL-запроса перед выполнением - INFO: успешное завершение экспорта

Параметры функции export_data

  • parameter — ключ параметра, id или объект Parameter
  • measures — список мер для экспорта (по умолчанию все меры)
  • columns — словарь с измерениями и уровнями для группировки
  • filter_ — фильтр для ограничения данных
  • path — путь к файлу экспорта (по умолчанию {parameter.key}.csv в директории экспорта)
  • data_type — тип файла: "csv" или "xlsx" (по умолчанию "csv")
  • use_sql_copy — использовать PostgreSQL COPY для экспорта (по умолчанию False или значение из USE_SQL_COPY_FOR_EXPORT)
  • export_params — дополнительные параметры для pandas to_csv или to_excel

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

# Простой экспорт
export_data(parameter="demand_plan_tech_week")

# Экспорт с фильтром
from planiqum.core.filters.libs.filter import Filter
filter_ = Filter()  # ваш фильтр
export_data(
    parameter="demand_plan_tech_week",
    filter_=filter_,
    path="filtered_export.csv"
)

# Экспорт конкретных мер
export_data(
    parameter="demand_plan_tech_week",
    measures=["qty", "revenue"],
    path="measures_export.csv"
)

# Экспорт с использованием PostgreSQL COPY
export_data(
    parameter="demand_plan_tech_week",
    path="export.csv",
    use_sql_copy=True
)

# Экспорт с настройками разделителя
export_data(
    parameter="demand_plan_tech_week",
    path="export.csv",
    export_params={"sep": ";"},  # разделитель точка с запятой
    use_sql_copy=True
)

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

  • Основная функция: export_data из модуля core.parameters.libs.import_data
  • При use_sql_copy=True и выполнении условий использует функцию copy_to_csv из core.libs.db
  • copy_to_csv использует PostgreSQL COPY ... TO STDOUT для потокового экспорта

  • В остальных случаях использует стандартный метод через pandas to_csv или to_excel

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

  • get_param_df — получает данные параметра в виде DataFrame
  • copy_to_csv — выполняет экспорт через PostgreSQL COPY TO STDOUT
  • DataQuery — строит SQL-запрос для экспорта с правильными JOIN для читаемых полей

Использование в скриптах

Экспорт доступен как скрипт "00.2.2 Экспорт данных - Параметр" в интерфейсе скриптов.

# В скрипте можно использовать те же параметры
export_data(
    parameter="my_parameter_key",
    path="export.csv",
    use_sql_copy=True
)

Ссылки

Важно: описанные настройки и сценарии могут отличаться в вашей инсталляции Planiqum
За уточнениями и методологической поддержкой обращайтесь в компанию ЮНИК СОФТ

— © 2025 ООО «ЮНИК СОФТ». Planiqum — платформа интегрированного бизнес-планирования. www.uniquesoft.ru