---
title: モデルを作成する
description: モデルはファイルに記述した select 文です。Supernova はその結果をテーブルとして保持し、依存順に更新します。
species: guide
---

# モデルを作成する

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

## モデルの保存場所

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

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

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

## モデルの完全な例

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

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

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

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

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

| ディレクティブ | 効果 |
|---|---|
| `-- name: Monthly revenue` | ファイルブラウザーと実行履歴で使う表示名 |
| `-- schema: revenue` | 出力スキーマ。デフォルトは `models`。小文字で指定し、同期ソースのスキーマと重複させることはできません |
| `-- cadence: manual` | スケジュール実行から除外し、手動で実行したときだけ再構築 |
| `-- depends_on: stripe.charges` | SQL だけでは分からない依存関係を追加 |
| `-- unique_key: id` | 全体の再構築ではなくキーによる増分更新。詳細は後述 |
| `-- lint:` | モデルごとの診断ポリシー。1 行に `TS0000: allow` または `deny` を 1 つ指定 |

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

## 再構築か upsert か

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

```sql fragment
-- unique_key: id
```

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

## 実行

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

## 型検証

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

```sql fragment
-- lint:
--   TS0400: allow
--   TS0609: deny
```

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