コンテンツへスキップ

セマンティック指標 ​

セマンティックモデルは、ある数値が何を意味するかを一度だけ決めておくものです。何をエラーと数えるか、どの呼び出しが権限変更か、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 ビューを数えます:

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 がテーブル名ではない、のいずれかに当たるモデルは全体が拒否されます。

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

  • 各ダッシュボードについて、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 としてクエリの前に付きます。そのためクエリは、ダッシュボードが開いているかどうかにかかわらずウィンドウ自身の接続で実行され、他のクエリと同じように編集できます。

コマンドラインから指標を実行する ​

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 と同じように 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 SQL1 つの条件。フィールドだけを使う条件は行を絞り込みます(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 を書き、その数値がモデルの指標ではないことを明記してください。

Apache-2.0 ライセンスで公開されています。