Zum Inhalt springen

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 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 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.

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. 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 ​

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. Es nimmt die Optionen --database, --format und --restricted 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:

OptionBedeutet
--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 SQLEine 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 NHö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:

KindWarum
metric_unknown_nameKeine Metrik und kein Feld heißt so. Der hint nennt den ähnlichsten Namen
metric_fanoutDas 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_grainDie Metriken zählen verschiedene Datensätze. Fragen Sie jede in einer eigenen Abfrage ab
metric_ambiguous_path, metric_no_pathDas Modell gibt nicht genau einen Weg an, die Datensätze zu verknüpfen
metric_window_unsupported, metric_nested_aggregate, metric_not_aggregateDie Metrik ist eine Fensterfunktion, verschachtelt Aggregate oder ist kein Aggregat
metric_no_dialectDie Metrik hat keinen Ausdruck in einem Dialekt, den DuckLocal liest
metric_bad_grainEine Zeiteinheit wurde für ein Feld verlangt, das kein Zeitfeld ist
metric_filter_refusedEin --where ist mehr als ein Ausdruck
metric_missingEs wurde kein --metric angegeben
metric_no_datasetKeine 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_invalidDas 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.

Veröffentlicht unter der Apache-2.0-Lizenz.