Aller au contenu

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 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, 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.

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. 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 ​

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. Il accepte les options --database, --format et --restricted 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 :

OptionSignifie
--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 SQLUne 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 NAu 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 :

KindPourquoi
metric_unknown_nameAucune métrique ni aucun champ ne porte ce nom. Le hint donne le plus proche
metric_fanoutLe 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_grainLes métriques comptent des jeux de données différents. Demandez chacune dans sa propre requête
metric_ambiguous_path, metric_no_pathLe modèle n'indique pas exactement une façon de joindre les jeux de données
metric_window_unsupported, metric_nested_aggregate, metric_not_aggregateLa métrique est une fonction de fenêtre, imbrique des agrégats, ou n'est pas un agrégat
metric_no_dialectLa métrique n'a pas d'expression dans un dialecte que DuckLocal lit
metric_bad_grainUne granularité a été demandée pour un champ qui n'est pas temporel
metric_filter_refusedUn --where contient plus d'une expression
metric_missingAucun --metric n'a été donné
metric_no_datasetAucune 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_invalidLe 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.

Publié sous licence Apache-2.0.