Практические сценарии
Типичные задачи при работе с репозиторием метрик и способы их решения с помощью 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 \{#ctrl-c-dlya-ostanovki-watch}
trisigma sl compile --source events --output final_events.sql
Теперь у тебя есть финальный SQL для проверки или использования в запросах.
Вариант 2: Ручная компиляция
Если не хочешь использовать watch режим:
# 1. Отредактируй файл \{#1-otredaktiruy-fayl}
vim sources/sql/events.sql
# 2. Скомпилируй \{#2-skompiliruy}
trisigma sl compile --source events
# 3. Повтори если нужно \{#3-povtori-esli-nuzhno}
Сценарий 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 для нового источника
# Узнай название нового источника \{#uznay-nazvanie-novogo-istochnika}
trisigma sl list-sources | grep -i "new"
# Скомпилируй \{#skompiliruy}
trisigma sl compile --source new_source
Шаг 4: Оставь комментарий
Если всё ОК. оставь ревью в PR.
Если есть проблемы. поделись результатами валидации с коллегой.
Сценарий 5: Пакетная генерация SQL для всех источников
Нужно сгенерировать SQL для всех источников и сохранить в файлы.
Скрипт
Создай generate_all.sh:
#!/bin/bash
# Получи список всех источников \{#poluchi-spisok-vseh-istochnikov}
sources=$(trisigma sl list-sources | awk 'NR>3 && NF>1 {print $2}')
# Создай директорию для SQL \{#sozday-direktoriyu-dlya-sql}
mkdir -p generated_sql
# Для каждого источника сгенерируй SQL \{#dlya-kazhdogo-istochnika-sgeneriruy-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
Командный режим
# Посмотри источники \{#posmotri-istochniki}
trisigma sl list-sources
# Посмотри дименшены \{#posmotri-dimensheny}
trisigma sl list-dimensions
# Посмотри метрики \{#posmotri-metriki}
trisigma sl list-metrics
# Проверь структуру \{#prover-strukturu}
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
Сохранение в разные файлы
# Для каждой гранулярности — отдельный файл \{#dlya-kazhdoy-granulyarnosti-otdel-nyy-fayl}
for gran in day week month; do
trisigma sl compile --source events \
--granularity "$gran" \
--output "events_${gran}.sql"
done
Сценарий 9: Работа с несколькими репозиториями
У тебя есть несколько репозиториев метрик (например, для разных проектов).
Переключение между репозиториями
# Способ 1: Переинициализация CLI \{#sposob-1-pereinitsializatsiya-cli}
cd ~/projects/repo1
trisigma init
cd ~/projects/repo2
trisigma init
# Способ 2: Несколько конфигураций \{#sposob-2-neskol-ko-konfiguratsiy}
# Создай алиасы для разных репозиториев \{#sozday-aliasy-dlya-raznyh-repozitoriev}
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. Комбинируй команды
# Валидация и компиляция \{#validatsiya-i-kompilyatsiya}
trisigma sl validate && trisigma sl compile -s events
# Валидация, коммит, публикация \{#validatsiya-kommit-publikatsiya}
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