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

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

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

1. Табличные enrichments. через LEFT JOIN с внешними таблицами
2. Calculated fields. через скалярные SQL выражения

Зачем?

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

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

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

Без 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 - описали один раз \{#enrichments-buyer-segment-yaml-opisali-odin-raz}
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 в правой таблице, что благосклонно сказывается на времени выполнения и потребляемой памяти.

Синтаксис:

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

# Несколько ключей \{#neskol-ko-klyuchey}
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') в зависимости от требований расчета.

Важно! Если используется granularity, то колонка с датой должна называться 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 выражения, вычисляемые на лету из существующих полей.

Важно: Calculated fields могут быть только скалярными выражениями:

Разрешено:

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

❌ Запрещено:

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

Зачем?

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

1. Объединение полей из разных enrichments

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

# 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

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

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

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 \{#v-yaml-fayle-enrichment-ili-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 можно применить (все колонки из join_key доступны)

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

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

1. Табличный enrichment может использовать колонку из другого табличного enrichment
2. Calculated field может использовать колонки из табличных enrichments
3. Табличный enrichment может использовать calculated field как join_key

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

Пример:

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

# Calculated field использует колонку из enrichment \{#calculated-field-ispol-zuet-kolonku-iz-enrichment}
calculated_fields:
  is_auto: logical_category_id = 9 # Авто

# Enrichment использует calculated field как join_key \{#enrichment-ispol-zuet-calculated-field-kak-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 \{#proverka-primeneniya-enrichments}
trisigma sl compile --source buyer_stream --dimensions category,region

# Валидация \{#validatsiya}
trisigma sl validate

# Просмотр финального SQL \{#prosmotr-final-nogo-sql}
trisigma sl compile --metrics your_metric --dimensions your_dim

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

1. Metrics. использование полей из enrichments и calculated fields
2. Workflow. практика создания

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