Перейти к основному содержимому

Основные концепции

Семантический слой состоит из четырех основных компонентов, которые вы настраиваете декларативно в YAML-конфигах, и одного центрального движка, который автоматически генерирует оптимизированный SQL.

Что вы настраиваете:

  1. Настройте источники данных (Sources) для определения SQL-запросов к DWH.
  2. Используйте обогащения (Enrichments) для добавления колонок через LEFT JOIN.
  3. Опишите способы расчета метрик (Metrics) через фильтры, агрегации и отношения.
  4. Определите доступные разрезы (Dimensions) для группировки данных.

Что происходит на стороне Trisigma:

  1. Движок Trisigma Semantic Engine анализирует конфигурации и генерирует SQL.
  2. Обогащения данных (Enrichments) применяются только при необходимости.
  3. SQL-запросы оптимизируются для эффективного выполнения.
  4. Метрики становятся доступны в аналитических отчетах, M42 и витринах данных.

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

Структура репозитория​

Репозиторий ab-metrics имеет следующую структуру папок:

ab-metrics/
├── sources/
│   ├── sql/               # SQL-запросы источников данных
│   │   ├── buyer_stream.sql
│   │   ├── seller_stream.sql
│   │   └── ...
│   └── sources.yaml       # Конфигурация источников с метаданными
│
├── enrichments/           # YAML-файлы с enrichments
│   ├── buyer_segment.yaml
│   ├── traffic_source.yaml
│   └── ...
│
├── metrics/               # YAML-файлы с метриками
│   ├── buyer_stream.yaml
│   ├── conversion.yaml
│   └── ...
│
└── dimensions/
    ├── sql/               # SQL-справочники для dimensions
    │   ├── platform.sql
    │   ├── vertical.sql
    │   └── ...
    └── dimensions.yaml    # Конфигурация dimensions с метаданными

Связи между файлами:

  1. Конфигурация в sources/sources.yaml ссылается на SQL-файлы в sources/sql/ и настройки метрик в metrics/.
  2. Обогащения из enrichments/ применяются к источнику автоматически при совпадении ключа join_key.
  3. Метрики в папке metrics/ используют колонки из источников данных и обогащений.
  4. Разрезы в dimensions/dimensions.yaml ссылаются на SQL-справочники в dimensions/sql/.

Источники данных​

Источник (Source) представляет собой SQL-запрос и метаданные в sources.yaml. Они описывают способ извлечения исходных данных из DWH. Результатом работы является таблица фактов, содержащая события, даты, идентификаторы пользователей и разрезы.

# sources.yaml
buyer_stream:
  sql: buyer_stream
  metric_configs: [buyer_stream]
  connections: [trino]
  participant: { visitor: cookie_id, user: user_id }
  dtm: event_date
-- sources/sql/buyer_stream.sql
SELECT cookie_id, event_date, eid, platform_id, events_count
FROM dwh.events
WHERE event_date BETWEEN :first_date AND :last_date

Обогащение данных​

Enrichments добавляют новые колонки к source двумя способами:

1. Табличные enrichments (LEFT JOIN)

Обогащают данные через JOIN с другой таблицей. Например, добавление сегмента покупателя или источника трафика.

# enrichments/buyer_segment.yaml
buyer_segment_cookie:
  sql: |
    SELECT cookie_id, event_date, buyer_segment
    FROM dma.v_buyer_segments
    WHERE {{ pushdown_filter(cookie_id='cookie_id') }}
  join_key: [cookie_id, event_date]

2. Calculated fields (вычисляемые поля)

Создают новые колонки на основе существующих через SQL-выражения, без JOIN.

# enrichments/calculated_fields.yaml
calculated_fields:
  is_mobile: "platform_id IN (4, 14)"
  price_bucket: |
    CASE
      WHEN price < 1000 THEN 'low'
      WHEN price < 10000 THEN 'medium'
      ELSE 'high'
    END

Автоматическое применение:

Никаких явных связей настраивать не нужно. Enrichment становится доступен автоматически, если:

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

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

Обогащенный источник​

Вы настраиваете источники и обогащения, а обогащенный источник (Enriched Source) формируется автоматически. Обогащения добавляются в SQL только при использовании соответствующих колонок. Это исключает избыточные JOIN-соединения.

-- Enriched Source (концептуально)
WITH enriched AS (
  SELECT
    s.*,                        -- Исходные колонки
    bs.buyer_segment            -- Добавленная колонка (только если нужна)
  FROM source s
  LEFT JOIN buyer_segments bs   -- Только если buyer_segment используется
    ON s.cookie_id = bs.cookie_id
)
SELECT ... FROM enriched        -- Metrics и Dimensions читают отсюда

Логика расчета​

Metrics описывают бизнес-логику метрик декларативно через фильтры. Они читают данные из Enriched Source и могут использовать как исходные колонки из source, так и добавленные колонки из enrichments.

Три типа метрик образуют иерархию: Counter (базовый подсчет) → Uniq (уникальные значения) → Ratio (производные метрики).

metric.counter:
  purchases: { filter: [eid: 500] }
  seeker_purchases: { filter: [buyer_segment: "seeker", eid: 500] } # Добавленная колонка

metric.uniq:
  buyers: { counter: purchases, key: [cookie_id] }

metric.ratio:
  conversion: { num: buyers, den: daily_active_users }

Разрезы данных​

Dimensions определяют разрезы для группировки метрик в A/B-тестах и M42. Как и метрики, они читают из Enriched Source и могут использовать любые колонки. и исходные из source, и добавленные из enrichments.

platform: # Исходная колонка (platform_id из source)
  has_id: true
  description: "Платформа (mobile, desktop)"

buyer_segment: # Добавленная колонка (из enrichment)
  has_id: false
  description: "Сегмент покупателя"

Генерация SQL​

Trisigma Semantic Engine является центральным компонентом системы. На основе ваших конфигураций движок формирует оптимизированный SQL-код.

Примеры задач:

Adhoc Queries. разовые запросы для анализа метрик. Используется для быстрой проверки данных и экспериментов.

trisigma sl compile --metrics conversion --dimensions platform

Experiment Reports. отчеты по A/B-тестам. Engine генерирует SQL для расчета метрик по группам эксперимента с учетом статистической значимости.

M42. многомерные кубы для срезов данных. Формируются предрасчитанные данные в кубах дименшенов для быстрого анализа.

Datamarts/Datasets. витрины данных для регулярного использования. Engine создает материализованные денормализованные таблицы с предрасчитанными метриками для любых целей.

Пример: конверсия в покупку​

Рассмотрим как описать конверсию из просмотров в покупки.

1. Source. таблица фактов​

Source извлекает события пользователей с идентификаторами и типами событий:

SELECT cookie_id, event_date, eid, platform_id
FROM dwh.events
WHERE event_date BETWEEN :first_date AND :last_date

2. Enrichment. добавляем сегмент​

Enrichment добавляет колонку buyer_segment:

buyer_segment_cookie:
  sql: SELECT cookie_id, event_date, buyer_segment FROM ...
  join_key: [cookie_id, event_date]

3. Metrics. логика расчета​

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

metric.counter:
  views: { filter: [eid: 303] }
  purchases: { filter: [eid: 500] }

metric.uniq:
  viewers: { counter: views, key: [cookie_id] }
  buyers: { counter: purchases, key: [cookie_id] }

metric.ratio:
  conversion: { num: buyers, den: viewers }

4. Как это работает​

Без enrichment (колонка buyer_segment не используется):

SELECT
  COUNT(DISTINCT CASE WHEN eid = 303 THEN cookie_id END) as viewers,
  COUNT(DISTINCT CASE WHEN eid = 500 THEN cookie_id END) as buyers
FROM source
-- Нет LEFT JOIN с enrichment

С enrichment (группировка по buyer_segment):

WITH enriched AS (
  SELECT s.*, e.buyer_segment
  FROM source s
  LEFT JOIN buyer_segment_enrichment e
    ON s.cookie_id = e.cookie_id
    AND s.event_date = e.event_date
)
SELECT
  buyer_segment,
  COUNT(DISTINCT CASE WHEN eid = 303 THEN cookie_id END) as viewers,
  COUNT(DISTINCT CASE WHEN eid = 500 THEN cookie_id END) as buyers
FROM enriched
GROUP BY buyer_segment

Enrichment с buyer_segment применился автоматически, потому что колонка используется в GROUP BY. (Это упрощенный пример, реальный SQL сложнее).

Для дальнейшего изучения​

  1. Прочитайте подробнее про источники данных в разделе Sources.
  2. Изучите методы автоматического обогащения в Enrichments.
  3. Настройте логику расчета в разделе Metrics.
  4. Выберите разрезы для анализа в Dimensions.
  5. Ознакомьтесь с практикой работы в Workflow.