Ir al contenido

Paneles (.dash) ​

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 para pedir cambios.

Un ejemplo completo ​

Este panel consulta el archivo de ejemplo del tutorial. Descarga 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).

Los gráficos se colocan en una cuadrícula de 12 columnas: cada uno ocupa su width, 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 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 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 ​

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.

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, 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 enseña este bucle, así que a un agente que la tenga solo hay que decirle "atiende los comentarios de sales.dash".

Nuevo en 0.4.0

Un agente puede proponer un cambio 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 ​

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 explica las opciones. Estos indicadores muestran actividad local; no envían trabajo a un agente.

Bloques ​

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

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 ​

AtributoObligatorioValor
pathsí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 ​

AtributoObligatorioValor
sqlsíUna sentencia SQL de solo lectura, como heredoc o como cadena

Un bloque de consulta contiene sql y nada más. Puede leer $name para un filtro.

plot ​

AtributoParaValor
typetodos, obligatorio"line", "bar", "stacked_bar", "area", "scatter", "pie", "heatmap", "histogram", "map", "timeline", "table", "card" o "text" — una cadena entre comillas
querytodos excepto text, obligatorioUna referencia a un bloque de consulta: query.by_channel
xgráficos, obligatorioLa columna del eje horizontal; las porciones de un pie; el número que agrupa un histogram; el tiempo de un timeline
ygráficos, obligatorioLa 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
seriesline, bar, stacked_bar, area, scatter, heatmap, timelineUna columna cuyos valores dividen las filas en una serie cada uno; las filas de un heatmap; los carriles de un timeline
titletodosUn encabezado para el gráfico, como cadena entre comillas; la etiqueta de una tarjeta
widthtodosCuántas de las 12 columnas de la cuadrícula ocupa el gráfico, 1–12. Por defecto 12, o 3 para una tarjeta
valuecardLa columna que se muestra, de la primera fila. Por defecto: la primera columna
notecardTexto bajo el valor: una cadena entre comillas o un nombre de columna sin más para leerlo de la primera fila
tonecard"accent", "good", "warning" o "critical"; colorea la línea superior y el valor
formatgráficos y cardQué son los números: consulta Formatos de número y cambio. Un map o un table no lo usan
deltacardUna columna numérica con el cambio, que se muestra bajo el valor
delta_formatcardUn formato para el cambio. Por defecto: el de la tarjeta
down_is_goodcardtrue hace que una bajada sea verde y una subida roja, para costes, latencia o bajas de clientes
descriptiontodos, 0.4.0+Qué muestra el gráfico y cómo leerlo; aparece al pasar el cursor por un ⓘ junto al título
texttextTexto del cuerpo como cadena o heredoc; indica title, text o ambos, sin query
captiontimelineLa columna que dice qué fue cada evento, escrita bajo su punto cuando cabe y al pasar el cursor
lat, lngmapColumnas 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
colormapUna columna por la que colorear los puntos; si se omite, se elige una cuando una columna de texto tiene pocos valores
sizemapUna columna numérica por la que dimensionar los puntos
size_scalemap"sqrt" (lo predeterminado) o "log", para cómo escala size
tooltipmapUna 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 ​

AtributoObligatorioValor
plotsíEl gráfico en el que una pulsación elige un valor: plot.revenue_by_channel. Un bar, un stacked_bar o un table
columnpara un tableLa columna cuyo valor se elige. Para un bar o un stacked_bar, su x cuando se omite
multiplebar, stacked_bartrue 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 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 ​

TipoDibuja
lineUna línea por serie, sin relleno
areaUn área rellena por serie
barUna 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_barUna 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
heatmapx 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
histogramLas 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
scatterUn punto por dato, sin conectar, un color por serie
pieUna 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
textUn título, texto explicativo o ambos; no se ejecuta ninguna consulta
mapUn punto por fila, en su lat y lng; consulta Mapas
timelineUn 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
tableEl resultado de la consulta como cuadrícula, con las columnas ajustadas a su contenido; pulsa un encabezado para ordenar
cardUn 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.

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 ​

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 ​

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

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

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 ​

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); 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 ​

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.

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 ​

FormaEjemploSe usa para
Cadena"Revenue by channel"type, title, path, size_scale, tone, note literal, text, nombres de columna entre comillas, sql corto
Heredoc<<SQL … SQLsql, text
Referenciaquery.daily, plot.revenue_by_channella query de un gráfico, el plot de un filtro
Nombre sin máschannelatributos de columna
Número6width
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 ​

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 ​

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 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ímiteQué pasa
12 series por gráficoLas series adicionales se omiten, y un aviso dice cuántas había
1.500 puntos por serieLos puntos se reducen promediando por intervalos para que quepan
200 barrasLas barras adicionales se omiten
8 porciones de tartaLas más pequeñas se agrupan en una sola porción «otros»
200 columnas y 12 filas de mapa de calorLas columnas y filas adicionales se omiten
5–40 intervalos de histogramaAproximadamente √filas, cada uno de 1, 2, 2,5 o 5 × una potencia de diez de ancho
20.000 puntos de mapaLos puntos adicionales se omiten, y un aviso lo dice
12 carriles y 1.000 eventos por línea de tiempoLos 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 ​

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 tiene los detalles.

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.

Mensajes habituales ​

MensajeArreglo
type is a string in quotesEscribe type = "line", no type = line
Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, textUsa uno de los tipos listados
plot block "p" requires yTodos los tipos de gráfico necesitan una y; table, map, card y text no
plot "p" draws query "q", which the file does not defineAñade el bloque de consulta o corrige el nombre en query = query.…
query names a query block: query = query.some_nameEl atributo query toma una referencia, no una cadena
plot "p" draws y = "channel" (VARCHAR), which is not numericApunta y a una columna numérica o usa type = "table"
A map plot places points by lat and lng; it takes no xUn 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 spansEscribe 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 plotApunta el filtro a un gráfico de barras o a una tabla
a dashboard query must be a single read-only statementMueve las escrituras al editor SQL, o nombra los valores de un PIVOT anidado con IN; consulta Reglas de SQL
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 ASEscribe count(*) AS minutes o pon el alias entre comillas
Unterminated heredoc: no line is exactly SQLAñ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.

Publicado bajo la licencia Apache-2.0.