# Semantische Metriken

> Metriken einmal in einem Apache-Ossie-Modell definieren und dann in der Seitenleiste von DuckLocal oder mit der CLI ducklocal metrics ausführen, kompiliert zu einem DuckDB-SELECT.

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

Ein semantisches Modell legt einmal fest, was eine Zahl bedeutet: was als
Fehler zählt, welche Aufrufe Zugriffsänderungen sind, wie zwei Tabellen
verknüpft werden. DuckLocal liest das Modell aus einer
[Apache-Ossie](https://ossie.apache.org/)-Datei, `model.ossie.yaml`, und macht
aus jeder Anfrage (diese Metriken, nach diesen Feldern, unter diesen
Bedingungen) ein einziges DuckDB-`SELECT`. Dieselbe Anfrage auf demselben
Modell ergibt immer dasselbe SQL, also meinen alle Diagramme, Antworten und
Agenten, die `error_rate` verwenden, dasselbe.

Sie können eine Metrik in der Seitenleiste des Fensters ausführen oder mit
`ducklocal metrics` auf der Befehlszeile. Ein Agent mit dem
[offiziellen Skill](cli.md#install-the-official-skill) fragt nach Metriken,
statt das SQL selbst zu schreiben.

::: info Neuer als 0.4.1
Semantische Metriken sind auf dem Branch `main` von DuckLocal und erscheinen
mit dem nächsten Release. 0.4.1 hat sie noch nicht.
:::

## Ein Modell schreiben {#write-a-model}

Legen Sie `model.ossie.yaml` in das Stammverzeichnis eines Projekts, neben oder
über seine Dashboards. DuckLocal liest die flache Form von Ossie 0.2:

- `datasets`: Jedes hat eine `source` (den Namen einer Tabelle oder Sicht), ein
  optionales `primary_key` und `fields`. Ein Feld mit
  `dimension: {is_time: true}` ist ein Zeitfeld.
- `relationships`: `from`, `to`, `from_columns` und `to_columns`.
- `metrics`: auf oberster Ebene des Modells oder unter einem Datensatz, wo sie
  `dataset.metric` heißen.

Jeder Ausdruck wird pro SQL-Dialekt angegeben. DuckLocal nimmt den ersten von
`DUCKDB`, `OSSIE_SQL_2026` und `ANSI_SQL`, den der Ausdruck hat, und der
Parser von DuckDB liest ihn. Dieses gekürzte Modell aus dem
[CloudTrail-Beispiel](example-cloudtrail.md) zählt die Sicht `events`, die das
Dashboard des Beispiels definiert:

```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)"}]}
```

Eine Metrik kann aus anderen Metriken aufgebaut sein, wie `error_rate`. Ein
Feld oder eine Metrik ohne nutzbaren Dialekt oder mit einem Ausdruck, den
DuckDB nicht parsen kann, wird mit dem Problem aufgeführt; der Rest des Modells
funktioniert weiter. Ein Modell mit einem doppelten Namen, einer Beziehung zu
einem nicht vorhandenen Datensatz oder einer `source`, die kein Tabellenname
ist, wird als Ganzes abgelehnt.

## Eine Metrik in der Seitenleiste ausführen {#sidebar}

Der Schema-Tab der Seitenleiste hat unter **Dashboards** einen Abschnitt
**Metriken**. Er listet die Modelle, die neben den zuletzt geöffneten
Dashboards gefunden wurden:

- Für jedes Dashboard sucht DuckLocal `model.ossie.yaml` in dessen Ordner und
  bis zu drei Ordner darüber. Die Suche endet an einem Ordner mit
  `ducklocal-project.json`, der Markierung eines
  [portablen Projekts](agent-workflows.md). Ein Modell, das von mehreren
  Dashboards aus gefunden wird, steht nur einmal in der Liste.
- Unter jedem Modell steht eine Zeile pro Metrik. Fahren Sie über das Modell,
  um seinen Pfad und das Dashboard zu sehen, aus dem seine Datensätze stammen.
  Fahren Sie über eine Metrik, um ihre Beschreibung und Synonyme zu sehen.
- Eine Metrik, die sich nicht abfragen lässt, ist als **nicht abfragbar**
  markiert. Fahren Sie darüber, um den Grund zu sehen.

Klicken Sie auf eine Metrik oder ihre ▶-Schaltfläche: DuckLocal kompiliert
sie, setzt das SQL in den aktiven Abfrage-Editor und führt es aus. Die
Schaltfläche 📈 führt sie nach Tagen aufgeschlüsselt aus, über das erste
Zeitfeld des Datensatzes, den sie zählt.

Das SQL beginnt mit einer Zeile, die sagt, woher die Zahl kommt, etwa
`-- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …)`.
Stammen die Datensätze des Modells aus den `source`- und `view`-Blöcken eines
Dashboards, stehen diese Blöcke als CTEs vor der Abfrage. Die Abfrage läuft
dann auf der eigenen Verbindung des Fensters, ob das Dashboard offen ist oder
nicht, und Sie können sie wie jede andere Abfrage bearbeiten.

## Eine Metrik auf der Befehlszeile ausführen {#cli}

```bash
ducklocal metrics                       # das Modell im aktuellen Ordner
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
```

Das erste Argument ist eine Modelldatei oder ein Ordner mit
`model.ossie.yaml`. Ohne Argument wird der aktuelle Ordner verwendet.

- `ducklocal metrics` gibt das Vokabular des Modells als JSON aus:
  - `model` mit seinem `sha256` und `ai_context`.
  - Jede Metrik mit `description`, `synonyms` und `queryable`. Eine abfragbare
    Metrik nennt ihre `base`, den Datensatz, den sie zählt; eine andere hat
    ein `problem`, das den Grund nennt.
  - Jedes Feld als `dataset.field`, mit `is_time`.
  - Die Beziehungen, jeweils mit ihrer `cardinality`: `many_to_one`, wenn die
    `to_columns` ein Schlüssel von `to` sind, sonst `unknown`.
- `metrics compile` gibt das SQL einer Anfrage aus, mit seinen Spalten, dem
  Basisdatensatz, den Joins und dem `sql_sha256` des SQL. Es liest keine Daten.
- `metrics query` kompiliert die Anfrage und führt das SQL aus wie
  [`ducklocal query`](cli.md#query-options). Es nimmt die Optionen
  `--database`, `--format` und [`--restricted`](agent-workflows.md) von `query`
  und fügt ein `semantic`-Objekt mit dem kompilierten SQL, der Anfrage und dem
  `sha256` des Modells hinzu; das ist zu zitieren. `--views FILE.dash` stellt
  die `source`- und `view`-Blöcke dieses Dashboards vor das SQL, für Modelle,
  deren Datensätze dort definiert sind.

Eine Anfrage besteht aus:

| Option | Bedeutet |
| --- | --- |
| `--metric NAME[,NAME]` | Die zu berechnenden Metriken. Wiederholbar |
| `--by REF[,REF]` | Felder, nach denen aufgeschlüsselt wird, als `dataset.field`. Ein bloßer Feldname reicht, wenn nur ein Datensatz ihn hat. `dataset.field:GRAIN` kürzt ein Zeitfeld auf `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter` oder `year`. Wiederholbar |
| `--where SQL` | Eine Bedingung. Eine Bedingung über Felder filtert Zeilen (`WHERE`); eine über Metriknamen, etwa `"error_count > 5"`, filtert Gruppen (`HAVING`). Wiederholbar; alle gelten |
| `--order-by NAME[:desc]` | Eine Ausgabespalte oder das `dataset.field`, aus dem sie stammt. Standard: die `--by`-Spalten, aufsteigend |
| `--limit N` | Höchstens N Zeilen |

## Wie aus einer Anfrage SQL wird {#compiled-sql}

Das kompilierte SQL ist ein einziges `SELECT` über den Datensatz, den die
Metriken zählen. Entlang von Viele-zu-eins-Beziehungen wird es per `LEFT JOIN`
mit jedem Datensatz verknüpft, den die Anfrage nennt, sodass eine Zeile ohne
Treffer trotzdem zählt, unter `NULL`. Ausgabespalten heißen wie das Feld (`ip`,
oder `event_time_day` bei einer Zeiteinheit) oder die Metrik. Kollidieren zwei
Namen, werden sie qualifiziert (`events.user_name`). Eine Feldbedingung kommt
in `WHERE`, eine Metrikbedingung in `HAVING`. Jedes `--where` ist ein einziger
Ausdruck: Eine Unterabfrage, eine zweite Anweisung oder irgendetwas um den
Ausdruck herum wird abgelehnt.

## Wenn eine Anfrage abgelehnt wird {#refusals}

DuckLocal lehnt eine Anfrage ab, die es nicht exakt beantworten kann, statt
eine möglicherweise falsche Zahl zurückzugeben. Eine Ablehnung endet mit
Exit-Code 2, und der Fehler nennt einen `kind`:

| Kind | Warum |
| --- | --- |
| `metric_unknown_name` | Keine Metrik und kein Feld heißt so. Der `hint` nennt den ähnlichsten Namen |
| `metric_fanout` | Das Feld liegt auf der „viele“-Seite einer Beziehung, und der Join würde Zeilen mehrfach zählen. Schlüsseln Sie nach einem Feld des eigenen Datensatzes der Metrik auf |
| `metric_multi_grain` | Die Metriken zählen verschiedene Datensätze. Fragen Sie jede in einer eigenen Abfrage ab |
| `metric_ambiguous_path`, `metric_no_path` | Das Modell gibt nicht genau einen Weg an, die Datensätze zu verknüpfen |
| `metric_window_unsupported`, `metric_nested_aggregate`, `metric_not_aggregate` | Die Metrik ist eine Fensterfunktion, verschachtelt Aggregate oder ist kein Aggregat |
| `metric_no_dialect` | Die Metrik hat keinen Ausdruck in einem Dialekt, den DuckLocal liest |
| `metric_bad_grain` | Eine Zeiteinheit wurde für ein Feld verlangt, das kein Zeitfeld ist |
| `metric_filter_refused` | Ein `--where` ist mehr als ein Ausdruck |
| `metric_missing` | Es wurde kein `--metric` angegeben |
| `metric_no_dataset` | Keine Metrik der Anfrage liest eine Spalte, also gibt es keinen Datensatz zu zählen. Qualifizieren Sie das Aggregat im Modell: `COUNT(events.event_id)`, nicht `COUNT(*)` |
| `model_invalid` | Das Modell selbst ist fehlerhaft, wie unter [Ein Modell schreiben](#write-a-model) beschrieben |

Eine Modelldatei, die sich nicht lesen lässt, endet mit Exit-Code 1 und dem
kind `model_not_found`. Braucht eine Frage SQL, das das Modell nicht ausdrücken
kann, schreiben Sie es mit `ducklocal query` und sagen Sie dazu, dass diese Zahl
keine der Metriken des Modells ist.
