セマンティック指標
セマンティックモデルは、ある数値が何を意味するかを一度だけ決めておくものです。何をエラーと数えるか、どの呼び出しが権限変更か、2 つのテーブルをどう結合するか。DuckLocal は Apache Ossie のファイル model.ossie.yaml からモデルを読み、各リクエスト(これらの指標を、これらのフィールドごとに、これらの条件で)を 1 つの DuckDB SELECT にコンパイルします。同じモデルに対する同じリクエストは常に同じ SQL になるので、error_rate を使うグラフ、回答、エージェントはすべて同じものを指します。
指標はウィンドウのサイドバーから実行することも、コマンドラインで ducklocal metrics を使って実行することもできます。公式スキル を入れたエージェントは、SQL を自分で書く代わりに指標で問い合わせます。
0.4.1 より新しい機能
セマンティック指標は DuckLocal の main ブランチにあり、次のリリースで提供されます。0.4.1 にはありません。
モデルを書く
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 の例 からのもので、例のダッシュボードが定義する events ビューを数えます:
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 がテーブル名ではない、のいずれかに当たるモデルは全体が拒否されます。
サイドバーから指標を実行する
サイドバーの スキーマ タブには、ダッシュボード の下に 指標 セクションがあります。最近開いたダッシュボードのそばで見つかったモデルを一覧表示します:
- 各ダッシュボードについて、DuckLocal はそのフォルダーと、その上 3 階層までで
model.ossie.yamlを探します。ポータブルプロジェクト を示すducklocal-project.jsonのあるフォルダーで探索を止めます。複数のダッシュボードから同じモデルが見つかっても、一覧には 1 回だけ載ります。 - 各モデルの下に、指標ごとに 1 行があります。モデルにカーソルを合わせるとパスと、データセットの定義元のダッシュボードが表示されます。指標にカーソルを合わせると説明と別名が表示されます。
- クエリできない指標には クエリ不可 の印が付きます。カーソルを合わせると理由が表示されます。
指標またはその ▶ ボタンをクリックすると、DuckLocal はそれをコンパイルし、SQL をアクティブなクエリエディタに入れて実行します。📈 ボタンは、その指標が数えるデータセットの最初の時間フィールドで、日ごとに分けて実行します。
SQL の 1 行目には、数値の出どころが書かれます。例: -- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …)。モデルのデータセットがダッシュボードの source と view ブロックで定義されている場合、それらのブロックが CTE としてクエリの前に付きます。そのためクエリは、ダッシュボードが開いているかどうかにかかわらずウィンドウ自身の接続で実行され、他のクエリと同じように編集できます。
コマンドラインから指標を実行する
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と同じように SQL を実行します。queryの--database、--format、--restrictedオプションを受け付け、コンパイルされた 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 になるまで
コンパイルされた SQL は、指標が数えるデータセットに対する 1 つの SELECT です。多対一の関係に沿って、リクエストが名前を挙げた各データセットへ LEFT JOIN されるので、一致しない行も NULL の下で数えられます。出力列はフィールド(ip、粒度付きなら event_time_day)または指標の名前になります。2 つが衝突する場合は修飾されます(events.user_name)。フィールドの条件は WHERE に、指標の条件は HAVING に入ります。各 --where は 1 つの式でなければなりません。サブクエリ、2 つ目の文、式の外側にあるものは拒否されます。
リクエストが拒否されたとき
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 | モデル自体に誤りがあります。モデルを書く を参照してください |
モデルファイルを読めない場合は、終了コード 1、kind model_not_found になります。モデルで表現できない SQL が必要な問いには ducklocal query で SQL を書き、その数値がモデルの指標ではないことを明記してください。
