# セマンティック指標

> Apache Ossie モデルに指標を一度定義し、DuckLocal のサイドバーや ducklocal metrics CLI から実行します。1 つの DuckDB SELECT にコンパイルされます。

Source: https://ducklocal.app/docs/ja/metrics

セマンティックモデルは、ある数値が何を意味するかを一度だけ決めておくものです。何をエラーと数えるか、どの呼び出しが権限変更か、2 つのテーブルをどう結合するか。DuckLocal は [Apache Ossie](https://ossie.apache.org/) のファイル `model.ossie.yaml` からモデルを読み、各リクエスト（これらの指標を、これらのフィールドごとに、これらの条件で）を 1 つの DuckDB `SELECT` にコンパイルします。同じモデルに対する同じリクエストは常に同じ SQL になるので、`error_rate` を使うグラフ、回答、エージェントはすべて同じものを指します。

指標はウィンドウのサイドバーから実行することも、コマンドラインで `ducklocal metrics` を使って実行することもできます。[公式スキル](cli.md#install-the-official-skill) を入れたエージェントは、SQL を自分で書く代わりに指標で問い合わせます。

::: info 0.4.1 より新しい機能
セマンティック指標は DuckLocal の `main` ブランチにあり、次のリリースで提供されます。0.4.1 にはありません。
:::

## モデルを書く {#write-a-model}

`model.ossie.yaml` をプロジェクトのルート、つまりダッシュボードと同じ階層かその上に置きます。DuckLocal はフラットな Ossie 0.2 形式を読みます:

- `datasets`: それぞれに `source`（テーブルまたはビューの名前）、省略可能な `primary_key`、`fields` があります。`dimension: {is_time: true}` が付いたフィールドは時間フィールドです。
- `relationships`: `from`、`to`、`from_columns`、`to_columns`。
- `metrics`: モデルのルート、またはデータセットの下に置きます。データセットの下に置いた場合の名前は `dataset.metric` です。

式はすべて SQL 方言ごとに書きます。DuckLocal は `DUCKDB`、`OSSIE_SQL_2026`、`ANSI_SQL` のうち、その式が持つ最初のものを使い、DuckDB 自身のパーサーで読みます。次の短縮したモデルは [CloudTrail の例](example-cloudtrail.md) からのもので、例のダッシュボードが定義する `events` ビューを数えます:

```yaml
version: 0.2.0.dev0
name: cloudtrail
ai_context:
  instructions: >
    event_time is UTC. A NULL error_code means the call succeeded.
datasets:
- name: events
  source: events
  fields:
  - name: event_time
    expression: {dialects: [{dialect: ANSI_SQL, expression: event_time}]}
    dimension: {is_time: true}
  - name: ip
    expression: {dialects: [{dialect: ANSI_SQL, expression: ip}]}
    dimension: {is_time: false}
    ai_context: {synonyms: [source_ip, address]}
metrics:
- name: event_count
  description: API calls.
  expression: {dialects: [{dialect: ANSI_SQL, expression: COUNT(events.event_time)}]}
- name: error_count
  description: Calls that were refused or failed.
  expression: {dialects: [{dialect: ANSI_SQL, expression: COUNT(events.error_code)}]}
- name: error_rate
  description: The share of calls that were refused or failed.
  expression: {dialects: [{dialect: ANSI_SQL, expression: "error_count * 1.0 / NULLIF(event_count, 0)"}]}
```

`error_rate` のように、指標は他の指標から組み立てられます。使える方言がない、または DuckDB が解析できないフィールドや指標は、問題とともに一覧に載り、モデルの残りはそのまま使えます。名前が重複している、存在しないデータセットへの関係がある、`source` がテーブル名ではない、のいずれかに当たるモデルは全体が拒否されます。

## サイドバーから指標を実行する {#sidebar}

サイドバーの **スキーマ** タブには、**ダッシュボード** の下に **指標** セクションがあります。最近開いたダッシュボードのそばで見つかったモデルを一覧表示します:

- 各ダッシュボードについて、DuckLocal はそのフォルダーと、その上 3 階層までで `model.ossie.yaml` を探します。[ポータブルプロジェクト](agent-workflows.md) を示す `ducklocal-project.json` のあるフォルダーで探索を止めます。複数のダッシュボードから同じモデルが見つかっても、一覧には 1 回だけ載ります。
- 各モデルの下に、指標ごとに 1 行があります。モデルにカーソルを合わせるとパスと、データセットの定義元のダッシュボードが表示されます。指標にカーソルを合わせると説明と別名が表示されます。
- クエリできない指標には **クエリ不可** の印が付きます。カーソルを合わせると理由が表示されます。

指標またはその ▶ ボタンをクリックすると、DuckLocal はそれをコンパイルし、SQL をアクティブなクエリエディタに入れて実行します。📈 ボタンは、その指標が数えるデータセットの最初の時間フィールドで、日ごとに分けて実行します。

SQL の 1 行目には、数値の出どころが書かれます。例: `-- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …)`。モデルのデータセットがダッシュボードの `source` と `view` ブロックで定義されている場合、それらのブロックが CTE としてクエリの前に付きます。そのためクエリは、ダッシュボードが開いているかどうかにかかわらずウィンドウ自身の接続で実行され、他のクエリと同じように編集できます。

## コマンドラインから指標を実行する {#cli}

```bash
ducklocal metrics                       # 現在のフォルダーのモデル
ducklocal metrics compile --metric error_count,event_count --by events.ip \
  --where "events.user_name = 'ci-deploy'"
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data
```

最初の引数はモデルファイル、または `model.ossie.yaml` を含むフォルダーです。省略すると現在のフォルダーを使います。

- `ducklocal metrics` はモデルの語彙を JSON で出力します:
  - `model`。`sha256` と `ai_context` を含みます。
  - 各指標。`description`、`synonyms`、`queryable` を含みます。クエリできる指標は、数える対象のデータセットを `base` に示します。できない指標は `problem` に理由を示します。
  - 各フィールド。`dataset.field` の形で、`is_time` を含みます。
  - 関係とその `cardinality`。`to_columns` が `to` のキーなら `many_to_one`、そうでなければ `unknown` です。
- `metrics compile` はリクエストの SQL を、その列、基準データセット、結合、SQL の `sql_sha256` とともに出力します。データは読みません。
- `metrics query` はリクエストをコンパイルし、[`ducklocal query`](cli.md#query-options) と同じように SQL を実行します。`query` の `--database`、`--format`、[`--restricted`](agent-workflows.md) オプションを受け付け、コンパイルされた SQL、リクエスト、モデルの `sha256` を含む `semantic` オブジェクトを付けます。結果を引用するときはこれを引用します。`--views FILE.dash` は、そのダッシュボードの `source` と `view` ブロックを SQL の前に置きます。データセットがそこで定義されているモデル向けです。

リクエストは次の要素からなります:

| オプション | 意味 |
| --- | --- |
| `--metric NAME[,NAME]` | 計算する指標。繰り返し指定できます |
| `--by REF[,REF]` | 分けるフィールド。`dataset.field` の形で書きます。そのフィールドを持つデータセットが 1 つだけなら、フィールド名だけでもかまいません。`dataset.field:GRAIN` は時間フィールドを `second`、`minute`、`hour`、`day`、`week`、`month`、`quarter`、`year` のいずれかに切り詰めます。繰り返し指定できます |
| `--where SQL` | 1 つの条件。フィールドだけを使う条件は行を絞り込みます（`WHERE`）。`"error_count > 5"` のように指標名を使う条件はグループを絞り込みます（`HAVING`）。繰り返し指定でき、すべて適用されます |
| `--order-by NAME[:desc]` | 出力列、またはそのもとになった `dataset.field`。既定では `--by` の列の昇順です |
| `--limit N` | 最大 N 行 |

## リクエストが SQL になるまで {#compiled-sql}

コンパイルされた SQL は、指標が数えるデータセットに対する 1 つの `SELECT` です。多対一の関係に沿って、リクエストが名前を挙げた各データセットへ `LEFT JOIN` されるので、一致しない行も `NULL` の下で数えられます。出力列はフィールド（`ip`、粒度付きなら `event_time_day`）または指標の名前になります。2 つが衝突する場合は修飾されます（`events.user_name`）。フィールドの条件は `WHERE` に、指標の条件は `HAVING` に入ります。各 `--where` は 1 つの式でなければなりません。サブクエリ、2 つ目の文、式の外側にあるものは拒否されます。

## リクエストが拒否されたとき {#refusals}

DuckLocal は、正確に答えられないリクエストを、誤っているかもしれない数値を返す代わりに拒否します。拒否されると終了コードは 2 で、エラーには `kind` が付きます:

| Kind | 理由 |
| --- | --- |
| `metric_unknown_name` | その名前の指標もフィールドもありません。`hint` に最も近い名前が示されます |
| `metric_fanout` | フィールドが関係の「多」の側にあり、結合すると行が重複して数えられます。指標自身のデータセットのフィールドで分けてください |
| `metric_multi_grain` | 指標がそれぞれ別のデータセットを数えています。別々のクエリで問い合わせてください |
| `metric_ambiguous_path`、`metric_no_path` | データセットを結合する方法がモデルで 1 つに決まっていません |
| `metric_window_unsupported`、`metric_nested_aggregate`、`metric_not_aggregate` | 指標がウィンドウ関数である、集計を入れ子にしている、または集計ではありません |
| `metric_no_dialect` | 指標に DuckLocal が読める方言の式がありません |
| `metric_bad_grain` | 時間フィールドではないフィールドに粒度を指定しました |
| `metric_filter_refused` | `--where` が 1 つの式ではありません |
| `metric_missing` | `--metric` が指定されていません |
| `metric_no_dataset` | リクエストのどの指標も列を読まないので、数える対象のデータセットがありません。モデルの集計を修飾してください: `COUNT(*)` ではなく `COUNT(events.event_id)` |
| `model_invalid` | モデル自体に誤りがあります。[モデルを書く](#write-a-model) を参照してください |

モデルファイルを読めない場合は、終了コード 1、kind `model_not_found` になります。モデルで表現できない SQL が必要な問いには `ducklocal query` で SQL を書き、その数値がモデルの指標ではないことを明記してください。
