# Métricas semánticas

> Define tus métricas una vez en un modelo de Apache Ossie y ejecútalas desde la barra lateral de DuckLocal o con la CLI ducklocal metrics, compiladas en un único SELECT de DuckDB.

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

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](https://ossie.apache.org/),
`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](cli.md#install-the-official-skill) pregunta por métricas en
lugar de escribir el SQL por su cuenta.

::: info 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 {#write-a-model}

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](example-cloudtrail.md), 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.

## Ejecuta una métrica desde la barra lateral {#sidebar}

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](agent-workflows.md). 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 {#cli}

```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`](cli.md#query-options). Acepta las opciones `--database`,
  `--format` y [`--restricted`](agent-workflows.md) 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ó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 {#compiled-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 {#refusals}

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](#write-a-model) |

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.
