Enrichments (обогащения)

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

Система enrichments добавляет колонки двумя способами:

1. Используйте табличные обогащения (Enrichments) для выполнения LEFT JOIN с внешними таблицами.
2. Добавляйте вычисляемые поля (Calculated fields) через скалярные SQL-выражения.

Зачем?

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

Система обогащений централизует эту бизнес-логику, позволяя:

1. Переиспользуйте SQL-код в любых источниках без дублирования.
2. Добавляйте новые разрезы и поля для метрик в ускоренном режиме.
3. Оптимизируйте вычисления: система не выполняет JOIN, если данные не требуются в конкретной задаче.

Без enrichments:

-- Source A
SELECT e.*, bs.buyer_segment
FROM events e LEFT JOIN buyer_segments bs ON e.cookie_id = bs.cookie_id

-- Source B (тот же JOIN продублирован)
SELECT c.*, bs.buyer_segment
FROM clicks c LEFT JOIN buyer_segments bs ON c.cookie_id = bs.cookie_id

С enrichments:

# enrichments/buyer_segment.yaml - описали один раз
buyer_segment_cookie:
  sql: SELECT cookie_id, buyer_segment FROM dma.v_buyer_segments
  join_key: [cookie_id]

Обогащение будет доступно автоматически во всех источниках с cookie_id.

Табличные Enrichments

Добавление колонок через LEFT JOIN с внешними таблицами.

Структура

enrichment_name:
  sql: |
    SELECT join_key, additional_columns
    FROM table
    WHERE {{ pushdown_filter(key='key') }}
        and event_date between :first_date and :last_date
  join_key: [columns]
  default_values: # Опционально
    column: value

Ключевые механизмы

1. Автоматическое применение и цепочки

Enrichment применяется автоматически, если в source или других enrichments есть все колонки из join_key:

buyer_segment_cookie:
  join_key: [cookie_id, event_date] # Применится если есть cookie_id и event_date

Цепочки enrichments:

Enrichments могут использовать колонки друг друга. Система автоматически определяет порядок через граф зависимостей:

# enrichments/user_profile.yaml
user_profile:
  sql: SELECT user_id, region_id FROM ...
  join_key: [user_id]

# enrichments/region_info.yaml
region_info:
  sql: SELECT region_id, region_name FROM ... # Использует region_id из user_profile
  join_key: [region_id]

Порядок джоинов определяется автоматически: сначала user_profile, затем region_info.

2. Pushdown Filter

Макрос для оптимизации. добавляет фильтр внутрь запроса enrichment по уникальным значениям из source:

WHERE {{ pushdown_filter(cookie_id='cookie_id') }}

Генерирует:

WHERE cookie_id IN (SELECT DISTINCT cookie_id FROM source_data WHERE cookie_id IS NOT NULL)

Оптимизация уменьшает объем данных в JOIN в правой таблице, что благосклонно сказывается на времени выполнения и потребляемой памяти.

Синтаксис:

# Один ключ
WHERE {{ pushdown_filter(cookie_id='cookie_id') }}

# Несколько ключей
WHERE {{ pushdown_filter(cookie_id='cookie_id', user_id='user_id') }}

Имя аргумента - это называние поля из join_key, а значение - это колонка, которая существует в контексте sql-запроса.

3. Default Values

Заполняет NULL через COALESCE:

traffic_source_cookie:
  sql: SELECT cookie_id, source_name, is_paid FROM ...
  join_key: [cookie_id]
  default_values:
    source_name: "organic"
    is_paid: false

4. Параметр гранулярности

Enrichment может зависеть от гранулярности расчета :granularity. Например, для расчетов m42 с месячной гранулярностью.

weekly_user_activity:
  sql: |
    SELECT
      user_id,
      DATE_TRUNC(:granularity, event_date) as metric_date,
      AVG(activity_score) as avg_activity
    FROM dma.user_activity
    WHERE {{ pushdown_filter(user_id='user_id') }}
    GROUP BY user_id, DATE_TRUNC(:granularity, event_date)
  join_key: [user_id, metric_date]

Система подставит правильное значение гранулярности ('day', 'week', 'month') в зависимости от требований расчета.

Если вы используете параметр гранулярности, колонка с датой должна называться metric_date — это зарезервированное имя для таких целей.

Best Practices для табличных enrichments

1. Используйте макрос pushdown_filter для оптимизации запросов к большим таблицам.
2. Выполняйте фильтрацию по датам с помощью условия AND event_date BETWEEN :first_date AND :last_date.
3. Всегда проверяйте уникальность результатов SQL по ключу join_key для исключения дублирования данных.

Calculated Fields

Добавление колонок через скалярные SQL выражения, вычисляемые на лету из существующих полей.

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

Разрешено:

1. Арифметика, CASE, COALESCE, функции дат и строк

❌ Запрещено:

1. Агрегации (SUM, COUNT, AVG и т.д.)
2. Оконные функции (ROW_NUMBER, RANK и т.д.)

Зачем?

Calculated fields решают две задачи:

Вы можете объединять поля из разных обогащений, когда нужно составить новое поле на их основе.

Когда нужно составить новое поле, используя поля из разных обогащений:

# enrichments/infmquery.yaml
logical_category:
  sql: SELECT logcat_id, logical_category_id as logical_category_id_logcat FROM ...
  join_key: [logcat_id]

microcategory:
  sql: SELECT microcat_id, logical_category_id as logical_category_id_microcat FROM ...
  join_key: [microcat_id]

calculated_fields:
  # Объединяем в единое поле
  logical_category_id: coalesce(logical_category_id_logcat, logical_category_id_microcat)
  vertical_id: coalesce(vertical_id_logcat, vertical_id_microcat)

Теперь logical_category_id можно использовать:

1. В metrics как обычное поле
2. В других enrichments как join_key
3. В dimensions

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

Вместо дублирования вычислений в каждой метрике:

item_attr_log:
  sql: SELECT item_id, event_date, sort_time, start_time, price FROM ...
  join_key: [item_id, event_date]

calculated_fields:
  # Один раз описали вычисление
  item_age_hours: date_diff('hour', sort_time, event_datetime)
  price_category: case
    when price >= 100000 then 'expensive'
    when price >= 10000 then 'medium'
    else 'cheap'
    end

Базовый синтаксис

# В YAML файле enrichment или source
calculated_fields:
  field_name: "SQL выражение"

Пример:

item_attr_log:
  sql: |
    SELECT item_id, event_date, sort_time, start_time, price, event_datetime
    FROM dma.item_attr_log
    WHERE {{ pushdown_filter(item_id='item_id') }}
  join_key: [item_id, event_date]

calculated_fields:
  item_age_hours: date_diff('hour', sort_time, event_datetime)
  item_start_hours: date_diff('hour', start_time, event_datetime)

Многострочные выражения

CASE выражения:

calculated_fields:
  price_bin: |
    case
    when price >= 5000000 then 5000000
    when price >= 3000000 then 3000000
    when price >= 1000000 then 1000000
    when price >= 500000 then 500000
    when price >= 100000 then 100000
    when price >= 10000 then 10000
    when price >= 0 then 0
    end

Цепочки приоритетов (Fallback)

Несколько выражений для одного поля с приоритетом:

calculated_fields:
  user_segment_market:
    - coalesce(user_segment_market_joined, user_segment_market_default) # Приоритет 1
    - user_segment_market_joined # Приоритет 2
    - user_segment_market_default # Приоритет 3

Система попытается использовать первое доступное выражение.

Валидация

Разрешено:

1. Алфавит, цифры, подчеркивание, дефис: field_name, field-name, field123
2. Многострочные выражения
3. Зависимости от других calculated fields

Запрещено:

1. Имена, начинающиеся с цифры: 123field
2. Пробелы в именах: field name
3. Циклические зависимости: field_a: field_b, field_b: field_a
4. Самозависимость: field_a: field_a * 2

Порядок резолвинга колонок

Когда в запросе используется колонка, система ищет её в следующем порядке:

1. Поиск в source

Сначала система проверяет наличие колонки в источнике (source). Если поле найдено, оно используется для дальнейших расчетов.

2. Поиск в enrichments

Если колонки нет в source, проверяются enrichments (табличные и calculated) в порядке их определения в YAML файле.

Берётся первый enrichment, у которого:

1. Проверьте наличие нужной колонки в обогащении.
2. Убедитесь, что все колонки из join_key доступны для применения.

3. Зависимости между enrichments

Enrichments могут зависеть друг от друга:

1. Используйте колонки из одного табличного обогащения в другом.
2. Применяйте колонки из табличных обогащений внутри вычисляемых полей.
3. Используйте вычисляемые поля в качестве join_key для табличных обогащений.

Система автоматически определяет порядок применения через граф зависимостей.

Пример:

# Сначала получаем категорию
logical_category:
  sql: SELECT item_id, logical_category_id FROM dma.categories
  join_key: [item_id]

# Calculated field использует колонку из enrichment
calculated_fields:
  is_auto: logical_category_id = 9 # Авто

# Enrichment использует calculated field как join_key
auto_attributes:
  sql: SELECT item_id, brand, model FROM dma.auto_attributes
  join_key: [item_id, is_auto] # Применится только для авто

Валидация:

1. ❌ Циклические зависимости запрещены
2. ❌ Табличный enrichment и calculated field не могут возвращать колонку с одинаковым именем

Работа с CLI

# Проверка применения enrichments
trisigma sl compile --source buyer_stream --dimensions category,region

# Валидация
trisigma sl validate

# Просмотр финального SQL
trisigma sl compile --metrics your_metric --dimensions your_dim

Следующие шаги

1. Изучите раздел Metrics для понимания использования полей в расчетах.
2. Ознакомьтесь с практическим руководством в разделе Workflow.

Подробнее: Концепции → Enrichments