Semantische Metriken
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-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 fragt nach Metriken, statt das SQL selbst zu schreiben.
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
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 einesource(den Namen einer Tabelle oder Sicht), ein optionalesprimary_keyundfields. Ein Feld mitdimension: {is_time: true}ist ein Zeitfeld.relationships:from,to,from_columnsundto_columns.metrics: auf oberster Ebene des Modells oder unter einem Datensatz, wo siedataset.metricheiß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 zählt die Sicht events, die das Dashboard des Beispiels definiert:
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
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.yamlin dessen Ordner und bis zu drei Ordner darüber. Die Suche endet an einem Ordner mitducklocal-project.json, der Markierung eines portablen Projekts. 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
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 dataDas erste Argument ist eine Modelldatei oder ein Ordner mit model.ossie.yaml. Ohne Argument wird der aktuelle Ordner verwendet.
ducklocal metricsgibt das Vokabular des Modells als JSON aus:modelmit seinemsha256undai_context.- Jede Metrik mit
description,synonymsundqueryable. Eine abfragbare Metrik nennt ihrebase, den Datensatz, den sie zählt; eine andere hat einproblem, das den Grund nennt. - Jedes Feld als
dataset.field, mitis_time. - Die Beziehungen, jeweils mit ihrer
cardinality:many_to_one, wenn dieto_columnsein Schlüssel vontosind, sonstunknown.
metrics compilegibt das SQL einer Anfrage aus, mit seinen Spalten, dem Basisdatensatz, den Joins und demsql_sha256des SQL. Es liest keine Daten.metrics querykompiliert die Anfrage und führt das SQL aus wieducklocal query. Es nimmt die Optionen--database,--formatund--restrictedvonqueryund fügt einsemantic-Objekt mit dem kompilierten SQL, der Anfrage und demsha256des Modells hinzu; das ist zu zitieren.--views FILE.dashstellt diesource- undview-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
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
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 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.
