---
title: Pisanie modeli
description: Model jest instrukcją select w pliku. Supernova materializuje go jako tabelę odświeżaną w kolejności zależności.
species: guide
---

# 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ą.

```text
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

```sql run
-- 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.

| Dyrektywa | Skutek |
|---|---|
| `-- name: Monthly revenue` | Nazwa wyświetlana w przeglądarce plików i historii uruchomień |
| `-- schema: revenue` | Schemat wyjściowy (domyślnie `models`; małe litery, bez przesłaniania schematu zsynchronizowanego źródła) |
| `-- cadence: manual` | Wykluczenie z zaplanowanych uruchomień; przebudowa tylko na żądanie |
| `-- depends_on: stripe.charges` | Dodanie zależności niewidocznej w samym SQL |
| `-- unique_key: id` | Aktualizacje przyrostowe według klucza zamiast pełnej przebudowy — opis poniżej |
| `-- lint:` | Polityka diagnostyczna danego modelu, po jednym `TS0000: allow` lub `deny` w wierszu |

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ę:

```sql fragment
-- 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:

```sql fragment
-- 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](/docs/typesql/annotations) do najważniejszych wyrażeń, a moduł sprawdzający będzie pilnować ich w każdym uruchomieniu.