Métriques sémantiques
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, 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 interroge par métrique au lieu d'écrire le SQL lui-même.
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
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 unesource(le nom d'une table ou d'une vue), uneprimary_keyfacultative et desfields. Un champ marquédimension: {is_time: true}est un champ temporel.relationships:from,to,from_columnsetto_columns.metrics: à la racine du modèle, ou sous un jeu de données, où elles s'appellentdataset.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, compte la vue events que définit le tableau de bord de l'exemple :
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
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.yamldans son dossier et jusqu'à trois dossiers au-dessus. Il s'arrête à un dossier qui contientducklocal-project.json, la marque d'un projet portable. 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
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 dataLe premier argument est un fichier de modèle, ou un dossier qui contient model.ossie.yaml. Sans lui, le dossier courant est utilisé.
ducklocal metricsaffiche le vocabulaire du modèle en JSON :model, avec sonsha256et sonai_context.- Chaque métrique, avec sa
description, sessynonymsetqueryable. Une métrique interrogeable nomme sabase, le jeu de données qu'elle compte ; les autres ont unproblemqui dit pourquoi. - Chaque champ sous la forme
dataset.field, avecis_time. - Les relations, chacune avec sa
cardinality:many_to_onequand lesto_columnssont une clé deto,unknownsinon.
metrics compileaffiche le SQL d'une requête, avec ses colonnes, son jeu de données de base, ses jointures et lesql_sha256du SQL. Il ne lit aucune donnée.metrics querycompile la requête et exécute le SQL commeducklocal query. Il accepte les options--database,--formatet--restricteddequery, et ajoute un objetsemanticavec le SQL compilé, la requête et lesha256du modèle : c'est ce qu'il faut citer.--views FILE.dashplace les blocssourceetviewde 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
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
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 |
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.
