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 unasource(il nome di una tabella o vista), unprimary_keyfacoltativo e deifields. Un campo marcato condimension: {is_time: true}è un campo temporale.relationships:from,to,from_columnseto_columns.metrics: nella radice del modello, o sotto un dataset, dove si chiamanodataset.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:
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.
Esegui una metrica dalla barra laterale
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.yamlnella sua cartella e fino a tre cartelle sopra. Si ferma a una cartella che contieneducklocal-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
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 dataIl primo argomento è un file di modello, o una cartella che contiene model.ossie.yaml. Se lo ometti, viene usata la cartella corrente.
ducklocal metricsstampa il vocabolario del modello in JSON:model, con il suosha256eai_context.- Ogni metrica, con
description,synonymsequeryable. Una metrica interrogabile indica la suabase, il dataset che conta; una che non lo è ha unproblemche spiega perché. - Ogni campo come
dataset.field, conis_time. - Le relazioni, ciascuna con la sua
cardinality:many_to_onequando leto_columnssono una chiave dito, altrimentiunknown.
metrics compilestampa l'SQL di una richiesta, con le sue colonne, il dataset di base, i join e losql_sha256dell'SQL. Non legge dati.metrics querycompila la richiesta ed esegue l'SQL come faducklocal query. Accetta le opzioni--database,--formate--restricteddiquery, e aggiunge un oggettosemanticcon l'SQL compilato, la richiesta e losha256del modello, che è ciò da citare.--views FILE.dashmette i blocchisourceeviewdi quella dashboard davanti all'SQL, per i modelli i cui dataset sono definiti lì.
Una richiesta è fatta di:
| Opzione | Significa |
|---|---|
--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 SQL | Una 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 N | Al 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:
| Kind | Perché |
|---|---|
metric_unknown_name | Nessuna metrica o campo ha quel nome. L'hint indica il più vicino |
metric_fanout | Il 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_grain | Le metriche contano dataset diversi. Chiedi ciascuna in una query a sé |
metric_ambiguous_path, metric_no_path | Il modello non indica esattamente un modo per unire i dataset |
metric_window_unsupported, metric_nested_aggregate, metric_not_aggregate | La metrica è una funzione finestra, annida aggregati o non è un aggregato |
metric_no_dialect | La 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_refused | Un --where contiene più di un'espressione |
metric_missing | Non è stato dato alcun --metric |
metric_no_dataset | Nessuna 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_invalid | Il 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.
