Métricas semánticas
Un modelo semántico fija una sola vez qué significa un número: qué cuenta como error, qué llamadas son cambios de acceso, cómo se unen dos tablas. DuckLocal lee el modelo de un archivo de Apache Ossie, model.ossie.yaml, y convierte cada petición (estas métricas, por estos campos, con estas condiciones) en un único SELECT de DuckDB. La misma petición sobre el mismo modelo siempre se compila en el mismo SQL, así que cada gráfico, respuesta y agente que usa error_rate habla de lo mismo.
Puedes ejecutar una métrica desde la barra lateral de la ventana, o con ducklocal metrics en la línea de comandos. Un agente con la habilidad oficial pregunta por métricas en lugar de escribir el SQL por su cuenta.
Posterior a 0.4.1
Las métricas semánticas están en la rama main de DuckLocal y llegarán con la próxima versión. 0.4.1 no las tiene.
Escribe un modelo
Pon model.ossie.yaml en la raíz de un proyecto, junto a sus paneles o por encima. DuckLocal lee la forma plana de Ossie 0.2:
datasets: cada uno tiene unasource(el nombre de una tabla o vista), unprimary_keyopcional yfields. Un campo marcado condimension: {is_time: true}es un campo de tiempo.relationships:from,to,from_columnsyto_columns.metrics: en la raíz del modelo, o bajo un conjunto de datos, donde se llamandataset.metric.
Cada expresión se escribe por dialecto SQL. DuckLocal usa el primero de DUCKDB, OSSIE_SQL_2026 y ANSI_SQL que tenga la expresión, y la lee el propio parser de DuckDB. Este modelo abreviado, del ejemplo de CloudTrail, cuenta la vista events que define el panel del ejemplo:
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 métrica puede construirse a partir de otras, como error_rate. Un campo o una métrica sin dialecto utilizable, o que DuckDB no puede analizar, aparece con el problema, y el resto del modelo sigue funcionando. Un modelo con un nombre duplicado, una relación con un conjunto de datos que no existe o una source que no es un nombre de tabla se rechaza entero.
Ejecuta una métrica desde la barra lateral
La pestaña Esquema de la barra lateral tiene una sección Métricas, debajo de Paneles. Lista los modelos que encuentra junto a los paneles que has abierto recientemente:
- Para cada panel, DuckLocal busca
model.ossie.yamlen su carpeta y hasta tres carpetas por encima. Se detiene en una carpeta que contengaducklocal-project.json, la marca de un proyecto portátil. Un modelo encontrado desde varios paneles se lista una sola vez. - Bajo cada modelo hay una fila por métrica. Pasa el puntero sobre el modelo para ver su ruta y el panel del que vienen sus conjuntos de datos. Pásalo sobre una métrica para ver su descripción y sus sinónimos.
- Una métrica que no se puede consultar aparece marcada como no consultable. Pasa el puntero por encima para ver por qué.
Haz clic en una métrica, o en su botón ▶, y DuckLocal la compila, pone el SQL en el editor de consultas activo y lo ejecuta. El botón 📈 la ejecuta desglosada por día, sobre el primer campo de tiempo del conjunto de datos que cuenta.
El SQL empieza con una línea que dice de dónde sale el número, por ejemplo -- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …). Cuando los conjuntos de datos del modelo vienen de los bloques source y view de un panel, esos bloques van delante de la consulta como CTE. La consulta se ejecuta entonces en la propia conexión de la ventana, esté o no abierto el panel, y puedes editarla como cualquier otra.
Ejecuta una métrica desde la línea de comandos
ducklocal metrics # el modelo de la carpeta actual
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 dataEl primer argumento es un archivo de modelo, o una carpeta que contiene model.ossie.yaml. Si lo omites, se usa la carpeta actual.
ducklocal metricsimprime el vocabulario del modelo en JSON:model, con susha256y suai_context.- Cada métrica, con su
description, sussynonymsyqueryable. Una métrica consultable nombra subase, el conjunto de datos que cuenta; la que no lo es tiene unproblemque dice por qué. - Cada campo como
dataset.field, conis_time. - Las relaciones, cada una con su
cardinality:many_to_onecuando lasto_columnsson una clave deto,unknownen otro caso.
metrics compileimprime el SQL de una petición, con sus columnas, su conjunto de datos base, sus uniones y elsql_sha256del SQL. No lee datos.metrics querycompila la petición y ejecuta el SQL como lo haceducklocal query. Acepta las opciones--database,--formaty--restricteddequery, y añade un objetosemanticcon el SQL compilado, la petición y elsha256del modelo, que es lo que hay que citar.--views FILE.dashpone los bloquessourceyviewde ese panel delante del SQL, para los modelos cuyos conjuntos de datos se definen ahí.
Una petición se compone de:
| Opción | Significa |
|---|---|
--metric NAME[,NAME] | Las métricas que calcular. Repetible |
--by REF[,REF] | Campos por los que desglosar, como dataset.field. Basta con el nombre del campo cuando solo un conjunto de datos lo tiene. dataset.field:GRAIN trunca un campo de tiempo a second, minute, hour, day, week, month, quarter o year. Repetible |
--where SQL | Una condición. Una condición sobre campos filtra filas (WHERE); una sobre nombres de métricas, como "error_count > 5", filtra grupos (HAVING). Repetible; se aplican todas |
--order-by NAME[:desc] | Una columna de salida, o el dataset.field del que salió. Por defecto, las columnas de --by, en orden ascendente |
--limit N | Como máximo N filas |
Cómo una petición se convierte en SQL
El SQL compilado es un único SELECT sobre el conjunto de datos que cuentan las métricas. Se une con LEFT JOIN, a lo largo de relaciones de muchos a uno, con cada conjunto de datos que nombra la petición, así que una fila sin coincidencia también cuenta, bajo NULL. Las columnas de salida se llaman como el campo (ip, o event_time_day con una granularidad) o la métrica. Cuando dos chocan, se califican (events.user_name). Una condición sobre un campo va a WHERE y una sobre una métrica a HAVING. Cada --where es una sola expresión: una subconsulta, una segunda sentencia o cualquier cosa alrededor de la expresión se rechaza.
Cuando se rechaza una petición
DuckLocal rechaza una petición que no puede responder con exactitud, en lugar de devolver un número que podría ser erróneo. Un rechazo sale con código 2, y el error indica un kind:
| Kind | Por qué |
|---|---|
metric_unknown_name | Ninguna métrica ni campo tiene ese nombre. El hint da el más parecido |
metric_fanout | El campo está en el lado «muchos» de una relación, y unirlo contaría filas más de una vez. Desglosa por un campo del propio conjunto de datos de la métrica |
metric_multi_grain | Las métricas cuentan conjuntos de datos distintos. Pide cada una en su propia consulta |
metric_ambiguous_path, metric_no_path | El modelo no indica exactamente una forma de unir los conjuntos de datos |
metric_window_unsupported, metric_nested_aggregate, metric_not_aggregate | La métrica es una función de ventana, anida agregados o no es un agregado |
metric_no_dialect | La métrica no tiene una expresión en un dialecto que DuckLocal lea |
metric_bad_grain | Se pidió una granularidad para un campo que no es de tiempo |
metric_filter_refused | Un --where es más de una expresión |
metric_missing | No se dio ningún --metric |
metric_no_dataset | Ninguna métrica de la petición lee una columna, así que no hay conjunto de datos que contar. Califica el agregado en el modelo: COUNT(events.event_id), no COUNT(*) |
model_invalid | El propio modelo es erróneo, como se describe en Escribe un modelo |
Un archivo de modelo que no se puede leer sale con código 1 y kind model_not_found. Cuando una pregunta necesita SQL que el modelo no puede expresar, escríbelo con ducklocal query y di que ese número no es una de las métricas del modelo.
