# Metriche semantiche

> Definisci le metriche una volta in un modello Apache Ossie, poi eseguile dalla barra laterale di DuckLocal o con la CLI ducklocal metrics, compilate in un'unica SELECT DuckDB.

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

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](https://ossie.apache.org/), `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](cli.md#install-the-official-skill) chiede per metrica invece
di scrivere l'SQL da sé.

::: info 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 {#write-a-model}

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](example-cloudtrail.md), 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.

## Esegui una metrica dalla barra laterale {#sidebar}

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](agent-workflows.md). 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 {#cli}

```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`](cli.md#query-options). Accetta le opzioni `--database`,
  `--format` e [`--restricted`](agent-workflows.md) 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:

| 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 {#compiled-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 {#refusals}

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](#write-a-model) |

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.
