---
title: モデルリファレンス
description: モデルのファイル名、先頭のディレクティブ、lint ポリシー、状態、失敗時の動作を参照します。
species: reference
---
# モデルリファレンス

モデルは `models/` にある 1 つの SQL ファイルです。ベース名が出力テーブル名、フォルダーパスが出力スキーマになります。

## 先頭のディレクティブ

ディレクティブは先頭のコメントヘッダーに記述する必要があります。パーサーが調べるのは最大で先頭 20 行です。

| ディレクティブ | 意味 |
|---|---|
| `-- name:` | 表示名を明示的に指定 |
| `-- schema:` | 出力スキーマを明示的に指定 |
| `-- cadence: manual` | 組織全体の定期実行から除外 |
| `-- depends_on: schema.table` | グラフに依存関係を明示的に追加 |
| `-- unique_key: column` | テーブルを置き換えず、この出力列のキーで upsert |
| `-- bigquery` | 文を BigQuery に送信。先頭行に置く必要があり、`titan.*` は参照不可 |
| `-- query-<class>` | より大きなメモリクラスに実行を固定。リソース不足のエラーで指示された場合のみ使用 |
| `-- lint:` | 範囲を限定した typesql 診断ポリシーブロックを開始 |

```sql
-- schema: finance
-- cadence: manual
-- depends_on: stripe.charges
-- unique_key: customer_id
-- lint:
--   TS0609: allow

select
  customer as customer_id,
  sum(amount) / 100.0 as revenue
from titan.stripe.charges
where status = 'succeeded' and not _deleted
group by customer
```

## 命名の制約

モデルは接続したソースが所有するスキーマには書き込めません。`finance` や `analytics` など、派生データ用のスキーマを選んでください。ベース名の変更は、出力テーブルの名前変更になります。

## 実行状態

各ステップは、待機中、実行中、成功、失敗、スキップの結果を記録します。手動モデルは定期実行ではスキップします。依存先が失敗した場合、その下流のステップは開始しません。

## よくある失敗

- 循環参照や不明な明示的依存関係があるグラフは拒否します。
- typesql のエラーは `enforce` での実行を停止し、安定したコードで記録します。
- 一意キーの列がない場合、upsert による実体化を拒否します。
- BigQuery に送信するモデルが `titan.*` を参照している場合、送信前に拒否します。
- クエリがタイムアウトするか、メモリ予算を使い切った場合、部分的なテーブルを公開せずにステップを失敗とします。