モデルを作成する#

モデルは 1 つの select 文を含む .sql ファイルです。Supernova はそれをレイクのテーブルとして実体化し、ほかのモデルとともに依存順に 4 時間ごとに再構築します。設定ファイルもスケジューラーの設定も不要で、SQL 自体が定義のすべてです。

モデルの保存場所#

モデルはデータリポジトリの models/ に置くファイルです。ファイルページで編集するか、リポジトリをクローンして自分のエディターを使えます。どちらでも Git で完全な履歴を保持します。

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

ファイルのベース名がテーブル名になります。models/revenue/churn_risk.sql は churn_risk というテーブルを実体化します。フォルダーはファイルを整理するためのもので、テーブル名は変えません。

モデルの完全な例#

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

これにより revenue.active_subscriptions が作成され、同期したテーブルと同じようにクエリできます。-- schema: の行を省略すると、デフォルトの models スキーマに作成されます。

ほかのモデルを読み取るには、そのテーブル名を指定します。Supernova は SQL から依存グラフを構築し、正しい順序ですべてを実行します。モデルが自身の出力テーブルを読む場合は、前回の実行結果を読み取ると解釈します。累積値や段階的に蓄積する履歴は、この仕組みで作成できます。

ヘッダーのディレクティブ#

ディレクティブは、ファイルの先頭 20 行以内に記述するコメント行です。すべて省略できます。

不正なディレクティブを部分的に適用することはありません。モデルは実行を拒否し、該当行を示すエラーを返します。入力ミスを黙って無視せず、明確に停止します。

再構築か upsert か#

デフォルトでは、実行のたびにモデルのテーブルを最初から再構築します。最も単純で、多くのモデルに適した方法です。キーを宣言すると、更新方法が変わります。

-- unique_key: id

以降の実行では、そのキーによって upsert します。キーが一致する行を置き換え、新しい行を追加し、それ以外は変更しません。再構築では計算し直す必要がある履歴を蓄積する場合や、下流のツールがテーブルを監視していて、再構築中にテーブルが消えるのを避けたい場合に使います。

実行#

4 時間ごとに、組織単位の 1 回の実行ですべてのモデルを依存順に処理します。グラフが許す範囲で、最大 4 個を並列実行します。モデルページにはグラフ、各モデルの最終結果、今すぐ実行ボタンが表示されます。モデルの実行上限は 4 時間です。超過すると失敗として記録し、そのモデルに依存しない処理へ進みます。

型検証#

すべてのモデルは実行前に、レイクの実際のスキーマに照らして検証します。エディターと同じ検証器を使うため、ソースで列が削除されたり上流で型が変わったりしても、ダッシュボードが壊れる前に、名前付きの診断として検出できます。-- lint: ヘッダーでモデルごとに重大度を調整します。

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

allow は診断を警告に下げ、deny は実行を止めるエラーに上げます。特に重要な式に型注釈を追加すると、毎回その条件を検証できます。