Vai al contenuto

Metriche semantiche ​

Un modello semantico stabilisce una volta per tutte che cosa significa un numero: che cosa conta come errore, quali chiamate sono modifiche agli accessi, come si uniscono due tabelle. DuckLocal legge il modello da un file Apache Ossie, model.ossie.yaml, e trasforma ogni richiesta (queste metriche, per questi campi, a queste condizioni) in un'unica SELECT DuckDB. La stessa richiesta sullo stesso modello si compila sempre nello stesso SQL, quindi ogni grafico, risposta e agente che usa error_rate intende la stessa cosa.

Puoi eseguire una metrica dalla barra laterale della finestra, oppure con ducklocal metrics dalla riga di comando. Un agente con la skill ufficiale chiede per metrica invece di scrivere l'SQL da sé.

Successivo alla 0.4.1

Le metriche semantiche sono sul branch main di DuckLocal e arriveranno con la prossima versione. La 0.4.1 non le ha.

Scrivi un modello ​

Metti model.ossie.yaml nella radice di un progetto, accanto alle sue dashboard o sopra di esse. DuckLocal legge la forma piatta di Ossie 0.2:

  • datasets: ognuno ha una source (il nome di una tabella o vista), un primary_key facoltativo e dei fields. Un campo marcato con dimension: {is_time: true} è un campo temporale.
  • relationships: from, to, from_columns e to_columns.
  • metrics: nella radice del modello, o sotto un dataset, dove si chiamano dataset.metric.

Ogni espressione è scritta per dialetto SQL. DuckLocal usa il primo tra DUCKDB, OSSIE_SQL_2026 e ANSI_SQL che l'espressione possiede, e la legge il parser di DuckDB stesso. Questo modello abbreviato, dall' esempio CloudTrail, conta la vista events che la dashboard dell'esempio definisce:

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

Una metrica può essere costruita da altre metriche, come error_rate. Un campo o una metrica senza un dialetto utilizzabile, o che DuckDB non riesce ad analizzare, viene elencato con il problema, e il resto del modello continua a funzionare. Un modello con un nome duplicato, una relazione verso un dataset inesistente o una source che non è un nome di tabella viene rifiutato per intero.

La scheda Schema della barra laterale ha una sezione Metriche, sotto Dashboard. Elenca i modelli trovati accanto alle dashboard aperte di recente:

  • Per ogni dashboard, DuckLocal cerca model.ossie.yaml nella sua cartella e fino a tre cartelle sopra. Si ferma a una cartella che contiene ducklocal-project.json, il segno di un progetto portabile. Un modello trovato da più dashboard compare una volta sola.
  • Sotto ogni modello c'è una riga per metrica. Passa il puntatore sul modello per vederne il percorso e la dashboard da cui provengono i suoi dataset. Passalo su una metrica per vederne la descrizione e i sinonimi.
  • Una metrica che non si può interrogare è segnata come non interrogabile. Passaci sopra il puntatore per vedere perché.

Fai clic su una metrica, o sul suo pulsante ▶, e DuckLocal la compila, mette l'SQL nell'editor di query attivo e lo esegue. Il pulsante 📈 la esegue suddivisa per giorno, sul primo campo temporale del dataset che conta.

L'SQL inizia con una riga che dice da dove viene il numero, per esempio -- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …). Quando i dataset del modello vengono dai blocchi source e view di una dashboard, quei blocchi vengono messi davanti alla query come CTE. La query viene quindi eseguita sulla connessione della finestra stessa, che la dashboard sia aperta o no, e puoi modificarla come qualsiasi altra query.

Esegui una metrica dalla riga di comando ​

bash
ducklocal metrics                       # il modello nella cartella corrente
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

Il primo argomento è un file di modello, o una cartella che contiene model.ossie.yaml. Se lo ometti, viene usata la cartella corrente.

  • ducklocal metrics stampa il vocabolario del modello in JSON:
    • model, con il suo sha256 e ai_context.
    • Ogni metrica, con description, synonyms e queryable. Una metrica interrogabile indica la sua base, il dataset che conta; una che non lo è ha un problem che spiega perché.
    • Ogni campo come dataset.field, con is_time.
    • Le relazioni, ciascuna con la sua cardinality: many_to_one quando le to_columns sono una chiave di to, altrimenti unknown.
  • metrics compile stampa l'SQL di una richiesta, con le sue colonne, il dataset di base, i join e lo sql_sha256 dell'SQL. Non legge dati.
  • metrics query compila la richiesta ed esegue l'SQL come fa ducklocal query. Accetta le opzioni --database, --format e --restricted di query, e aggiunge un oggetto semantic con l'SQL compilato, la richiesta e lo sha256 del modello, che è ciò da citare. --views FILE.dash mette i blocchi source e view di quella dashboard davanti all'SQL, per i modelli i cui dataset sono definiti lì.

Una richiesta è fatta di:

OpzioneSignifica
--metric NAME[,NAME]Le metriche da calcolare. Ripetibile
--by REF[,REF]I campi per cui suddividere, come dataset.field. Basta il nome del campo quando un solo dataset lo ha. dataset.field:GRAIN tronca un campo temporale a second, minute, hour, day, week, month, quarter o year. Ripetibile
--where SQLUna condizione. Una condizione sui campi filtra le righe (WHERE); una sui nomi delle metriche, come "error_count > 5", filtra i gruppi (HAVING). Ripetibile; si applicano tutte
--order-by NAME[:desc]Una colonna di output, o il dataset.field da cui proviene. Il predefinito sono le colonne di --by, in ordine crescente
--limit NAl massimo N righe

Come una richiesta diventa SQL ​

L'SQL compilato è un'unica SELECT sul dataset che le metriche contano. Viene unito con LEFT JOIN, lungo relazioni molti-a-uno, a ogni dataset nominato dalla richiesta, quindi una riga senza corrispondenza conta comunque, sotto NULL. Le colonne di output prendono il nome del campo (ip, o event_time_day con una granularità) o della metrica. Quando due nomi collidono, vengono qualificati (events.user_name). Una condizione su un campo va in WHERE, una su una metrica in HAVING. Ogni --where è una sola espressione: una sottoquery, una seconda istruzione o qualunque cosa attorno all'espressione viene rifiutata.

Quando una richiesta viene rifiutata ​

DuckLocal rifiuta una richiesta a cui non può rispondere con esattezza, invece di restituire un numero che potrebbe essere sbagliato. Un rifiuto esce con codice 2, e l'errore indica un kind:

KindPerché
metric_unknown_nameNessuna metrica o campo ha quel nome. L'hint indica il più vicino
metric_fanoutIl campo è sul lato "molti" di una relazione, e il join conterebbe le righe più di una volta. Suddividi per un campo del dataset della metrica stessa
metric_multi_grainLe metriche contano dataset diversi. Chiedi ciascuna in una query a sé
metric_ambiguous_path, metric_no_pathIl modello non indica esattamente un modo per unire i dataset
metric_window_unsupported, metric_nested_aggregate, metric_not_aggregateLa metrica è una funzione finestra, annida aggregati o non è un aggregato
metric_no_dialectLa metrica non ha un'espressione in un dialetto che DuckLocal legge
metric_bad_grainÈ stata chiesta una granularità per un campo che non è temporale
metric_filter_refusedUn --where contiene più di un'espressione
metric_missingNon è stato dato alcun --metric
metric_no_datasetNessuna metrica della richiesta legge una colonna, quindi non c'è un dataset da contare. Qualifica l'aggregato nel modello: COUNT(events.event_id), non COUNT(*)
model_invalidIl modello stesso è sbagliato, come descritto in Scrivi un modello

Un file di modello che non si riesce a leggere esce con codice 1 e kind model_not_found. Quando una domanda richiede SQL che il modello non può esprimere, scrivilo con ducklocal query e specifica che quel numero non è una delle metriche del modello.

Pubblicato con licenza Apache-2.0.