Adnotacje typów#

Typesql jest SQL z opcjonalnymi typami. Oznaczasz miejsca zależne od założenia — ta kolumna nigdy nie jest null, ta liczba mieści się w decimal(28,2), ten JSON ma pole plan — a moduł sprawdzający weryfikuje je względem rzeczywistego schematu jeziora przed wykonaniem zapytania i po każdej zmianie schematu.

select
  id,
  amount satisfies integer!,
  metadata::json<{plan: string}> ->> 'plan' as plan
from titan.stripe.charges

Gwarancja#

Adnotacje nigdy nie zmieniają wyniku zapytania. Usuń wszystkie adnotacje z dokumentu typesql, a otrzymasz zwykły SQL działający identycznie — te same wiersze, wartości i wszystko inne. To gwarancja strukturalna, a nie konwencja: typy są sprawdzane i wymazywane; żadna ścieżka wykonania nie może ich nawet odczytać.

Nie musisz więc podejmować decyzji o migracji. Oznacz jedno wyrażenie w jednym zapytaniu i na tym zakończ albo nadaj typy całemu modelowi — każdy punkt między „zwykłym SQL” a „pełnymi typami” jest działającym programem.

satisfies: sprawdzanie wyrażenia#

Zapisz expr satisfies type wszędzie tam, gdzie dozwolone jest wyrażenie:

select
  round(sum(amount) / 100.0, 2) satisfies decimal(38,2) as gross_volume
from titan.stripe.charges
where not _deleted

Jeśli zmiana schematu kiedykolwiek sprawi, że wyrażenie przestanie być liczbą dziesiętną, model nie przejdzie kontroli z diagnostyką wskazującą dokładny zakres — zamiast po cichu pokazać śmieci na dashboardzie. Każdy komunikat zawiera stabilny kod TS, lokalizację i wiersz help: z poprawką.

satisfies nie jest rzutowaniem. amount::string konwertuje wartość; amount satisfies string stwierdza fakt i nie przechodzi kontroli, gdy jest fałszywy. Używaj ::, aby zmieniać dane, i satisfies, aby wykrywać zmiany.

Brak wartości null: ! i zawężanie#

string! oznacza „tekst, który nigdy nie jest null”. Moduł sprawdzający rozumie wpływ logiki zapytania na możliwość wartości null — to przejdzie kontrolę:

select email satisfies string!
from titan.stripe.customers
where email is not null

Usuń where, a kontrola się nie powiedzie: email może być null w schemacie, a zapytanie niczego takiego nie wykluczyło. Działa też odwrotna sytuacja — kolumna bez null staje się opcjonalna po zewnętrznej stronie left join, co również jest śledzone. Kontrola odzwierciedla działanie zapytania, nie tylko deklarację schematu.

Nagłówki CTE z typami#

Nagłówek CTE może zadeklarować typy kolumn, zmieniając granicę między etapami zapytania w sprawdzany kontrakt:

with monthly(month: date!, gross_volume: decimal(38,2)) as (
  select
    date_trunc('month', created_at)::date,
    round(sum(amount) / 100.0, 2)
  from titan.stripe.charges
  where not _deleted
  group by 1
)
select * from monthly where gross_volume > 250000

Ciało jest sprawdzane względem nagłówka, a wszystko poniżej monthly otrzymuje zadeklarowane typy. Po wymazaniu nagłówek traci typy — with monthly(month, gross_volume) as (…) — i działa jak zwykły SQL.

JSON z typami#

Nadaj kolumnie JSON strukturę, aby odwołania do niej przestały być domysłami:

select
  metadata::json<{plan: string, seats: integer}> as meta,
  meta ->> 'plan' as plan
from titan.stripe.charges

Literówka taka jak meta ->> 'paln' staje się błędem kontroli, a nie kolumną null odkrytą trzy dashboardy później.

W edytorze#

Edytor zapytań uruchamia ten sam moduł w trakcie pisania. Wskaż wyrażenie, aby zobaczyć wywnioskowany typ. Podpowiedzi w kodzie pokazują typy już znane modułowi, a kliknięcie jednej zapisuje ją w zapytaniu jako prawdziwą adnotację satisfies — stopniowe typowanie jednym kliknięciem. Szybkie poprawki zawierają te same zmiany co sugestie diagnostyki.

Co dalej#

• Pisanie modeli — modele są sprawdzane względem jeziora przy każdym uruchomieniu, a nagłówek -- lint: ustala, która diagnostyka blokuje.

• Strony systemu typów opisują pełną gramatykę: typy skalarne, decimal(p,s), listy i struktury, typy tabel oraz sposób typowania kolumn systemowych, takich jak _synced_at.