# Métriques sémantiques

> Définissez vos métriques une fois dans un modèle Apache Ossie, puis exécutez-les depuis la barre latérale de DuckLocal ou la CLI ducklocal metrics, compilées en un seul SELECT DuckDB.

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

Un modèle sémantique fixe une fois pour toutes ce que signifie un nombre : ce
qui compte comme une erreur, quels appels sont des changements d'accès,
comment deux tables se joignent. DuckLocal lit le modèle dans un fichier
[Apache Ossie](https://ossie.apache.org/), `model.ossie.yaml`, et transforme
chaque requête (ces métriques, par ces champs, sous ces conditions) en un seul
`SELECT` DuckDB. La même requête sur le même modèle se compile toujours en le
même SQL : chaque graphique, chaque réponse et chaque agent qui utilise
`error_rate` parle de la même chose.

Vous pouvez exécuter une métrique depuis la barre latérale de la fenêtre, ou
avec `ducklocal metrics` en ligne de commande. Un agent équipé de la
[compétence officielle](cli.md#install-the-official-skill) interroge par
métrique au lieu d'écrire le SQL lui-même.

::: info Plus récent que 0.4.1
Les métriques sémantiques sont sur la branche `main` de DuckLocal et sortiront
avec la prochaine version. 0.4.1 ne les a pas.
:::

## Écrire un modèle {#write-a-model}

Placez `model.ossie.yaml` à la racine d'un projet, à côté de ses tableaux de
bord ou au-dessus. DuckLocal lit la forme plate d'Ossie 0.2 :

- `datasets` : chacun a une `source` (le nom d'une table ou d'une vue), une
  `primary_key` facultative et des `fields`. Un champ marqué
  `dimension: {is_time: true}` est un champ temporel.
- `relationships` : `from`, `to`, `from_columns` et `to_columns`.
- `metrics` : à la racine du modèle, ou sous un jeu de données, où elles
  s'appellent `dataset.metric`.

Chaque expression est donnée par dialecte SQL. DuckLocal prend le premier de
`DUCKDB`, `OSSIE_SQL_2026` et `ANSI_SQL` que l'expression possède, et le
parseur de DuckDB la lit. Ce modèle abrégé, tiré de
l'[exemple CloudTrail](example-cloudtrail.md), compte la vue `events` que
définit le tableau de bord de l'exemple :

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

Une métrique peut être construite à partir d'autres métriques, comme
`error_rate`. Un champ ou une métrique sans dialecte utilisable, ou que DuckDB
ne sait pas analyser, est listé avec le problème, et le reste du modèle
fonctionne toujours. Un modèle avec un nom en double, une relation vers un jeu
de données inexistant ou une `source` qui n'est pas un nom de table est refusé
en entier.

## Exécuter une métrique depuis la barre latérale {#sidebar}

L'onglet Schéma de la barre latérale a une section **Métriques**, sous
**Tableaux de bord**. Elle liste les modèles trouvés à côté des tableaux de
bord ouverts récemment :

- Pour chaque tableau de bord, DuckLocal cherche `model.ossie.yaml` dans son
  dossier et jusqu'à trois dossiers au-dessus. Il s'arrête à un dossier qui
  contient `ducklocal-project.json`, la marque d'un
  [projet portable](agent-workflows.md). Un modèle trouvé depuis plusieurs
  tableaux de bord n'est listé qu'une fois.
- Sous chaque modèle, une ligne par métrique. Survolez le modèle pour voir son
  chemin et le tableau de bord d'où viennent ses jeux de données. Survolez une
  métrique pour voir sa description et ses synonymes.
- Une métrique qui ne peut pas être interrogée est marquée **non
  interrogeable**. Survolez-la pour savoir pourquoi.

Cliquez sur une métrique, ou sur son bouton ▶ : DuckLocal la compile, place le
SQL dans l'éditeur de requêtes actif et l'exécute. Le bouton 📈 l'exécute
ventilée par jour, sur le premier champ temporel du jeu de données qu'elle
compte.

Le SQL commence par une ligne qui dit d'où vient le nombre, par exemple
`-- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …)`.
Quand les jeux de données du modèle viennent des blocs `source` et `view` d'un
tableau de bord, ces blocs sont placés devant la requête sous forme de CTE. La
requête s'exécute alors sur la connexion de la fenêtre, que le tableau de bord
soit ouvert ou non, et vous pouvez la modifier comme n'importe quelle autre.

## Exécuter une métrique en ligne de commande {#cli}

```bash
ducklocal metrics                       # le modèle du dossier courant
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
```

Le premier argument est un fichier de modèle, ou un dossier qui contient
`model.ossie.yaml`. Sans lui, le dossier courant est utilisé.

- `ducklocal metrics` affiche le vocabulaire du modèle en JSON :
  - `model`, avec son `sha256` et son `ai_context`.
  - Chaque métrique, avec sa `description`, ses `synonyms` et `queryable`.
    Une métrique interrogeable nomme sa `base`, le jeu de données qu'elle
    compte ; les autres ont un `problem` qui dit pourquoi.
  - Chaque champ sous la forme `dataset.field`, avec `is_time`.
  - Les relations, chacune avec sa `cardinality` : `many_to_one` quand les
    `to_columns` sont une clé de `to`, `unknown` sinon.
- `metrics compile` affiche le SQL d'une requête, avec ses colonnes, son jeu
  de données de base, ses jointures et le `sql_sha256` du SQL. Il ne lit
  aucune donnée.
- `metrics query` compile la requête et exécute le SQL comme
  [`ducklocal query`](cli.md#query-options). Il accepte les options
  `--database`, `--format` et [`--restricted`](agent-workflows.md) de `query`,
  et ajoute un objet `semantic` avec le SQL compilé, la requête et le `sha256`
  du modèle : c'est ce qu'il faut citer. `--views FILE.dash` place les blocs
  `source` et `view` de ce tableau de bord devant le SQL, pour les modèles dont
  les jeux de données y sont définis.

Une requête se compose de :

| Option | Signifie |
| --- | --- |
| `--metric NAME[,NAME]` | Les métriques à calculer. Répétable |
| `--by REF[,REF]` | Les champs de ventilation, sous la forme `dataset.field`. Un nom de champ seul suffit quand un seul jeu de données l'a. `dataset.field:GRAIN` tronque un champ temporel à `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter` ou `year`. Répétable |
| `--where SQL` | Une condition. Une condition sur des champs filtre les lignes (`WHERE`) ; une condition sur des noms de métriques, comme `"error_count > 5"`, filtre les groupes (`HAVING`). Répétable ; toutes s'appliquent |
| `--order-by NAME[:desc]` | Une colonne de sortie, ou le `dataset.field` dont elle vient. Par défaut, les colonnes de `--by`, dans l'ordre croissant |
| `--limit N` | Au plus N lignes |

## Comment une requête devient du SQL {#compiled-sql}

Le SQL compilé est un seul `SELECT` sur le jeu de données que comptent les
métriques. Il est joint par `LEFT JOIN`, le long des relations plusieurs-à-un,
à chaque jeu de données que nomme la requête : une ligne sans correspondance
compte quand même, sous `NULL`. Les colonnes de sortie portent le nom du champ
(`ip`, ou `event_time_day` pour une granularité) ou de la métrique. Quand deux
noms entrent en conflit, ils sont qualifiés (`events.user_name`). Une condition
sur un champ va dans `WHERE`, une condition sur une métrique dans `HAVING`.
Chaque `--where` est une seule expression : une sous-requête, une deuxième
instruction ou quoi que ce soit autour de l'expression est refusé.

## Quand une requête est refusée {#refusals}

DuckLocal refuse une requête à laquelle il ne peut pas répondre exactement,
plutôt que de renvoyer un nombre peut-être faux. Un refus sort avec le code 2,
et l'erreur indique un `kind` :

| Kind | Pourquoi |
| --- | --- |
| `metric_unknown_name` | Aucune métrique ni aucun champ ne porte ce nom. Le `hint` donne le plus proche |
| `metric_fanout` | Le champ est du côté « plusieurs » d'une relation, et la jointure compterait des lignes plusieurs fois. Ventilez par un champ du jeu de données de la métrique |
| `metric_multi_grain` | Les métriques comptent des jeux de données différents. Demandez chacune dans sa propre requête |
| `metric_ambiguous_path`, `metric_no_path` | Le modèle n'indique pas exactement une façon de joindre les jeux de données |
| `metric_window_unsupported`, `metric_nested_aggregate`, `metric_not_aggregate` | La métrique est une fonction de fenêtre, imbrique des agrégats, ou n'est pas un agrégat |
| `metric_no_dialect` | La métrique n'a pas d'expression dans un dialecte que DuckLocal lit |
| `metric_bad_grain` | Une granularité a été demandée pour un champ qui n'est pas temporel |
| `metric_filter_refused` | Un `--where` contient plus d'une expression |
| `metric_missing` | Aucun `--metric` n'a été donné |
| `metric_no_dataset` | Aucune métrique de la requête ne lit de colonne, donc il n'y a pas de jeu de données à compter. Qualifiez l'agrégat dans le modèle : `COUNT(events.event_id)`, pas `COUNT(*)` |
| `model_invalid` | Le modèle lui-même est erroné, comme décrit dans [Écrire un modèle](#write-a-model) |

Un fichier de modèle illisible sort avec le code 1 et le kind
`model_not_found`. Quand une question demande du SQL que le modèle ne sait pas
exprimer, écrivez-le avec `ducklocal query`, et précisez que ce nombre n'est
pas l'une des métriques du modèle.
