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

Метаданные etl-блока

В метаданных etl-блока описываются основные характеристики блока и приводится список его параметров. Указываются в файле block_meta.json в json-формате.

block_meta.json
{
  "uid": "example_sql",
  "name": "JSON блок",
  "description": "Выполняет SQL выражение над вложенными объектами",
  "author": "AnalyticWorkspace",
  "version": "1.0",
  "updated_at": "2023-11-05 11:00:00+00:00",
  "params": [{
    "code": "sql",
    "name": "SQL выражение",
    "type": "sql_text",
    "description": "Текст SQL-запроса. Например, SELECT * FROM child",
    "required": true,
    "mult": false,
    "extra": {
      "height": 240
    } 
  }]
}

Метаданные блока задаются двумя группами значений:

  • Описание блока. Содержат всю необходимую информацию для корректной регистрации блока в системе: уникальный идентификатор, название, версию и т.п.

  • Параметры блока. Описывают необходимую входную информацию для работы блока и способ её представления в форме настройки блока при создании модели.

Описание блока

Название Обязательно Описание
uid да Уникальный идентификатор блока. В одном экземпляре AW не может существовать двух разных блоков с одним и тем же значением uid. Идентификаторы блоков, включенных в дистрибутив AW, имеют префикс aw_
name да Название блока
description да Описание блока. Отображается на форме заполнения параметров блока и в краткой форме дает понять пользователю, для чего предназначен данный блок.
author да Строка с указанием автора блока. У всех блоков, включенных в дистрибутив AW, в данном поле указано "Analytic Workspace".
version да Строка с указанием версии блока. Формат значения: major.minor (мажорная и минорная версии). Предполагается, что все версии блока, у которых совпадает major-компонента являются совместимыми друг с другом. Компонента minor меняется при исправлении ошибок или при внесении улучшений в работу блока, которые обратно совместимы с существующими блоками в моделях. AW автоматически применяет более новые версии блока с одной и той же major-версией.
updated_at да Строка с временной меткой последнего изменения блока. Указывается в формате "YYYY-MM-DD HH-mm-ss+00:00"

Параметры блока

Существует три типа объектов, которые указываются в списке params у метаданных etl-блока:

  • Параметр блока задает значение, которое нужно получить от пользователя при настройке блока и передать далее в функции построения схемы и данных.
  • Группа параметров позволяет объединить c смежные параметры в некоторые логическую группу для представления в пользовательском интерфейсе.
  • Действие указывает на то, какие операции пользователь может выполнить внутри формы ввода параметров (например, автоматически заполнить ряд полей при настройке блока).

Параметр

Параметр etl-блока описывается полями:

Название Обязательно Описание
code + Код параметра. Значение должно быть уникальным в пределах одного блока
name + Название параметра. Отображается в интерфейсе в качестве заголовка блока
type + Тип значения параметра: string, number, float, bool, date и др. (см. список ниже )
description Описание блока. Отображается в интерфейсе рядом с названием поля в виде всплывающей подсказки
required + Является ли данный параметр обязательным для заполнения (true/false)
mult + Является ли данный параметр множественным (true/false). Множественные параметры позволяют вводить несколько однотипных значений подряд и передаются в функции блока в виде списка значений, а не как одиночное значение
domain Область допустимых значений параметра. Позволяет для некоторых типов параметров ограничить список допустимых значений для ввода
extra Дополнительные опции, влияющие на отображение поля ввода параметра
Пример объявления параметра в block_meta.json 
{
  # значения описания: uid, name, ..
  "params": [{
    "code": "column_name",
    "name": "Название столбца модели",
    "type": "string",
    "description": "Так будет называться новое поле в модели",
    "required": true,
    "mult": false
  }]
}

Тип параметра

Принимает одно из следующих значений:

Название Тип данных в params Поле воода
string Cтрока Однострочное поле ввода текста <input type="text">
text Строка Многострочное поле ввода текста <textarea>
password Строка Поле ввода пароля <input type="password">
sql_text Строка Многострочный текст с подсветкой синтаксиса и подсказками для SQL-выражений
number Целое Поле ввода числа <input type="number">
float Дробное Поле ввода числа <input type="number">
bool Булево Чекбокс <input type="checkbox">
date Строка с датой в формате DD.MM.YYYY Поле выбора даты из календаря
datetime Строка с датой/временем в формате DD.MM.YYYY HH:MM Поле выбора даты из календаря с возможностью указания времени (часы + минуты)
select id выбранного объекта (подробнее) Отображается на форме в виде выпадающего списка.

Обязательность

Обязательный параметр отмечается флажком required: true. Для них на форме ввода параметров блока включается клиентская валидация.

Внимание

Проверка обязательности параметра выполняется только в пользовательском интерфейсе. На сервере такой проверки нет.

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

Поэтому, при обработке параметров в коде блока необходимо всегда проверять все нужные значения на непустоту.

Множественность

Для параметров со значением mult: true на форме настройки блоков появляется возможность указания нескольких значений.

block_meta.json
{
  // ...,
  "params": [{

  }]
}

Опции

Параметры специальных типов

select

Список возможных вариантов выбора значения указывается в параметре domain. Ожидается, что здесь будет указан список объектов с атрибутами id и name. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "code": "step_type",
  "name": "Тип шага",
  "type": "select",
  "required": true,
  "mult": false,
  "domain": [
    {"id": "second", "name": "Секунда"},
    {"id": "minute", "name": "Минута"},
    {"id": "hour", "name": "Час"},
    {"id": "day", "name": "День"},
    {"id": "week", "name": "Неделя"},
    {"id": "month", "name": "Месяц"},
    {"id": "year", "name": "Год"}
  ]
}

Значение name будет показано в выпадающем списке, а id будет передано в params при запуске функций блока.

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

1
2
3
4
5
6
def block_data(params):
    """ """
    # ...
    if params['step_type'] == 'week':
        print('Пользователь выбрал недельный тип шага')
    # ...
sql_text

Для параметра с типом sql_text на форме настройки блока будет использовано специальное поле с подсветкой синтаксиса и подсказками. Кроме стандартных для SQL выражений ключевых слов, в список подсказок добавляются названия вложенных объектов и их полей.

В функции модуля блока значение такого параметра будет передано обычной строкой.

Группы параметров

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

Действия

Позволяет разместить на форме ввода параметров кнопку для выполнения действия с текущими значениями параметров.

Действие описывается следующими параметрами:

Название Обязательно Описание
code + Код действия. Должно быть уникальным в пределах одного etl-блока. Используется для связывания с функцией-обработчиком действия в block_code.py
name + Название действия. Будет показано на форме ввода параметров в надписи к кнопке
type + Тип действия. В текущей версии должно содержать значение action
description Описание действия
action + Идентификатор действия. В текущей версии должно совпадать со значением code
extra Словарь с дополнительными опциями действия

Пример описания действия:

1
2
3
4
5
6
{
  "code": "autofill_schema",
  "name": "Заполнить схему JSON автоматически",
  "type": "action",
  "action": "autofill_schema"
}

При нажатии на кнопку происходит следующее:

  1. Все указанные пользователем значения параметров на форме настройки etl-блока отправляются на сервер;
  2. Серверный механизм находит в модуле etl-блока block_code.py функцию-обработчик действия и вызывает её. Эта функция должна называться block_action_{% код действия%}();
  3. В результате выполнения возвращает

Передача значений параметров в функции модуля

Указанные пользователем на форме настройки блока параметры передаются в функции модуля блока в аргументе params.

block_code.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
def block_schema(params):
    """ Функция построения схемы """
    ...


def block_data(params):
    """ Функция обработки данных """
    ...


def block_action_autofill(params):
    """ Обработчик действия"""
    ...

Объект в аргументе params является словарем. Ключами словаря являются коды параметров и групп самого верхнего уровня. Значения с формы редактирования указаны в словаре по правилам из следующших подразделов

Параметр

Передается значение, введенное пользователем на форме редактирования.

block_meta.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  ...
  "params": [{
    "code": "sql",
    "name": "SQL выражение",
    "type": "string",
    "multiple": false
    ...
  }]
}

block_code.py
1
2
3
4
5
def block_data(params):
    print(params['sql_text']) 

# Распечатает:
#   select * from transactions

Множественный параметр

Множественные параметры передаются списком значений, введенных пользователем на форме редактирования.

block_meta.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  ...
  "params": [{
    "code": "lvl_field",
    "name": "Уровень иерархии",
    "type": "string",
    "multiple": true,
    ...
  }]
}

block_code.json
1
2
3
4
5
6
7
def block_data(params):
    for lvl in params['lvl_fields']:  # (1)!
        print(lvl)

# Распечатает две строки:
#   level_region
#   level_city
  1. Для параметра с mult: true в params находится список значений.

Внутригрупповой параметр

Параметры внутри группы доступны через двойное индексирование params['group_code']['param_code']: сначала из params достаются вложенные в группу параметры по коду группы, а затем применяется ключ с кодом параметра.

block_meta.json
{
  // ...,
  "params": [{
  "code": "period",
  "name": "Период генерации серии",
  "type": "group",
  "mult": false,
  "params": [
    {
      "code": "start",
      "name": "Начало серии",
      "type": "datetime",
      // ...
    },
    {
      "code": "end",
      "name": "Окончание серии",
      "type": "datetime",
      // ...
    }
  ]
}]

block_code.py
1
2
3
4
5
6
7
def block_data(params):
    print(params['period']['start'])
    print(params['period']['end'])

# Распечатает:
#   01.11.2024
#   30.11.2024

Множественный внутригрупповой параметр

Множественные параметры внутри группы хранятся в params списком объектов, который доступны по ключу группы.

block_meta.json
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  // ...
  "params": [{
    "code": "calc_fields",
    "name": "Вычисляемое поле",
    "type": "group",
    "mult": true,
    "params": [{
      "code": "field_name",
      "name": "Название",
      "type": "string",
      // ...
    }, {
      "code": "sql",
      "name": "SQL выражение",
      "type": "sql_text",
      // ...
    }]
  }]
}

block_code.py
1
2
3
4
5
6
7
8
9
def block_data(params):
    for field in params['calc_fields']:  # (1)!
        field_name = field['field_name']
        field_sql = field['sql']
        print(f"{field_name}: {field_sql}")

# Распечатает:
#   id_no_null: case when id is null then 0 else id end
#   id_x100: 100 * id
  1. Для группы с mult: true в params находится список объектов.