Что такое Jinja при использовании в Apache Superset?

Jinja2 — это шаблонизатор для Python, используемый для генерации динамического SQL за счет встраивания в код запроса переменных, условий и выражений.

Суть его работы заключается в том, что он заменяет часть SQL кода значениями переменных или функций с помощью определенного синтаксиса, который будет описан дальше в статье. После того, как код динамически сгенерировался — он отправляется на сервер базы данных.

Тем самым с помощью использования Jinja мы можем повысить интерактивность своих Dashboards, за счет кастомизации sql в метриках, динамических измерениях и виртуальных датасетах.

Если кратко, то выглядит это примерно так (пока без погружения в детали, картинка с хабра):

Еще один пример с хабра:

На высоком уровне шаблонизация — это возможность добавлять программные возможности к SQL, при этом Jinja действует как мост, позволяющий нам вводить контекст в запросы.

Для чего можно использовать Jinja

Включение Jinja повышает гибкость функциональности фильтра Superset. Вот несколько более конкретных примеров того, для чего можно использовать Jinja:

• Отображение только данных вошедшего в систему пользователя.
• Использование компонента фильтра для фильтрации запроса, когда имя столбца фильтра не соответствует имени в текущем запросе.
• Применение ограничений фильтра через URL-адрес дашборда Superset.
• Для таблиц, содержащих массивы, возможность поиска записей с определенным значением в массиве.
• Возможность применять операторы OR в фильтре для двух разных столбцов (например ‘name’ = “Matthew” OR ‘age’ = 12)
• Персонализированные дашборды.
• Управление доступом к данным с использованием доступа на уровне строк на основе User_ID или Email (использование информации о пользователе в Row Level Security RLS — построчное ограничение доступа на уровне датасета).
• Исследуйте доступ к метаданным Superset по User_ID.

Как работает контекст фильтров и Jinja в Superset

В контексте Jinja состояние фильтра можно менять за счет использования информации:

• Состояние пользователя
  • user_id человека, вошедшего в систему
  • имя пользователя
  • email пользователя
• Состояние URL
  • вы можете добавить параметры в URL-адрес Superset, который можно вставить в ваш запрос (то есть внедрить внутрь url параметры и их значения использовать через Jinja).
  • Например, если у вас есть Dashboard по продажам, а конечный пользователь хочет видеть продажи только в Барселоне:
    • Можно отправить панель мониторинга, где они смогут перейти к фильтру и нажать «Барселона».
    • Отправьте информационную панель с предварительно отфильтрованным URL-адресом с городом в самом параметре URL-адреса, чтобы при загрузке дашборда они могли сразу увидеть то, что хотят.

Немного про синтаксис Jinja

• Выражение {{ ... }}: выражения используются, когда вы хотите вывести строку. Вы можете использовать выражения для ссылки на переменные и вызова макросов.
• Оператор {% ... %}: этот оператор не выводит строку. Он используется для потока управления, например, для настройки for циклов и if (условных) операторов, для установки или изменения переменных или для определения макросов.
• Комментарий {# ... #}: комментарии Jinja используются для предотвращения выполнения текста внутри комментария или вывода строки.

Как активировать работу Jinja в Apache Superset?

Для того, чтобы начать работу с Jinja в Apache Superset, необходимо в файле

superset/docker/pythonpath_dev/superset_config.py

активировать настройку (флаг)

"ENABLE_TEMPLATE_PROCESSING": True

Полный код в конфиг файле выглядит как:

FEATURE_FLAGS = {
    "ALERT_REPORTS": True,
    "DATAPANEL_CLOSED_BY_DEFAULT": True,
    "DASHBOARD_VIRTUALIZATION": True,
    "DASHBOARD_RBAC": True,
    "ENABLE_TEMPLATE_PROCESSING": True,
    "ESCAPE_MARKDOWN_HTML": True,
    "LISTVIEWS_DEFAULT_CARD_VIEW": True,
    "THUMBNAILS": True,
    "DRILL_BY": True,
    "DRILL_TO_DETAIL": True,
    "HORIZONTAL_FILTER_BAR": True,
    "ESTIMATE_QUERY_COST": True,
    "TAGGING_SYSTEM": True,
    "HTML_SANITIZATION": False,
}

Jinja Templates (Шаблоны Джинджа) в Superset

Функциональность Superset «SQL Lab» и «Explore» поддерживает шаблоны Jinja в SQL запросах. Если включено использование шаблонов, код Python можно внедрить в виртуальные наборы данных и в пользовательский SQL в фильтрах и элементах управления метриками в Explore. По умолчанию в контексте Jinja доступны следующие переменные:

• columns: столбцы, по которым группируется запрос.
• filter: фильтры, примененные в запросе
• from_dttm: начальное datetime значение из выбранного временного диапазона (None если не определено)
• to_dttm: конечное datetime значение из выбранного временного диапазона (None если не определено)
• groupby: столбцы, по которым группируется запрос (устарело)
• metrics: агрегированные выражения в запросе
• row_limit: ограничение строки запроса
• row_offset: смещение строки запроса
• table_columns: столбцы, доступные в наборе данных
• time_column: временной столбец запроса (None если не определен)
• time_grain: выбранный временной интервал (None если не определен)

Параметры Jinja вызываются в двойных скобках в запросе и без них в логических блоках.

SELECT *
FROM tbl
WHERE dttm_col > '{{ from_dttm }}' and dttm_col < '{{ to_dttm }}'

SELECT *
FROM tbl
WHERE (
    {% if from_dttm is not none %}
        dttm_col > '{{ from_dttm }}' AND
    {% endif %}
    {% if to_dttm is not none %}
        dttm_col < '{{ to_dttm }}' AND
    {% endif %}
    true
)

JINJA_CONTEXT_ADDONS = {
 '<Template_name>': <function body>,
}

Пример:

JINJA_CONTEXT_ADDONS = {
    'my_new_custom_macro': lambda x: x*2,
}

JINJA_CONTEXT_ADDONS = {
 'tst': lambda x=0, y=0: x * y,
}

{
  "_filters": [
    {
      "col": "action_type",
      "op": "IN",
      "val": ["sell", "buy"]
    }
  ]
}

SELECT action, count(*) as times
FROM logs
WHERE action in {{ filter_values('action_type'))|where_in }}
GROUP BY action

Примечание _filters не сохраняется вместе с набором данных. Он используется только в пользовательском интерфейсе SQL Lab.

CUSTOM_TEMPLATE_PROCESSORS шаблон SQL

Помимо шаблонов Jinja по умолчанию, лаборатория SQL также поддерживает самоопределяемый процессор шаблонов, устанавливая его CUSTOM_TEMPLATE_PROCESSORS в конфигурации расширенного набора.

Значения в этом словаре перезаписывают процессоры шаблонов Jinja по умолчанию для указанного ядра базы данных. В приведенном ниже примере настраивается пользовательский процессор шаблонов presto, который реализует собственную логику обработки шаблона макроса с анализом регулярных выражений. Он использует макрос $ стиля вместо {{ }} стиля в шаблонах Jinja.

При настройке с помощью CUSTOM_TEMPLATE_PROCESSORS шаблон SQL в базе данных presto обрабатывается пользовательским шаблоном, а не шаблоном по умолчанию.

def DATE(
    ts: datetime, day_offset: SupportsInt = 0, hour_offset: SupportsInt = 0
) -> str:
    """Current day as a string."""
    day_offset, hour_offset = int(day_offset), int(hour_offset)
    offset_day = (ts + timedelta(days=day_offset, hours=hour_offset)).date()
    return str(offset_day)

class CustomPrestoTemplateProcessor(PrestoTemplateProcessor):
    """A custom presto template processor."""

    engine = "presto"

    def process_template(self, sql: str, **kwargs) -> str:
        """Processes a sql template with $ style macro using regex."""
        # Add custom macros functions.
        macros = {
            "DATE": partial(DATE, datetime.utcnow())
        }  # type: Dict[str, Any]
        # Update with macros defined in context and kwargs.
        macros.update(self.context)
        macros.update(kwargs)

        def replacer(match):
            """Expand $ style macros with corresponding function calls."""
            macro_name, args_str = match.groups()
            args = [a.strip() for a in args_str.split(",")]
            if args == [""]:
                args = []
            f = macros[macro_name[1:]]
            return f(*args)

        macro_names = ["$" + name for name in macros.keys()]
        pattern = r"(%s)\s*\(([^()]*)\)" % "|".join(map(re.escape, macro_names))
        return re.sub(pattern, replacer, sql)

CUSTOM_TEMPLATE_PROCESSORS = {
    CustomPrestoTemplateProcessor.engine: CustomPrestoTemplateProcessor
}

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

FEATURE_FLAGS = {
    'SQL_VALIDATORS_BY_ENGINE': {
        'presto': 'PrestoDBSQLValidator',
    }
}

Доступные валидаторы и имена можно найти в sql_validators.

Где находится исходный код Jinja Python в репозитории Superset в GitHub

Исходный код шаблонизации Jinja лежит в файле:

superset/superset/jinja_context.py

Я не пробовал, но теоретически сюда можно добавить нестандартный функционал для вызова через функционал Jinja. Но это уже будет нестандартной доработкой Superset, что усложнит обновление на новые версии Superset.

SELECT count(*)
FROM ORDERS
WHERE country_code = '{{ url_param('countrycode') }}'

SELECT count(*)
FROM ORDERS
WHERE country_code = 'ES'

SELECT count(*)
FROM ORDERS
WHERE country_code = 'US'

SELECT action, count(*) as times
FROM logs
WHERE
    action in {{ filter_values('action_type')|where_in }}
GROUP BY action

WITH RECURSIVE
    superiors(employee_id, manager_id, full_name, level, lineage) AS (
    SELECT
        employee_id,
        manager_id,
        full_name,
    1 as level,
    employee_id as lineage
    FROM
        employees
    WHERE
    1=1

    {# Render a blank line #}
    {%- for filter in get_filters('full_name', remove_filter=True) -%}

    {%- if filter.get('op') == 'IN' -%}
        AND
        full_name IN {{ filter.get('val')|where_in }}
    {%- endif -%}

    {%- if filter.get('op') == 'LIKE' -%}
        AND
        full_name LIKE {{ "'" + filter.get('val') + "'" }}
    {%- endif -%}

    {%- endfor -%}
    UNION ALL
        SELECT
            e.employee_id,
            e.manager_id,
            e.full_name,
    s.level + 1 as level,
    s.lineage
        FROM
            employees e,
        superiors s
        WHERE s.manager_id = e.employee_id
    )

    SELECT
    employee_id, manager_id, full_name, level, lineage
    FROM
    superiors
    order by lineage, level

select * from 
{% if my_table %}
  {{my_table}}
{% else %}
  foo
{% endif %}