Pisanie modeli#

Model jest plikiem .sql zawierającym jedną instrukcję select. Supernova materializuje go jako tabelę w jeziorze i przebudowuje co 4 godziny w kolejności zależności ze wszystkimi innymi modelami. Nie ma pliku konfiguracyjnego ani osobnego harmonogramu — całą definicją jest SQL.

Gdzie znajdują się modele#

Modele są plikami w katalogu models/ repozytorium danych. Edytuj je na stronie Pliki albo sklonuj repozytorium i użyj własnego edytora — w obu przypadkach jest to Git z pełną historią.

models/
  monthly_revenue.sql
  revenue/
    active_subscriptions.sql
    churn_risk.sql

Podstawowa nazwa pliku jest nazwą tabeli: models/revenue/churn_risk.sql materializuje tabelę churn_risk. Foldery porządkują pliki, ale nie zmieniają nazwy tabeli.

Kompletny model#

-- name: Active subscriptions
-- schema: revenue
select
  s.id,
  s.customer_id,
  c.email,
  s.status,
  s.created_at
from titan.stripe.subscriptions s
join titan.stripe.customers c on c.id = s.customer_id
where s.status in ('active', 'past_due')
  and not s._deleted

Tworzy to tabelę revenue.active_subscriptions, którą można odpytywać jak każdą zsynchronizowaną tabelę. Bez wiersza -- schema: trafiłaby do domyślnego schematu models.

Model może odczytywać inne modele — wystarczy wskazać ich tabele. Supernova analizuje SQL, buduje graf zależności i uruchamia wszystko we właściwej kolejności. Model odczytujący własną tabelę wyjściową odczytuje wynik poprzedniego uruchomienia, co umożliwia tworzenie sum narastających i stopniowo budowanej historii.

Dyrektywy nagłówka#

Dyrektywy są wierszami komentarzy w pierwszych 20 wierszach pliku. Wszystkie są opcjonalne.

Nieprawidłowa dyrektywa nie działa częściowo: model odmawia uruchomienia i wskazuje błędny wiersz. Głośne zatrzymanie jest lepsze od po cichu zignorowanej literówki.

Przebudowa lub wstawianie i aktualizacja#

Domyślnie każde uruchomienie przebudowuje tabelę modelu od zera — to najprostsze i prawidłowe dla większości modeli. Zadeklarowanie klucza zmienia strategię:

-- unique_key: id

Od tej chwili każde uruchomienie wstawia lub aktualizuje według klucza: wiersze z pasującym kluczem są zastępowane, nowe są dodawane, a pozostałe nie zmieniają się. Użyj tej strategii, gdy model gromadzi historię, której przebudowanie byłoby kosztowne, albo gdy narzędzia podrzędne obserwują tabelę i nie powinny widzieć jej zniknięcia podczas przebudowy.

Uruchomienia#

Co 4 godziny jedno uruchomienie na organizację wykonuje wszystkie modele w kolejności zależności — do 4 jednocześnie, jeśli graf na to pozwala. Strona Modele pokazuje graf, ostatni wynik każdego modelu i przycisk Uruchom teraz. Działający model ma do 4 godzin, zanim uruchomienie oznaczy go jako nieudany i przejdzie do modeli, które od niego nie zależą.

Kontrola typów#

Każdy model jest przed uruchomieniem sprawdzany względem rzeczywistego schematu jeziora — przez ten sam moduł co edytor. Kolumna usunięta ze źródła lub zmiana typu w modelu nadrzędnym staje się więc nazwaną diagnostyką, a nie dopiero awarią dashboardu. Nagłówek -- lint: ustala ważność diagnostyki dla modelu:

-- lint:
--   TS0400: allow
--   TS0609: deny

allow obniża diagnostykę do ostrzeżenia, a deny podnosi ją do błędu blokującego. Dodaj adnotacje typów do najważniejszych wyrażeń, a moduł sprawdzający będzie pilnować ich w każdym uruchomieniu.