# Paneles (.dash)

> Crea paneles de DuckLocal como archivos .dash de SQL de DuckDB: gráficos, filtros cruzados, comentarios que un agente de IA puede responder y validación con ducklocal check.

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

Un archivo `.dash` describe un panel como datos: los bloques **source** nombran archivos de datos, los bloques **query** contienen SQL, los bloques **plot** dibujan los resultados y los bloques **filter** permiten que una pulsación en un gráfico acote los demás. No hay código que escribir. Tanto las personas como los agentes de IA pueden crear el archivo, revisarlo en un diff y validarlo antes de que nadie lo abra.

Un archivo `.dash` dibuja gráficos, tablas, números y mapas estándar a partir de consultas guardadas. Su formato de texto plano también lo hace útil para trabajar con un agente de IA: el agente escribe o edita el archivo, `ducklocal check` verifica que se ejecuta y tú [comentas los gráficos](#review-with-comments) para pedir cambios.

## Un ejemplo completo {#a-complete-example}

Este panel consulta el [archivo de ejemplo del tutorial](tutorial.md#sample-file). Descarga [sales.dash](https://ducklocal.app/docs/samples/sales.dash) en el mismo directorio que `sales.csv` y ábrelo.

```hcl
source "sales" {
  path = "sales.csv"
}

query "totals" {
  sql = <<SQL
    SELECT round(sum(revenue), 2) AS revenue, sum(orders) AS orders,
           count(DISTINCT region) AS regions
    FROM sales
    WHERE $channel
  SQL
}

query "by_channel" {
  sql = <<SQL
    SELECT channel, round(sum(revenue), 2) AS revenue
    FROM sales
    GROUP BY channel
    ORDER BY revenue DESC
  SQL
}

query "daily" {
  sql = <<SQL
    SELECT date, region, round(sum(revenue), 2) AS revenue
    FROM sales
    WHERE $channel
    GROUP BY date, region
    ORDER BY date
  SQL
}

plot "revenue" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  width = 4
}

plot "orders" {
  type  = "card"
  query = query.totals
  value = orders
  title = "Orders"
  width = 4
}

plot "regions" {
  type  = "card"
  query = query.totals
  value = regions
  title = "Regions"
  width = 4
}

plot "revenue_by_channel" {
  type  = "bar"
  query = query.by_channel
  x     = channel
  y     = revenue
  title = "Revenue by channel"
  width = 5
}

plot "daily_revenue" {
  type   = "line"
  query  = query.daily
  x      = date
  y      = revenue
  series = region
  title  = "Daily revenue, per region"
  width  = 7
}

plot "daily_table" {
  type  = "table"
  query = query.daily
  title = "The numbers behind it"
}

filter "channel" {
  plot = plot.revenue_by_channel
}
```

Se abre con tres números en la parte superior, el gráfico de barras y el de líneas uno al lado del otro, y la tabla debajo. Cada consulta se ejecuta una vez, por muchos gráficos que la dibujen: `totals` alimenta las tres tarjetas y `daily` alimenta tanto el gráfico de líneas como la tabla. Pulsa una barra en **Revenue by channel** y las tarjetas, el gráfico de líneas y la tabla se acotan a ese canal; el gráfico de barras se queda entero, para que puedas pulsar otra.

## Abrir un panel

Cualquiera de estas acciones abre un archivo `.dash` como pestaña de panel, junto a tus consultas:

- el **+** al final de la fila de pestañas y luego **Abrir panel**;
- arrastrar el archivo a la ventana;
- nombrarlo en la línea de comandos: `ducklocal sales.dash`;
- desde un script o un agente, en la ventana que ya está en ejecución:
  `ducklocal open sales.dash` (consulta la [guía de la CLI](cli.md#show-work-in-the-running-window)).

Los gráficos se colocan en una cuadrícula de 12 columnas: cada uno ocupa su [`width`](#layout), los gráficos llenan una fila de izquierda a derecha y un gráfico que ya no cabe empieza la fila siguiente. Arrastra los separadores entre filas para cambiar su tamaño; un panel más alto que la pestaña se desplaza. Un gráfico que no puede dibujarse —su consulta falló o falta una columna— muestra el motivo en su propio recuadro, y el resto del panel se sigue dibujando. Los paneles abiertos vuelven en el siguiente arranque, y los abiertos recientemente aparecen en **Paneles** en la barra lateral.

Pasa el cursor por un gráfico para ver sus controles en la esquina superior derecha:

- **SQL** convierte el gráfico en el SQL que ejecutó su consulta por última vez —con sus fuentes y las selecciones de filtro actuales ya puestas, así que se ejecuta tal cual—, con **Copiar** y **Abrir en una pestaña de consulta**. **Gráfico** lo devuelve a su forma normal.
- La burbuja de diálogo abre los [comentarios](#review-with-comments) del gráfico.
- **Ampliar este gráfico** lo expande hasta llenar la pestaña del panel. Usa **Volver al panel (Esc)** o pulsa **Esc** para volver a la cuadrícula.

La vista SQL resalta la sintaxis. Haz clic derecho en una celda de una tabla del panel para copiar la celda, su fila separada por tabuladores o su columna en el orden mostrado.

Pulsa el encabezado de una columna de un gráfico `table` para ordenarla: descendente, ascendente y de vuelta al orden de la consulta. Los números se ordenan como números y `NULL` va al final; una fila elegida para un [filtro](#filters) sigue elegida tras una ordenación.

**Ver especificación** en la barra de herramientas cambia la pestaña a un editor del archivo, con resaltado de sintaxis (el SQL de los heredocs se colorea como en el editor SQL), autocompletado y diagnósticos en línea. **Guardar** o **⌘S** lo escribe y vuelve a dibujar. Si el archivo guardado no pasa la validación, la pestaña conserva el último panel que funcionaba y muestra el error encima. Lo mismo ocurre cuando otro programa cambia el archivo. **Volver al panel** vuelve a los gráficos. **Recargar** relee el archivo y ejecuta de nuevo todas las consultas.

## Revisar con comentarios {#review-with-comments}

Los comentarios te permiten revisar un panel como revisarías un documento y pasar los cambios a un agente de IA. La reflexión de producto que hay detrás de este flujo se cuenta en [What Claude Dashboards taught me about DuckLocal](https://ducklocal.app/blog/claude-dashboards-ducklocal/).

**En la ventana**, pasa el cursor por un gráfico y pulsa la burbuja de diálogo. Se abre una tarjeta sobre el panel, con el título del gráfico citado, los hilos que ya tiene y un cuadro para escribir. Escribe qué debería cambiar —*"ordena estos, el canal más grande primero"*— y pulsa **Comentar** (o **⌘/Ctrl+Enter**). Cada hilo tiene **Responder** y **Resolver**; un hilo resuelto se queda, atenuado, hasta que alguien le responde. Un gráfico con hilos abiertos mantiene a la vista una burbuja con su cuenta, para que veas de un vistazo qué está pendiente.

**El agente** lee y responde los hilos con
[`ducklocal comments`](cli.md#review-comments-on-a-dashboard), sin necesidad de ventana:

```bash
ducklocal comments sales.dash
```

```json
{
  "file": "sales.dash",
  "comments_file": "sales.dash.comments.json",
  "open": 1,
  "threads": [
    {
      "id": "c1",
      "plot": "revenue_by_channel",
      "plot_title": "Revenue by channel",
      "plot_query": "by_channel",
      "plot_lines": [68, 75],
      "plot_missing": false,
      "resolved": false,
      "comments": [
        { "author": "user", "text": "Rank these, biggest channel first", "at": "2026-10-10T14:03:00+08:00" }
      ]
    }
  ]
}
```

Cada hilo nombra su gráfico, la consulta del gráfico y las líneas de su bloque `plot` en el archivo, así que el agente sabe qué editar. Cambia la especificación, ejecuta `ducklocal check` y responde:

```bash
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" --resolve
```

La ventana vigila ambos archivos. En menos de un segundo el gráfico se redibuja desde la especificación editada y la respuesta del agente aparece en su hilo, marcada como **Agente**.

Los hilos se guardan junto al panel, en `NAME.dash.comments.json`, así que viajan con él como lo hacen sus archivos `source`. Son notas de trabajo, no parte del panel: déjalos fuera del control de versiones o borra el archivo cuando termine la revisión.

La [habilidad oficial del agente](cli.md#install-the-official-skill) enseña este bucle, así que a un agente que la tenga solo hay que decirle *"atiende los comentarios de sales.dash"*.

::: info Nuevo en 0.4.0
Un agente puede [proponer un cambio](agent-workflows.md#propose) en vez de editar el archivo. La pestaña ofrece entonces **Revisar**, con el diff y las comprobaciones, y solo tú puedes aplicarlo.
:::

### Ver a un agente trabajando {#agent-presence}

Mientras un agente ejecuta `check`, `comments` o `presence` para este panel abierto, su nombre aparece en la esquina, con la marca de su creador —Claude, OpenAI, Gemini, Cursor, DeepSeek— o su inicial. Pulsa el nombre para ver el registro de la sesión. Cuando edita el archivo, los gráficos cambiados y añadidos siguen marcados (**Claude cambió esto**, **Claude añadió esto**) hasta que los hayas tenido a la vista un momento; un gráfico eliminado deja un aviso que puedes descartar.

Un agente puede anunciar su siguiente edición con `ducklocal presence sales.dash --doing editing --plot revenue_by_channel`. Ese gráfico recibe un anillo; un nombre de gráfico que aún no existe recibe un marcador de posición debajo del panel. La sesión termina tras 30 segundos sin actividad o con un `--doing idle` explícito. Un agente que ha terminado se queda en la esquina mientras un hilo que respondió espera tu respuesta, con la cuenta en su avatar. Los comentarios registran qué agente los escribió y muestran su marca. La [referencia de la CLI](cli.md#agent-presence) explica las opciones. Estos indicadores muestran actividad local; no envían trabajo a un agente.

## Bloques {#blocks}

Un archivo es una secuencia de bloques, cada uno con un tipo, un nombre entre comillas y un cuerpo:

```hcl
source "name" { ... }
view "name" { ... }
query "name" { ... }
plot "name" { ... }
filter "name" { ... }
dashboard "name" { ... }
```

Los nombres deben ser únicos dentro de su tipo: dos consultas no pueden compartir un nombre, y dos gráficos tampoco, pero una consulta y un gráfico sí.

::: info Nuevo en 0.4.1
Un bloque `view` contiene el modelado que comparten varias consultas, un `filter` puede reunir varios valores (`multiple = true`), un gráfico `timeline` coloca los eventos según su distancia real en el tiempo y un bloque `dashboard` fija la zona en la que se muestra cada `TIMESTAMPTZ`.
:::

### source

| Atributo | Obligatorio | Valor |
| --- | --- | --- |
| `path` | sí | Un archivo `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.jsonl` o `.ndjson` (también comprimido con gzip, como `.csv.gz`), o un glob de ellos (`exports/orders-*.csv`) leído como una sola relación |

Una fuente da a los archivos de datos un nombre con el que las consultas los leen: con `source "sales"`, una consulta dice `FROM sales`. La ruta es **relativa al archivo `.dash`**, no al lugar desde donde se inició DuckLocal, así que un panel y sus datos pueden moverse juntos; `~` y las rutas absolutas también funcionan.

Una fuente nunca toca la conexión: se convierte en un `WITH sales AS (…)` delante de cada consulta que la nombra, así que no aparece nada en la barra lateral, nada sobrevive a la pestaña, y una fuente oculta una tabla del mismo nombre solo para las consultas de este panel. El nombre debe ser un identificador simple (letras, dígitos y `_`). Un libro no puede ser una fuente; ábrelo en DuckLocal y consulta la tabla en la que se convierte.

### view

Una vista contiene el modelado que comparten varias consultas, escrito una sola vez. Tiene un atributo `sql`, con las mismas reglas que el de una consulta, y toda consulta que la nombra la lee como una tabla:

```hcl
view "events" {
  sql = <<SQL
    SELECT r.eventName AS event_name, r.eventTime AS event_time
    FROM (SELECT unnest(Records) AS r FROM trail)
  SQL
}

query "totals" {
  sql = "SELECT count(*) AS events, count(DISTINCT event_name) AS kinds FROM events"
}
```

Una vista lee las fuentes y las vistas definidas por encima de ella, comparte nombres con las fuentes y no admite `$filter`: lee el filtro en las consultas que leen la vista. Como una fuente, se pone delante de cada consulta que la nombra y no crea nada en la conexión. Recurre a una cuando, si no, las consultas repetirían el mismo CTE, como al aplanar JSON anidado.

### query

| Atributo | Obligatorio | Valor |
| --- | --- | --- |
| `sql` | sí | Una sentencia SQL de solo lectura, como [heredoc](#heredocs) o como cadena |

Un bloque de consulta contiene `sql` y nada más. Puede leer `$name` para un [filtro](#filters).

### plot

| Atributo | Para | Valor |
| --- | --- | --- |
| `type` | todos, obligatorio | `"line"`, `"bar"`, `"stacked_bar"`, `"area"`, `"scatter"`, `"pie"`, `"heatmap"`, `"histogram"`, `"map"`, `"timeline"`, `"table"`, `"card"` o `"text"` — una cadena entre comillas |
| `query` | todos excepto `text`, obligatorio | Una referencia a un bloque de consulta: `query.by_channel` |
| `x` | gráficos, obligatorio | La columna del eje horizontal; las porciones de un `pie`; el número que agrupa un `histogram`; el tiempo de un `timeline` |
| `y` | gráficos, obligatorio | La columna que se dibuja; debe ser numérica. Los tamaños de las porciones de un `pie`. Un `histogram` y un `timeline` no lo usan |
| `series` | `line`, `bar`, `stacked_bar`, `area`, `scatter`, `heatmap`, `timeline` | Una columna cuyos valores dividen las filas en una serie cada uno; las filas de un `heatmap`; los carriles de un `timeline` |
| `title` | todos | Un encabezado para el gráfico, como cadena entre comillas; la etiqueta de una tarjeta |
| `width` | todos | Cuántas de las 12 columnas de la cuadrícula ocupa el gráfico, `1`–`12`. Por defecto 12, o 3 para una tarjeta |
| `value` | `card` | La columna que se muestra, de la primera fila. Por defecto: la primera columna |
| `note` | `card` | Texto bajo el valor: una cadena entre comillas o un nombre de columna sin más para leerlo de la primera fila |
| `tone` | `card` | `"accent"`, `"good"`, `"warning"` o `"critical"`; colorea la línea superior y el valor |
| `format` | gráficos y `card` | Qué son los números: consulta [Formatos de número y cambio](#number-formats-and-change). Un `map` o un `table` no lo usan |
| `delta` | `card` | Una columna numérica con el cambio, que se muestra bajo el valor |
| `delta_format` | `card` | Un formato para el cambio. Por defecto: el de la tarjeta |
| `down_is_good` | `card` | `true` hace que una bajada sea verde y una subida roja, para costes, latencia o bajas de clientes |
| `description` | todos, **0.4.0+** | Qué muestra el gráfico y cómo leerlo; aparece al pasar el cursor por un ⓘ junto al título |
| `text` | `text` | Texto del cuerpo como cadena o heredoc; indica `title`, `text` o ambos, sin `query` |
| `caption` | `timeline` | La columna que dice qué fue cada evento, escrita bajo su punto cuando cabe y al pasar el cursor |
| `lat`, `lng` | `map` | Columnas de latitud y longitud, en grados. Cualquiera de las dos puede omitirse cuando el nombre de la columna numérica indica la coordenada: `lat`, `latitude`, `geo_lat`; `lng`, `lon`, `longitude` |
| `color` | `map` | Una columna por la que colorear los puntos; si se omite, se elige una cuando una columna de texto tiene pocos valores |
| `size` | `map` | Una columna numérica por la que dimensionar los puntos |
| `size_scale` | `map` | `"sqrt"` (lo predeterminado) o `"log"`, para cómo escala `size` |
| `tooltip` | `map` | Una lista de las columnas que muestra el tooltip de un punto: `[name, passengers]` |

Los atributos de columna nombran columnas del resultado de la consulta, sin distinguir mayúsculas de minúsculas. Escribe un nombre simple sin comillas (`x = date`); pon entre comillas uno que no sea un identificador simple (`y = "revenue (EUR)"`). Un atributo que el tipo de gráfico no usa —`lat` en un gráfico de líneas, `x` en un mapa, `series` en un gráfico circular— es un error, no algo que se ignore en silencio.

### filter

| Atributo | Obligatorio | Valor |
| --- | --- | --- |
| `plot` | sí | El gráfico en el que una pulsación elige un valor: `plot.revenue_by_channel`. Un `bar`, un `stacked_bar` o un `table` |
| `column` | para un `table` | La columna cuyo valor se elige. Para un `bar` o un `stacked_bar`, su `x` cuando se omite |
| `multiple` | `bar`, `stacked_bar` | `true` hace que cada pulsación añada su valor y una segunda lo quite; `$name` pasa a ser `IN (…)`. Una tabla selecciona una fila, así que `multiple` en una tabla es un error de comprobación |

Consulta [Filtros](#filters) para ver qué hace un filtro.

### dashboard

Un bloque `dashboard` opcional contiene ajustes para todo el archivo:

```hcl
dashboard "Ops" {
  timezone = "+08:00"     # or "UTC", or "local"
}
```

`timezone` es la zona en la que se muestra cada `TIMESTAMPTZ` del panel; la zona aparece nombrada sobre los gráficos. Se aceptan un desfase (`"+08:00"`), `"UTC"` y `"local"`; los nombres IANA como `Asia/Shanghai` no. Un `TIMESTAMP` simple no tiene zona y se muestra tal como está escrito, y una columna que elige un filtro conserva su valor guardado para que las selecciones sigan coincidiendo. Un archivo contiene como mucho un bloque `dashboard`.

## Tipos de gráfico {#plot-types}

| Tipo | Dibuja |
| --- | --- |
| `line` | Una línea por serie, sin relleno |
| `area` | Un área rellena por serie |
| `bar` | Una barra por fila, un color por serie. Con `series`, las barras de cada serie una al lado de otra en cada grupo. Una sola serie etiqueta cada barra con su valor |
| `stacked_bar` | Una barra por `x`, con su `series` apilada: las partes positivas hacia arriba desde cero, las negativas hacia abajo, con el total arriba y en el tooltip |
| `heatmap` | `x` en horizontal y `series` en vertical, cada celda coloreada por `y` en un mismo azul, más oscuro cuanto más (más claro en modo oscuro). Un par que la consulta no devuelve queda vacío |
| `histogram` | Las filas contadas en cada rango de una `x` numérica, en intervalos de ancho redondeado. Haz que su consulta devuelva las filas en sí, no una agrupación |
| `scatter` | Un punto por dato, sin conectar, un color por serie |
| `pie` | Una porción por valor de `x`, dimensionada por `y`, la mayor primero; a partir de 8 porciones las más pequeñas se agrupan en «otros». Se dibuja como un anillo con el total en el centro; pulsa una entrada de la leyenda para destacar una porción y otra vez para restaurarla |
| `text` | Un título, texto explicativo o ambos; no se ejecuta ninguna consulta |
| `map` | Un punto por fila, en su `lat` y `lng`; consulta [Mapas](#maps) |
| `timeline` | Un evento por fila en su tiempo `x`, colocado según su distancia real a los demás para que se vean los huecos. `series` da a cada actor un carril, `caption` dice qué pasó y `tooltip` lista las columnas que aparecen al pasar el cursor. No usa `y`; dibuja como mucho 12 carriles y 1.000 eventos (adelgazados de forma uniforme a partir de ahí, y se indica) y cuenta las filas cuya hora no se puede leer en vez de dibujarlas |
| `table` | El resultado de la consulta como cuadrícula, con las columnas ajustadas a su contenido; pulsa un encabezado para ordenar |
| `card` | Un número, grande, con el `title` como etiqueta. Agrupado por miles, con una fracción larga redondeada (`11439704.020000005` → `11,439,704.02`) y reducido para caber en la tarjeta en vez de cortarse |

Pasa el cursor por un gráfico para ver sus valores, con el formato del eje (`4.4M`, no `4400000`).

Un gráfico de barras etiqueta **todas** las categorías. Cuando las etiquetas no caben bajo sus barras, el gráfico se tumba, con las etiquetas en una columna a la izquierda. Solo un eje de tiempo adelgaza sus etiquetas, manteniendo tantas como quepan —siempre la primera y la última—, y una barra sobre una columna `DATE` rellena los días para los que la consulta no devolvió nada como bandas vacías, así que un tramo tranquilo se lee como un hueco en vez de desaparecer. Los ejes de líneas, áreas y dispersión adelgazan sus etiquetas de la misma manera.

El eje x es categórico en todos los tipos de gráfico: los valores se espacian de forma uniforme en el orden en que los devuelve la consulta, no según su distancia entre sí. Un `scatter` de dos columnas numéricas no es, por tanto, una gráfica x–y auténtica.

Las filas se dibujan en el orden en que las devuelve la consulta, así que termina con `ORDER BY` toda consulta que alimente un gráfico.

::: info Nuevo en 0.4.0
Un `line` o un `scatter` de panel sobre tiempos se coloca por tiempo, así que los huecos desiguales se ven desiguales, y se dibuja en orden temporal sea cual sea el `ORDER BY`. Una fila con tiempo NULL se omite, con una nota. Una lectura NULL que devolvió la consulta rompe la línea. Un `area` se mantiene equiespaciado y lo dice. Cada serie conserva su color por nombre, y todos los gráficos dicen cuándo se cortó su consulta.
:::

Una tarjeta muestra la primera fila de su consulta. Cuando la consulta devuelve más de una fila, la tarjeta lo dice bajo el número; cuando no devuelve ninguna, muestra `—`.

### Tarjetas y paneles de texto {#cards-and-text-panels}

Las tarjetas pueden explicar un número con `note` y darle un color de estado con `tone`. Las tarjetas de una misma fila comparten el tamaño de fuente del valor. Los paneles de texto añaden encabezados o contexto sin ejecutar SQL:

```hcl
plot "revenue_summary" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  note  = "Current channel selection"
  tone  = "accent"
  width = 4
}

plot "reading_guide" {
  type  = "text"
  title = "How to read this dashboard"
  text  = "Click a channel to filter the daily chart and revenue cards."
  width = 8
}
```

Un panel de texto solo acepta `type`, `title`, `text` y `width`. Usa `text = <<TEXT` con una línea de cierre `TEXT` para una explicación más larga. Los gráficos, los circulares y los mapas usan ocho matices distintos, con tonos adaptados al tema actual y una leyenda cuando hay varias series.

### Formatos de número y cambio {#number-formats-and-change}

`format` da forma al valor de una tarjeta, al eje de valores, a las etiquetas de las barras y a los tooltips:

| Valor | Se lee |
| --- | --- |
| `"num0"`, `"num1"`, `"num2"` | Un número con esa cantidad de decimales |
| `"pct"` (lo mismo que `"pct1"`), `"pct0"`, `"pct2"` | Una proporción: 0,421 se lee 42,1 %, así que devuelve la fracción, no ×100 |
| `"usd"`, `"eur"`, `"gbp"`, `"cny"` | Dinero, con dos decimales |
| `"usd0"`, `"eur0"`, `"gbp0"`, `"cny0"`, `"jpy"` | Dinero, en unidades enteras |

Una tarjeta muestra un cambio con `delta`, bajo el valor, como `▲ 12.3%` o `▼ $125`. Es verde cuando es bueno y rojo cuando no, y la `note` que le sigue dice contra qué. Calcula el cambio en la consulta de la tarjeta:

```hcl
plot "revenue_total" {
  type         = "card"
  query        = query.totals
  value        = revenue
  format       = "usd0"
  delta        = growth
  delta_format = "pct1"
  note         = "vs last week"
}
```

### Diseño {#layout}

`width` es cuántas de las doce columnas del panel ocupa un gráfico. Los gráficos llenan una fila desde la izquierda en el orden en que están escritos y saltan de línea cuando el siguiente no cabe, así que cuatro tarjetas (`3` cada una) forman una fila de números y dos gráficos con `width = 6` quedan uno al lado del otro debajo. Una fila a la que le faltan columnas para doce deja el resto vacío. Una fila de solo tarjetas empieza con poca altura; una fila de solo tablas empieza tan alta como las filas de su tabla más larga, hasta la altura de un gráfico. Una fila de paneles de texto se ajusta a su texto; las demás filas empiezan a la altura de un gráfico. Los tiradores para redimensionar filas aparecen al pasar el cursor.

### Mapas {#maps}

```hcl
plot "stations" {
  type       = "map"
  query      = query.stations
  lat        = geo_lat
  lng        = geo_lng
  color      = line
  size       = passengers
  size_scale = "log"
  tooltip    = [name, passengers]
}
```

Un mapa dibuja cada fila como un punto, sobre una proyección Web Mercator ajustada a los puntos, sobre una cuadrícula de latitud/longitud etiquetada en grados.

- **`color`**: hasta cinco valores reciben un color cada uno; con más, lo reciben los cuatro más frecuentes y el resto comparte un color «Otros». Una leyenda los identifica. Si se omite, los puntos se colorean por una columna de texto con pocos valores distintos, cuando el resultado tiene una.
- **`size`**: el *área* de un punto sigue al valor, así que el doble de valor es el doble de tinta. `size_scale = "log"` va bien con valores que abarcan órdenes de magnitud. Una leyenda en la esquina identifica los tamaños.
- **`tooltip`**: sin él, el tooltip de un punto lista la columna de tamaño y los demás números, y luego las coordenadas.

Bajo los puntos, un mapa puede dibujar un mapa base de **OpenStreetMap**. Está desactivado hasta que lo actives —**Ver → Mapa base en línea (OpenStreetMap)**—, porque cargar teselas necesita la red. Lo que envía es qué teselas quiere, lo que revela a grandes rasgos la zona que se está mirando, nunca una fila de tus datos. Las teselas se guardan en caché en disco durante una semana (consulta [Ajustes y datos de la app](settings-and-data.md#where-things-are-stored)); sin conexión o desactivado, el mapa se dibuja solo sobre su cuadrícula de latitud/longitud. El mismo interruptor afecta al mapa de la pestaña **Gráfico** de los resultados de consulta.

## Filtros {#filters}

Un filtro hace que un gráfico se pueda pulsar y deja que el valor elegido allí acote otras consultas:

```hcl
filter "channel" {
  plot = plot.revenue_by_channel     # a click on a bar picks its channel
}

filter "day" {
  plot   = plot.days                 # a table: a selected row picks …
  column = day                       # … the value of this column
}

filter "channel" {
  plot     = plot.revenue_by_channel
  multiple = true                    # clicks collect channels
}

query "daily" {
  sql = "SELECT date, sum(orders) AS orders FROM sales WHERE $channel AND $day GROUP BY 1"
}
```

Una consulta lee un filtro como **`$name`, una condición**: escríbelo donde iría una condición. Mientras no hay nada elegido es `TRUE`, así que el panel se abre exactamente como lo haría sin el filtro. Cuando se elige un valor pasa a ser `("channel" = 'Web')`: la columna nombrada como la `column` del filtro, comparada con el valor elegido; una celda mostrada como `NULL` coincide con el NULL de SQL o con el texto literal `NULL`. Con `multiple = true` en una barra o una barra apilada, cada pulsación añade su valor y una segunda lo quita, y `$name` pasa a ser `("channel" IN ('Web', 'App'))`, con `OR "channel" IS NULL` cuando NULL es uno de ellos. Varios filtros se combinan como los combine la consulta.

- **En un gráfico de barras**, pulsa una barra para elegirla: conserva su color mientras las demás se atenúan. Púlsala otra vez para anular la selección. Con `multiple = true`, cada pulsación añade un valor y una segunda lo quita.
- **En una tabla**, selecciona una fila, pulsándola o con las teclas de flecha.
- Las selecciones activas aparecen como etiquetas sobre los gráficos; la ✕ de cada etiqueta borra su filtro, y **Borrar todo** borra todas las selecciones. Un filtro de selección múltiple muestra una etiqueta por valor elegido.
- **El gráfico donde se elige nunca se acota por su propio filtro.** Su consulta lee `$channel` como `TRUE` incluso mientras hay un canal elegido; de lo contrario, una pulsación reduciría el gráfico de barras a la barra recién pulsada, sin nada que pulsar después. Esto es filtrado cruzado, como en Mosaic o crossfilter.
- **Solo se vuelve a ejecutar lo que cambió.** Una selección vuelve a ejecutar las consultas cuyo SQL cambia; una consulta que no lee ningún filtro conserva su resultado.

Un filtro contiene un valor a la vez, o varios con `multiple = true`. Los gráficos seleccionables incluyen una pista de «pulsa para filtrar» bajo el título. Las series conservan sus colores aunque el filtrado cambie qué grupos quedan. Una consulta que usa `$channel` debe exponer la columna del filtro donde se usa ese predicado; ahora `ducklocal check` enlaza también una variante con valor elegido, así que una columna que falta se detecta antes de la primera pulsación.

::: info Nuevo en 0.4.0
Elegir una celda mostrada como `NULL` selecciona solo el NULL de SQL, y el texto `'NULL'` se selecciona solo a sí mismo. Los gráficos seleccionables ya no muestran la pista de «pulsa para filtrar» bajo el título.
:::

El valor elegido entra en el SQL como literal entre comillas, y DuckDB lo convierte al tipo de la columna al comparar, así que las fechas y los números funcionan igual de bien que el texto. Las selecciones duran mientras la pestaña esté abierta y sobreviven a una recarga, siempre que el filtro siga en el archivo; no se recuerdan entre arranques.

## Valores

| Forma | Ejemplo | Se usa para |
| --- | --- | --- |
| Cadena | `"Revenue by channel"` | `type`, `title`, `path`, `size_scale`, `tone`, `note` literal, `text`, nombres de columna entre comillas, `sql` corto |
| Heredoc | `<<SQL` … `SQL` | `sql`, `text` |
| Referencia | `query.daily`, `plot.revenue_by_channel` | la `query` de un gráfico, el `plot` de un filtro |
| Nombre sin más | `channel` | atributos de columna |
| Número | `6` | `width` |
| Lista | `[name, "Unique IPs"]` | `tooltip` |

Una cadena termina en su línea y entiende `\n`, `\t`, `\"` y `\\`.

`#` y `//` inician un comentario que llega hasta el final de la línea. Los atributos no necesitan separador; los saltos de línea son solo espacio en blanco.

Ese es todo el lenguaje: sin variables, sin funciones, sin condicionales y sin más interpolación que el `$name` de un filtro.

### Heredocs {#heredocs}

Un heredoc contiene texto en varias líneas, en la práctica SQL:

```hcl
  sql = <<SQL
    SELECT 1
  SQL
```

- El delimitador tras `<<` es cualquier palabra (`SQL` por convención), y no puede seguirle nada en su línea.
- El heredoc termina en la primera línea que es exactamente el delimitador, salvo espacios alrededor.
- La sangría de la línea de cierre se quita de todas las líneas del texto, así que el SQL puede ir a la sangría del bloque sin arrastrarla.

## Reglas de SQL {#sql-rules}

Un panel ejecuta sus consultas siempre que se abre, se recarga o se guarda, y cuando DuckLocal arranca con la pestaña restaurada, así que una consulta solo puede **leer**:

- **Permitido:** `SELECT`, `WITH …`, las consultas que empiezan por `FROM`, `VALUES`, `SHOW`, `DESCRIBE`, `SUMMARIZE`, `PIVOT` y `UNPIVOT`.
- **Rechazado:** cualquier cosa que pueda cambiar datos o archivos: `CREATE`, `INSERT`, `UPDATE`, `DELETE`, `DROP`, `COPY`, `ATTACH`, `INSTALL`, `LOAD`, etcétera. Abrir un archivo `.dash` que te haya enviado alguien no puede cambiar tus datos.
- **Una sentencia por consulta.**
- **Un `PIVOT` dentro de otra consulta nombra sus valores.** Una consulta que empieza por `PIVOT` puede dejar que DuckDB encuentre los valores (`PIVOT orders ON channel USING sum(amount)`). Uno anidado dentro de un `SELECT` o un `WITH` necesita una lista explícita: `ON channel IN ('Web', 'Store')`.
- **`$name` debe nombrar un bloque `filter`.** La comprobación de solo lectura juzga el SQL con cada `$name` como `TRUE`. Un `$` dentro de una cadena, un identificador entre comillas, un comentario o una cadena `$$ … $$` no se toca.

Las consultas se ejecutan en la conexión propia de la ventana, así que ven todo lo que ve el editor SQL: archivos abiertos, bases de datos adjuntas y estado a nivel de conexión, como las tablas `TEMP`.

### Rutas en SQL

Desde la v0.2.2, las rutas de archivo relativas del SQL de un panel también se buscan desde la carpeta del archivo `.dash`. Por ejemplo, `FROM 'sales.csv'` puede leer el CSV que está junto al panel cuando este se abre desde otro directorio. Esto se aplica en la ventana y en `ducklocal check`.

DuckDB sigue mirando primero el directorio de trabajo para un archivo nombrado directamente en el SQL: un archivo con el mismo nombre allí puede tener prioridad. Un bloque [source](#source) resuelve su ruta explícitamente contra la carpeta del panel y evita esa ambigüedad. Las rutas absolutas y las vistas registradas siguen disponibles.

## Límites

| Límite | Qué pasa |
| --- | --- |
| 12 series por gráfico | Las series adicionales se omiten, y un aviso dice cuántas había |
| 1.500 puntos por serie | Los puntos se reducen promediando por intervalos para que quepan |
| 200 barras | Las barras adicionales se omiten |
| 8 porciones de tarta | Las más pequeñas se agrupan en una sola porción «otros» |
| 200 columnas y 12 filas de mapa de calor | Las columnas y filas adicionales se omiten |
| 5–40 intervalos de histograma | Aproximadamente √filas, cada uno de 1, 2, 2,5 o 5 × una potencia de diez de ancho |
| 20.000 puntos de mapa | Los puntos adicionales se omiten, y un aviso lo dice |
| 12 carriles y 1.000 eventos por línea de tiempo | Los eventos adicionales se adelgazan de forma uniforme y un aviso lo dice; las filas cuya hora no se puede leer se cuentan, no se dibujan |

## Validar un panel {#validate-a-dashboard}

`ducklocal check` valida un archivo sin abrir una ventana: el paso que hay que ejecutar antes de entregar un panel a nadie:

```bash
ducklocal check sales.dash
ducklocal check sales.dash --database warehouse.duckdb
ducklocal check sales.dash --summary
```

Primero las comprobaciones estáticas: la sintaxis, los nombres y las referencias, los atributos obligatorios, cada `$name` contra los bloques `filter` y el SQL de cada consulta a través del analizador propio de DuckDB. Después **se ejecuta cada consulta**, de solo lectura, con sus fuentes y sin nada elegido, y las columnas de cada gráfico se contrastan con las columnas que su consulta devuelve de verdad, incluido que `y`, las coordenadas de un mapa y su `size` sean numéricos, y que la `column` de cada filtro sea una que devuelva la consulta de su gráfico. Ejecutar importa: un cast que falla o un glob que no coincide con nada solo se ve cuando se leen las filas.

- **Sin `--database`**, las consultas se ejecutan en memoria, que es todo lo que necesita un panel sobre sus propios archivos `source`. Una consulta que lee una tabla que ninguna fuente define aparece en `unresolved` en vez de fallar, y las columnas de sus gráficos no se comprueban: probablemente esté pensada para una base de datos.
- **Con `--database PATH`**, se ejecutan contra esa base de datos, abierta de solo lectura. Pásalo siempre que las consultas lean tablas de una base de datos.

Cada consulta que usa un filtro se enlaza además con un valor elegido, sin ejecutar esa variante. Así se detectan predicados que se refieren a una columna no disponible en esa consulta. Los bloques con errores no impiden que se comprueben los bloques correctos: los diagnósticos incluyen tanto errores de especificación como fallos de consulta de la misma ejecución.

El éxito imprime un resumen JSON de las fuentes, las consultas (con sus columnas de resultado y cuántas `rows` devolvió cada una), los filtros y los gráficos, más `empty`: las consultas que se ejecutaron y no devolvieron filas. Eso no es un error, pero normalmente es una regex, un filtro o un join que no coincidió con nada, así que revísalas antes de entregar el panel. `--summary` imprime una línea JSON de recuentos y los nombres de las consultas sin resolver y vacías. Un error sale con estado **2** si hay diagnósticos de especificación y lista todos los problemas a la vez, con un `file:line: message` cada uno. Los fallos solo de SQL, de base de datos o de archivo salen con **1**. La [guía de la CLI](cli.md#check-a-dashboard-spec) tiene los detalles.

::: info Nuevo en 0.4.0
`ducklocal check FILE --restricted --allow-read PATH` comprueba con límites un panel que no has escrito tú. Consulta [Limitar el SQL que no has escrito](agent-workflows.md#restricted).
:::

### Mensajes habituales

| Mensaje | Arreglo |
| --- | --- |
| `type is a string in quotes` | Escribe `type = "line"`, no `type = line` |
| `Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, text` | Usa uno de los tipos listados |
| `plot block "p" requires y` | Todos los tipos de gráfico necesitan una `y`; `table`, `map`, `card` y `text` no |
| `plot "p" draws query "q", which the file does not define` | Añade el bloque de consulta o corrige el nombre en `query = query.…` |
| `query names a query block: query = query.some_name` | El atributo `query` toma una referencia, no una cadena |
| `plot "p" draws y = "channel" (VARCHAR), which is not numeric` | Apunta `y` a una columna numérica o usa `type = "table"` |
| `A map plot places points by lat and lng; it takes no x` | Un mapa no tiene ejes: da `lat` y `lng`, o déjalos a los nombres de columna |
| `width is how many of the dashboard's 12 columns the plot spans` | Escribe un número entero de 1 a 12 |
| `query "q" reads $chanel, but no filter block is named "chanel"` | Corrige el nombre o añade el bloque `filter` |
| `filter "f" picks on plot "p", a line; a value is picked on a bar or table plot` | Apunta el filtro a un gráfico de barras o a una tabla |
| `a dashboard query must be a single read-only statement` | Mueve las escrituras al editor SQL, o nombra los valores de un `PIVOT` anidado con `IN`; consulta [Reglas de SQL](#sql-rules) |
| `Unknown block: "card"; a card is a plot: plot "x" { type = "card" … }` | Todos los recuadros son bloques `plot`, también las tarjetas y los paneles de texto |
| `"minutes" is a SQL keyword, so as a column alias it needs AS` | Escribe `count(*) AS minutes` o pon el alias entre comillas |
| `Unterminated heredoc: no line is exactly SQL` | Añade el delimitador de cierre en una línea propia |

## Editar en tu propio editor

`ducklocal lsp` es un servidor de lenguaje para archivos `.dash`: diagnósticos mientras escribes, autocompletado de tipos de bloque, atributos, tipos de gráfico y los nombres tras `query.` y `plot.`, documentación al pasar el cursor e ir a la definición desde una referencia `query.name` o `plot.name` hasta su bloque. La configuración para Neovim y VS Code está en la [guía de la CLI](cli.md#edit-a-dashboard-spec-with-lsp).
