Ir al contenido

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 una source (el nombre de una tabla o vista), un primary_key opcional y fields. Un campo marcado con dimension: {is_time: true} es un campo de tiempo.
  • relationships: from, to, from_columns y to_columns.
  • metrics: en la raíz del modelo, o bajo un conjunto de datos, donde se llaman dataset.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:

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

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.yaml en su carpeta y hasta tres carpetas por encima. Se detiene en una carpeta que contenga ducklocal-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 ​

bash
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 data

El primer argumento es un archivo de modelo, o una carpeta que contiene model.ossie.yaml. Si lo omites, se usa la carpeta actual.

  • ducklocal metrics imprime el vocabulario del modelo en JSON:
    • model, con su sha256 y su ai_context.
    • Cada métrica, con su description, sus synonyms y queryable. Una métrica consultable nombra su base, el conjunto de datos que cuenta; la que no lo es tiene un problem que dice por qué.
    • Cada campo como dataset.field, con is_time.
    • Las relaciones, cada una con su cardinality: many_to_one cuando las to_columns son una clave de to, unknown en otro caso.
  • metrics compile imprime el SQL de una petición, con sus columnas, su conjunto de datos base, sus uniones y el sql_sha256 del SQL. No lee datos.
  • metrics query compila la petición y ejecuta el SQL como lo hace ducklocal query. Acepta las opciones --database, --format y --restricted de query, y añade un objeto semantic con el SQL compilado, la petición y el sha256 del modelo, que es lo que hay que citar. --views FILE.dash pone los bloques source y view de ese panel delante del SQL, para los modelos cuyos conjuntos de datos se definen ahí.

Una petición se compone de:

OpciónSignifica
--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 SQLUna 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 NComo 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:

KindPor qué
metric_unknown_nameNinguna métrica ni campo tiene ese nombre. El hint da el más parecido
metric_fanoutEl 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_grainLas métricas cuentan conjuntos de datos distintos. Pide cada una en su propia consulta
metric_ambiguous_path, metric_no_pathEl modelo no indica exactamente una forma de unir los conjuntos de datos
metric_window_unsupported, metric_nested_aggregate, metric_not_aggregateLa métrica es una función de ventana, anida agregados o no es un agregado
metric_no_dialectLa métrica no tiene una expresión en un dialecto que DuckLocal lea
metric_bad_grainSe pidió una granularidad para un campo que no es de tiempo
metric_filter_refusedUn --where es más de una expresión
metric_missingNo se dio ningún --metric
metric_no_datasetNinguna 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_invalidEl 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.

Publicado bajo la licencia Apache-2.0.