Практические сценарии#

Типичные задачи при работе с репозиторием метрик и способы их решения с помощью Trisigma CLI.

Предварительные требования#

Все сценарии ниже предполагают что у тебя:

✅ Установлен и настроен Trisigma CLI (см. Настройка)

✅ Склонирован репозиторий метрик:

git clone git@github.com:<your-company>/<your-company>_ab_metrics.git

✅ CLI настроен на этот репозиторий (trisigma init)

Если что-то из этого не выполнено, начни с раздела настройки.

Сценарий 1: Добавление новой метрики#

Ты хочешь добавить новую метрику в репозиторий и убедиться что всё работает корректно.

Шаг 1: Создай ветку для задачи#

cd ~/projects/ab-metrics
trisigma sl task AB-1234 "Добавление метрики revenue"

CLI создаст и переключится на новую ветку.

Шаг 2: Создай файл метрики#

Открой редактор и создай metrics/revenue.yaml:

name: revenue
title: Выручка
type: sum
source: purchases
columns:
  - amount
description: Сумма всех покупок

Шаг 3: Валидируй изменения#

trisigma sl validate

Если есть ошибки — исправь их. Повторяй валидацию пока не увидишь зеленое сообщение об успехе.

С AI-объяснением (если есть ошибки):

trisigma sl validate --ai-explain

Шаг 4: Проверь сгенерированный SQL#

trisigma sl compile --metrics revenue --granularity day

Убедись что SQL корректен.

Шаг 5: Сохрани изменения#

trisigma sl save -m "Добавил метрику revenue"

Шаг 6: Опубликуй#

trisigma sl publish

Создай Pull Request по сгенерированной ссылке!

Итого команд: 5 команд для полного цикла разработки! 🎉

Сценарий 2: Отладка SQL источника#

У тебя есть источник events, но SQL генерируется некорректно.

Вариант 1: Режим watch (рекомендуется)#

Шаг 1: Включи режим watch#

trisigma sl compile --source events --watch

Шаг 2: Открой файл в редакторе#

Открой sources/sql/events.sql в VS Code или другом редакторе.

Шаг 3: Редактируй и сохраняй#

Каждый раз при сохранении файла CLI автоматически валидирует синтаксис, генерирует SQL и показывает результат в терминале. Не нужно переключаться между терминалом и редактором — просто смотри на вывод CLI!

Шаг 4: Сохрани итоговый SQL в файл#

Когда результат тебя устроит:

# Ctrl+C для остановки watch
trisigma sl compile --source events --output final_events.sql

Теперь у тебя есть финальный SQL для проверки или использования в запросах.

Вариант 2: Ручная компиляция#

Если не хочешь использовать watch режим:

# 1. Отредактируй файл
vim sources/sql/events.sql

# 2. Скомпилируй
trisigma sl compile --source events

# 3. Повтори если нужно

Сценарий 3: Проверка изменений перед PR#

Ты внес множество изменений в несколько файлов. Перед созданием PR нужно убедиться что всё корректно.

Шаг 1: Проверь статус#

trisigma sl status

CLI покажет таблицу всех измененных файлов с их статусами.

Шаг 2: Валидация с AI-объяснением#

trisigma sl validate --ai-explain

Если есть ошибки, AI даст подробное объяснение и рекомендации по исправлению.

Шаг 3: Протестируй генерацию SQL для ключевых источников#

trisigma sl compile --source events
trisigma sl compile --source users
trisigma sl compile --metrics revenue,sessions

Убедись что SQL генерируется без ошибок.

Шаг 4: Сохрани и опубликуй#

trisigma sl save -m "Обновил источники и метрики"
trisigma sl publish

Сценарий 4: Быстрая проверка изменений коллеги#

Коллега попросил проверить его изменения в ветке.

Шаг 1: Переключись на ветку#

git fetch origin
git checkout feature/AB-5678-new-source

Шаг 2: Валидируй изменения#

trisigma sl validate

Шаг 3: Проверь SQL для нового источника#

# Узнай название нового источника
trisigma sl list-sources | grep -i "new"

# Скомпилируй
trisigma sl compile --source new_source

Шаг 4: Оставь комментарий#

Если всё ОК — оставь ревью в PR.

Если есть проблемы — поделись результатами валидации с коллегой.

Сценарий 5: Пакетная генерация SQL для всех источников#

Нужно сгенерировать SQL для всех источников и сохранить в файлы.

Скрипт#

Создай generate_all.sh:

#!/bin/bash

# Получи список всех источников
sources=$(trisigma sl list-sources | awk 'NR>3 && NF>1 {print $2}')

# Создай директорию для SQL
mkdir -p generated_sql

# Для каждого источника сгенерируй SQL
for source in $sources; do
  echo "Генерация SQL для: $source"
  trisigma sl compile --source "$source" \
    --output "generated_sql/${source}.sql"
done

echo "✓ Генерация завершена!"
echo "Файлы сохранены в: generated_sql/"

Запусти:

chmod +x generate_all.sh
./generate_all.sh

Сценарий 7: Исследование нового репозитория#

Ты впервые работаешь с репозиторием метрик и хочешь понять его структуру.

Интерактивный режим (рекомендуется)#

trisigma

Используй меню для:

Просмотра списков источников, дименшенов, метрик
Валидации репозитория
Компиляции примеров SQL

Командный режим#

# Посмотри источники
trisigma sl list-sources

# Посмотри дименшены
trisigma sl list-dimensions

# Посмотри метрики
trisigma sl list-metrics

# Проверь структуру
trisigma sl validate

Сценарий 8: Работа с датами и гранулярностью#

Нужно сгенерировать SQL для разных периодов и гранулярностей.

День (day)#

trisigma sl compile --source events \
  --first-date 2025-01-01 \
  --last-date 2025-01-31 \
  --granularity day

Неделя (week)#

trisigma sl compile --source events \
  --first-date 2025-01-01 \
  --last-date 2025-12-31 \
  --granularity week

Месяц (month)#

trisigma sl compile --source events \
  --first-date 2025-01-01 \
  --last-date 2025-12-31 \
  --granularity month

Сохранение в разные файлы#

# Для каждой гранулярности — отдельный файл
for gran in day week month; do
  trisigma sl compile --source events \
    --granularity "$gran" \
    --output "events_${gran}.sql"
done

Сценарий 9: Работа с несколькими репозиториями#

У тебя есть несколько репозиториев метрик (например, для разных проектов).

Переключение между репозиториями#

# Способ 1: Переинициализация CLI
cd ~/projects/repo1
trisigma init

cd ~/projects/repo2
trisigma init

# Способ 2: Несколько конфигураций
# Создай алиасы для разных репозиториев
alias ts-repo1='cd ~/projects/repo1 && trisigma'
alias ts-repo2='cd ~/projects/repo2 && trisigma'

Сценарий 10: Отладка с AI-помощником#

У тебя сложная ошибка валидации и непонятно как её исправить.

Шаг 1: Запусти валидацию с AI#

trisigma sl validate --ai-explain

Шаг 2: Прочитай объяснение#

AI проанализирует ошибки и даст:

Описание проблемы
Причину возникновения
Конкретное решение с примерами кода
Дополнительные рекомендации

Шаг 3: Примени рекомендации#

Исправь код согласно рекомендациям AI.

Шаг 4: Повторная валидация#

trisigma sl validate

Быстрые команды (шпаргалка)#

Задача	Команда
Валидация	`trisigma sl validate`
Валидация с AI	`trisigma sl validate --ai-explain`
Компиляция источника	`trisigma sl compile -s events`
Компиляция метрик	`trisigma sl compile -m revenue,sessions`
Режим watch	`trisigma sl compile -s events --watch`
Список источников	`trisigma sl list-sources`
Список дименшенов	`trisigma sl list-dimensions`
Список метрик	`trisigma sl list-metrics`
Создать ветку	`trisigma sl task AB-1234 "Описание"`
Коммит	`trisigma sl save -m "Сообщение"`
Публикация	`trisigma sl publish`
Статус	`trisigma sl status`
Интерактивный режим	`trisigma`

Советы по эффективной работе#

1. Используй алиасы#

alias tsv='trisigma sl validate'
alias tsc='trisigma sl compile'

2. Комбинируй команды#

# Валидация и компиляция
trisigma sl validate && trisigma sl compile -s events

# Валидация, коммит, публикация
trisigma sl validate && \
  trisigma sl save -m "Описание" && \
  trisigma sl publish

3. Используй режим watch для отладки#

trisigma sl compile -s events --watch

4. Проверяй изменения перед коммитом#

trisigma sl status
trisigma sl validate

5. Используй AI для сложных ошибок#

trisigma sl validate --ai-explain

🏠 Вернуться к содержанию