Ir para o conteúdo

Painéis (.dash) ​

Um arquivo .dash descreve um painel como dados: blocos source nomeiam arquivos de dados, blocos query contêm SQL, blocos plot desenham os resultados, e blocos filter deixam que um clique em um gráfico restrinja os outros. Não há código para escrever. Tanto pessoas quanto agentes de IA podem criar o arquivo, revisá-lo em um diff e validá-lo antes de alguém abri-lo.

Um arquivo .dash desenha gráficos, tabelas, números e mapas comuns a partir de consultas salvas. Seu formato de texto puro também o torna útil para trabalhar com um agente de IA: o agente escreve ou edita o arquivo, o ducklocal check verifica se ele executa, e você comenta os gráficos para pedir mudanças.

Um exemplo completo ​

Este painel consulta o arquivo de exemplo do tutorial. Baixe sales.dash no mesmo diretório que sales.csv e abra-o.

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
}

Ele abre com três números na parte superior, o gráfico de barras e o de linhas lado a lado, e a tabela embaixo deles. Cada consulta roda uma vez, por mais gráficos que a desenhem: totals alimenta os três cartões, e daily alimenta tanto o gráfico de linhas quanto a tabela. Clique em uma barra em Revenue by channel e os cartões, o gráfico de linhas e a tabela se restringem àquele canal; o gráfico de barras em si continua inteiro, para você poder clicar em outro.

Abra um painel ​

Qualquer uma destas ações abre um arquivo .dash como aba de painel, junto das suas consultas:

  • o + no fim da faixa de abas, depois Abrir painel;
  • arrastar o arquivo para a janela;
  • nomeá-lo na linha de comando: ducklocal sales.dash;
  • a partir de um script ou de um agente, na janela que já está rodando: ducklocal open sales.dash (veja o guia da CLI).

Os gráficos são dispostos em uma grade de 12 colunas: cada um ocupa seu width, os gráficos preenchem uma linha da esquerda para a direita, e um gráfico que não cabe mais começa a linha seguinte. Arraste os divisores entre as linhas para redimensioná-las; um painel mais alto que a aba rola. Um gráfico que não consegue desenhar — sua consulta falhou, ou falta uma coluna — mostra o motivo em seu próprio painel, e o resto do painel continua desenhando. Painéis abertos voltam no próximo início, e os abertos recentemente estão listados em Painéis na barra lateral.

Passe o mouse sobre um gráfico para revelar seus controles no canto superior direito:

  • SQL transforma o gráfico no SQL que sua consulta executou por último — com suas fontes e as seleções de filtro atuais já preenchidas, então ele roda como está —, com Copiar e Abrir em uma aba de consulta. Gráfico o devolve ao formato normal.
  • A bolha de fala abre os comentários do gráfico.
  • Ampliar este gráfico o expande para preencher a aba do painel. Use Voltar ao painel (Esc) ou pressione Esc para voltar à grade.

A visualização SQL destaca a sintaxe. Clique com o botão direito em uma célula de tabela do painel para copiar a célula, sua linha separada por tabulações, ou sua coluna na ordem exibida.

Clique no cabeçalho de uma coluna de um gráfico table para ordená-la: decrescente, crescente e de volta à ordem da consulta. Números são ordenados como números e NULL fica por último; uma linha escolhida para um filtro continua escolhida depois de uma ordenação.

Ver especificação, na barra de ferramentas, muda a aba para um editor do arquivo, com destaque de sintaxe (o SQL nos heredocs é colorido como no editor SQL), autocompletar e diagnósticos em linha. Salvar ou ⌘S grava de volta e redesenha. Se o arquivo salvo não passar na validação, a aba mantém o último painel que funcionava e mostra o erro acima dele. O mesmo acontece quando outro programa muda o arquivo. Voltar ao painel retorna aos gráficos. Recarregar relê o arquivo e executa todas as consultas de novo.

Revisar com comentários ​

Os comentários deixam você revisar um painel como revisaria um documento, e entregar as mudanças a um agente de IA. O raciocínio de produto por trás desse fluxo é explorado em What Claude Dashboards taught me about DuckLocal.

Na janela, passe o mouse sobre um gráfico e clique na bolha de fala. Um cartão abre sobre o painel, citando o título do gráfico, com as conversas que já existem nele e uma caixa para escrever. Escreva o que deve mudar — "ordene estes, maior canal primeiro" — e pressione Comentar (ou ⌘/Ctrl+Enter). Cada conversa tem Responder e Resolver; uma conversa resolvida continua ali, esmaecida, até alguém responder a ela. Um gráfico com conversas abertas mantém uma bolha com a contagem delas à vista, para você ver de relance o que está esperando.

O agente lê e responde as conversas com ducklocal comments, sem precisar de janela:

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 conversa nomeia seu gráfico, a consulta do gráfico e as linhas do bloco plot dele no arquivo, então o agente sabe o que editar. Ele muda a especificação, executa ducklocal check e responde:

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

A janela observa os dois arquivos. Em menos de um segundo o gráfico é redesenhado a partir da especificação editada, e a resposta do agente aparece na conversa dele, marcada como Agente.

As conversas ficam guardadas ao lado do painel, em NAME.dash.comments.json, então elas viajam com ele como os arquivos source dele. São notas de trabalho, não parte do painel: deixe-as fora do controle de versão, ou apague o arquivo quando a revisão terminar.

A skill oficial de agente ensina esse ciclo, então um agente que a tem só precisa ouvir "trate os comentários de sales.dash".

Novo na 0.4.0

Um agente pode propor uma mudança em vez de editar o arquivo. A aba então oferece Revisar, com o diff e as verificações, e só você pode aplicá-la.

Ver um agente trabalhando ​

Enquanto um agente executa check, comments ou presence para este painel aberto, o nome dele aparece no canto, com a marca de seu criador — Claude, OpenAI, Gemini, Cursor, DeepSeek — ou sua inicial. Clique no nome para ver o log da sessão. Quando ele edita o arquivo, os gráficos alterados e adicionados continuam marcados (Claude mudou isto, Claude adicionou isto) até você tê-los à vista por um momento; um gráfico removido deixa um aviso que você pode dispensar.

Um agente pode anunciar sua próxima edição com ducklocal presence sales.dash --doing editing --plot revenue_by_channel. Esse gráfico ganha um anel; um nome de gráfico que ainda não existe ganha um marcador abaixo do painel. A sessão termina depois de 30 segundos sem atividade, ou com um --doing idle explícito. Um agente que terminou fica no canto enquanto uma conversa que ele respondeu espera sua resposta, com a contagem no avatar dele. Os comentários registram qual agente os escreveu e mostram sua marca. A referência da CLI cobre as opções. Esses indicadores mostram atividade local; eles não enviam trabalho a um agente.

Blocos ​

Um arquivo é uma sequência de blocos, cada um com um tipo, um nome entre aspas e um corpo:

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

Nomes precisam ser únicos dentro do seu tipo: duas consultas não podem compartilhar um nome, e dois gráficos também não — mas uma consulta e um gráfico podem.

Novo na 0.4.1

Um bloco view guarda a modelagem que várias consultas compartilham, um filter pode reunir vários valores (multiple = true), um gráfico timeline coloca eventos pela sua distância real no tempo, e um bloco dashboard define o fuso em que cada TIMESTAMPTZ é mostrado.

source ​

AtributoObrigatórioValor
pathsimUm arquivo .csv, .tsv, .txt, .parquet, .json, .jsonl ou .ndjson (comprimido com gzip também, como .csv.gz), ou um glob deles (exports/orders-*.csv) lido como uma única relação

Uma fonte dá aos arquivos de dados um nome que as consultas leem: com source "sales", uma consulta diz FROM sales. O caminho é relativo ao arquivo .dash, não ao lugar de onde o DuckLocal foi iniciado, então um painel e seus dados podem se mudar juntos; ~ e caminhos absolutos também funcionam.

Uma fonte nunca toca a conexão: ela vira um WITH sales AS (…) na frente de cada consulta que a nomeia, então nada aparece na barra lateral, nada sobrevive à aba, e uma fonte oculta uma tabela de mesmo nome apenas para as consultas deste painel. O nome precisa ser um identificador simples (letras, dígitos e _). Uma pasta de trabalho não pode ser uma fonte; abra-a no DuckLocal e consulte a tabela em que ela se transforma.

view ​

Uma view guarda a modelagem que várias consultas compartilham, escrita uma vez. Ela tem um atributo sql, sob as mesmas regras de uma consulta, e toda consulta que a nomeia a lê como uma tabela:

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"
}

Uma view lê as fontes e as views definidas acima dela, compartilha seus nomes com as fontes, e não aceita $filter — leia o filtro nas consultas que leem a view. Como uma fonte, ela é colocada na frente de cada consulta que a nomeia e não cria nada na conexão. Recorra a uma quando as consultas repetiriam, de outro modo, o mesmo CTE, como ao achatar JSON aninhado.

query ​

AtributoObrigatórioValor
sqlsimUma instrução SQL somente leitura, como um heredoc ou uma string

Um bloco de consulta contém sql e nada mais. Ele pode ler $name para um filtro.

plot ​

AtributoParaValor
typetodos, obrigatório"line", "bar", "stacked_bar", "area", "scatter", "pie", "heatmap", "histogram", "map", "timeline", "table", "card" ou "text" — uma string entre aspas
querytodos exceto text, obrigatórioUma referência a um bloco de consulta: query.by_channel
xgráficos, obrigatórioA coluna no eixo horizontal; as fatias de um pie; o número que um histogram agrupa em faixas; o tempo de um timeline
ygráficos, obrigatórioA coluna a plotar; precisa ser numérica. Os tamanhos das fatias de um pie. Um histogram e um timeline não usam nenhuma
seriesline, bar, stacked_bar, area, scatter, heatmap, timelineUma coluna cujos valores dividem as linhas em uma série cada; as linhas de um heatmap; as faixas de um timeline
titletodosUm título para o gráfico, como uma string entre aspas; o rótulo de um cartão
widthtodosQuantas das 12 colunas da grade o gráfico ocupa, 1–12. Padrão 12, ou 3 para um cartão
valuecardA coluna a mostrar, da primeira linha. Padrão: a primeira coluna
notecardTexto abaixo do valor: uma string entre aspas, ou um nome de coluna puro para ler da primeira linha
tonecard"accent", "good", "warning" ou "critical"; colore a linha superior e o valor
formatgráficos e cardO que os números são: veja Formatos de número e variação. Um map ou table não usa nenhum
deltacardUma coluna numérica com a variação, mostrada abaixo do valor
delta_formatcardUm formato para a variação. Padrão: o do cartão
down_is_goodcardtrue deixa uma queda verde e uma alta vermelha, para custos, latência ou churn
descriptiontodos, 0.4.0+O que o gráfico mostra e como lê-lo; aparece ao passar o mouse sobre um ⓘ ao lado do título
texttextTexto do corpo como string ou heredoc; informe title, text, ou ambos, sem query
captiontimelineA coluna que diz o que cada evento foi, escrita abaixo do ponto dele quando cabe e ao passar o mouse
lat, lngmapColunas de latitude e longitude, em graus. Qualquer uma pode ser omitida quando o nome da coluna numérica indica a coordenada — lat, latitude, geo_lat; lng, lon, longitude
colormapUma coluna para colorir os pontos; omitida, uma é escolhida quando uma coluna de texto tem poucos valores
sizemapUma coluna numérica para dimensionar os pontos
size_scalemap"sqrt" (o padrão) ou "log", para como size escala
tooltipmapUma lista das colunas que a dica de ferramenta de um ponto mostra: [name, passengers]

Atributos de coluna nomeiam colunas do resultado da consulta, correspondidas sem levar em conta maiúsculas e minúsculas. Escreva um nome simples puro (x = date); ponha entre aspas um que não seja um identificador simples (y = "revenue (EUR)"). Um atributo que o tipo do gráfico não usa — lat em uma linha, x em um mapa, series em um gráfico de pizza — é um erro, não algo ignorado em silêncio.

filter ​

AtributoObrigatórioValor
plotsimO gráfico em que um clique escolhe um valor: plot.revenue_by_channel. Um bar, um stacked_bar ou um table
columnpara um tableA coluna cujo valor é escolhido. Para um bar ou stacked_bar, seu x quando omitida
multiplebar, stacked_bartrue faz cada clique adicionar seu valor e um segundo clique tirá-lo; $name vira IN (…). Uma tabela seleciona uma linha, então multiple em uma tabela é um erro de verificação

Veja Filtros para o que um filtro faz.

dashboard ​

Um bloco dashboard opcional guarda configurações para o arquivo inteiro:

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

timezone é o fuso em que cada TIMESTAMPTZ do painel é mostrado; o fuso é nomeado acima dos gráficos. Um deslocamento ("+08:00"), "UTC" e "local" são aceitos; nomes IANA como Asia/Shanghai não. Um TIMESTAMP simples não tem fuso e é mostrado como escrito, e uma coluna que um filtro escolhe mantém seu valor guardado para que as seleções continuem correspondendo. Um arquivo contém no máximo um bloco dashboard.

Tipos de gráfico ​

TipoDesenha
lineUma linha por série, sem preenchimento
areaUma área preenchida por série
barUma barra por linha, uma cor por série. Com series, as barras das séries lado a lado em cada grupo. Uma única série rotula cada barra com seu valor
stacked_barUma barra por x, com sua series empilhada: partes positivas subindo de zero, negativas descendo, com o total em cima e na dica de ferramenta
heatmapx na horizontal e series na vertical, cada célula colorida por y em um mesmo azul, mais escuro quanto mais (mais claro no modo escuro). Um par que a consulta não retorna fica vazio
histogramAs linhas contadas em cada intervalo de um x numérico, em faixas de largura arredondada. Deixe a consulta retornar as linhas em si, não um agrupamento
scatterUm ponto por dado, sem conexão, uma cor por série
pieUma fatia por valor de x, dimensionada por y, a maior primeiro; a partir de 8 fatias as menores se juntam em "outros". Desenhado como um anel com o total no centro; clique em uma entrada da legenda para destacar uma fatia, e de novo para restaurá-la
textUm título, texto explicativo, ou ambos; nenhuma consulta roda
mapUm ponto por linha, em seu lat e lng; veja Mapas
timelineUm evento por linha em seu tempo x, colocado pela distância real dele dos outros para que os intervalos apareçam. series dá a cada ator uma faixa, caption diz o que aconteceu, e tooltip lista as colunas mostradas ao passar o mouse. Não usa y; desenha no máximo 12 faixas e 1.000 eventos (afinados de forma uniforme depois disso, e isso é informado), e conta as linhas cujo horário não pode ser lido em vez de desenhá-las
tableO resultado da consulta como grade, com as colunas dimensionadas ao conteúdo; clique em um cabeçalho para ordenar
cardUm número, grande, com o title como rótulo. Agrupado por milhares, uma fração longa arredondada (11439704.020000005 → 11,439,704.02), e reduzido para caber no cartão em vez de cortado

Passe o mouse sobre um gráfico para ver seus valores, formatados como o eixo os mostra (4.4M, não 4400000).

Um gráfico de barras rotula todas as categorias. Quando os rótulos não cabem embaixo das barras, o gráfico se deita, com os rótulos em uma coluna à esquerda. Apenas um eixo de tempo afina seus rótulos, mantendo tantos quantos cabem — sempre o primeiro e o último — e uma barra sobre uma coluna DATE preenche os dias para os quais a consulta não retornou nada como faixas vazias, então um trecho calmo se lê como um intervalo em vez de desaparecer. Os eixos de linhas, áreas e dispersão afinam seus rótulos da mesma forma.

O eixo x é categórico em todos os tipos de gráfico: os valores são espaçados uniformemente na ordem em que a consulta os retorna, não pela distância entre eles. Um scatter de duas colunas numéricas, portanto, não é um gráfico x–y de verdade.

As linhas são plotadas na ordem em que a consulta as retorna, então termine com ORDER BY uma consulta que alimenta um gráfico.

Novo na 0.4.0

Um line ou scatter de painel sobre tempos é colocado por tempo, então intervalos desiguais parecem desiguais, e ele desenha em ordem temporal seja qual for o ORDER BY. Uma linha com tempo NULL fica de fora, com uma nota. Uma leitura NULL que a consulta retornou quebra a linha. Um area continua com espaçamento uniforme e diz isso. Uma série mantém sua cor pelo nome, e todo gráfico diz quando sua consulta foi cortada.

Um cartão mostra a primeira linha de sua consulta. Quando a consulta retorna mais de uma linha, o cartão avisa embaixo do número; quando não retorna nenhuma, ele mostra —.

Cartões e painéis de texto ​

Cartões podem explicar um número com note e dar a ele uma cor de status com tone. Cartões na mesma linha compartilham um tamanho de fonte para o valor. Painéis de texto acrescentam títulos ou contexto sem executar 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
}

Um painel de texto aceita apenas type, title, text e width. Use text = <<TEXT com uma linha TEXT de fechamento para uma explicação mais longa. Gráficos, pizzas e mapas usam oito matizes distintos, com tons adaptados ao tema atual e uma legenda para várias séries.

Formatos de número e variação ​

format molda o valor de um cartão, o eixo de valores, os rótulos das barras e as dicas de ferramenta:

ValorLê
"num0", "num1", "num2"Um número com essa quantidade de casas decimais
"pct" (o mesmo que "pct1"), "pct0", "pct2"Uma proporção: 0,421 se lê 42,1%, então retorne a fração, não ×100
"usd", "eur", "gbp", "cny"Dinheiro, com duas casas decimais
"usd0", "eur0", "gbp0", "cny0", "jpy"Dinheiro, em unidades inteiras

Um cartão mostra uma variação com delta, abaixo do valor, como ▲ 12.3% ou ▼ $125. É verde quando é bom e vermelho quando não é, e a note que a segue diz em relação a quê. Calcule a variação na consulta do cartão:

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

Layout ​

width é quantas das doze colunas do painel um gráfico ocupa. Os gráficos preenchem uma linha da esquerda para a direita na ordem em que estão escritos e quebram quando o próximo não cabe, então quatro cartões (3 cada) formam uma linha de números, e dois gráficos com width = 6 ficam lado a lado embaixo deles. Uma linha com menos de doze deixa o resto vazio. Uma linha só de cartões começa com altura baixa, uma linha só de tabelas começa tão alta quanto as linhas da sua tabela mais longa, até a altura de um gráfico. Uma linha de painéis de texto se ajusta ao seu texto; as outras linhas começam na altura de um gráfico. As alças para redimensionar linhas aparecem ao passar o mouse.

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]
}

Um mapa plota cada linha como um ponto, em uma projeção Web Mercator ajustada aos pontos, sobre uma grade de latitude/longitude rotulada em graus.

  • color: até cinco valores recebem cada um uma cor; com mais, os quatro mais comuns recebem e o resto compartilha uma cor "Outros". Uma legenda os identifica. Omitida, os pontos são coloridos por uma coluna de texto com apenas alguns valores distintos, quando o resultado tem uma.
  • size: a área de um ponto segue o valor, então o dobro do valor é o dobro de tinta. size_scale = "log" combina com valores que abrangem ordens de magnitude. Uma legenda no canto identifica os tamanhos.
  • tooltip: sem ela, a dica de ferramenta de um ponto lista a coluna de tamanho e os outros números, e depois as coordenadas.

Abaixo dos pontos, um mapa pode desenhar um mapa base do OpenStreetMap. Ele fica desligado até você ativá-lo — Exibir → Mapa base on-line (OpenStreetMap) — porque carregar as peças do mapa precisa de rede. O que ele envia é quais peças do mapa quer, o que revela aproximadamente a área sendo olhada, nunca uma linha dos seus dados. As peças ficam em cache no disco por uma semana (veja Configurações e dados do app); sem conexão ou desligado, o mapa desenha apenas sobre sua grade de latitude/longitude. O mesmo interruptor cobre o mapa na aba Gráfico dos resultados da consulta.

Filtros ​

Um filtro torna um gráfico clicável, e deixa o valor escolhido ali restringir outras 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"
}

Uma consulta lê um filtro como $name, uma condição: escreva-o onde uma condição iria. Enquanto nada está escolhido ele é TRUE, então o painel abre exatamente como abriria sem o filtro. Assim que um valor é escolhido ele vira ("channel" = 'Web') — a coluna nomeada como a column do filtro, comparada com o valor escolhido; uma célula exibida como NULL corresponde ao NULL do SQL ou ao texto literal NULL. Com multiple = true em uma barra ou barra empilhada, cada clique adiciona seu valor e um segundo clique o tira, e $name vira ("channel" IN ('Web', 'App')), com OR "channel" IS NULL quando NULL é um deles. Vários filtros se combinam como a consulta os combinar.

  • Em um gráfico de barras, clique em uma barra para escolhê-la: ela mantém sua cor enquanto as outras esmaecem. Clique nela de novo para limpar a escolha. Com multiple = true, cada clique adiciona um valor e um segundo clique o remove.
  • Em uma tabela, selecione uma linha, clicando ou com as teclas de seta.
  • As seleções ativas aparecem como chips acima dos gráficos; o ✕ de cada chip limpa seu filtro, e Limpar tudo limpa todas as seleções. Um filtro de seleção múltipla mostra um chip por valor escolhido.
  • O gráfico que escolhe nunca é restringido pelo próprio filtro. Sua consulta lê $channel como TRUE mesmo enquanto um canal está escolhido — caso contrário, um clique reduziria o gráfico de barras à barra recém-clicada, sem nada restante para clicar depois. Isto é filtragem cruzada, como em Mosaic ou crossfilter.
  • Só o que mudou roda de novo. Uma seleção reexecuta as consultas cujo SQL ela muda; uma consulta que não lê nenhum filtro mantém seu resultado.

Um filtro contém um valor por vez, ou vários com multiple = true. Gráficos selecionáveis incluem uma dica de "clique para filtrar" abaixo do título. As séries mantêm suas cores enquanto a filtragem muda quais grupos permanecem. Uma consulta que usa $channel precisa expor a coluna do filtro onde esse predicado é usado; o ducklocal check agora também vincula uma variante com valor escolhido, então uma coluna faltante é detectada antes do primeiro clique.

Novo na 0.4.0

Escolher uma célula exibida como NULL seleciona apenas o NULL do SQL, e o texto 'NULL' seleciona apenas a si mesmo. Gráficos selecionáveis não mostram mais a dica de "clique para filtrar" abaixo do título.

O valor escolhido entra no SQL como um literal entre aspas, e o DuckDB o converte para o tipo da coluna ao comparar, então datas e números funcionam tão bem quanto texto. As seleções duram enquanto a aba estiver aberta e sobrevivem a uma recarga, contanto que o filtro ainda esteja no arquivo; elas não são lembradas entre inícios.

Valores ​

FormaExemploUsado para
String"Revenue by channel"type, title, path, size_scale, tone, note literal, text, nomes de coluna entre aspas, sql curto
Heredoc<<SQL … SQLsql, text
Referênciaquery.daily, plot.revenue_by_channela query de um gráfico, o plot de um filtro
Nome purochannelatributos de coluna
Número6width
Lista[name, "Unique IPs"]tooltip

Uma string termina na sua linha e entende \n, \t, \" e \\.

# e // iniciam um comentário que vai até o fim da linha. Atributos não precisam de separador; quebras de linha são apenas espaço em branco.

Essa é a linguagem inteira: sem variáveis, sem funções, sem condicionais, e sem interpolação além do $name de um filtro.

Heredocs ​

Um heredoc contém texto em várias linhas — na prática, SQL:

hcl
  sql = <<SQL
    SELECT 1
  SQL
  • O delimitador depois de << é qualquer palavra (SQL por convenção), e nada pode vir depois dele na mesma linha.
  • O heredoc termina na primeira linha que é exatamente o delimitador, com ou sem espaços em volta.
  • A indentação da linha de fechamento é removida de todas as linhas do texto, então o SQL pode ficar na indentação do bloco sem carregá-la.

Regras de SQL ​

Um painel executa suas consultas sempre que é aberto, recarregado ou salvo, e quando o DuckLocal inicia com a aba restaurada — então uma consulta só pode ler:

  • Permitido: SELECT, WITH …, consultas que começam com FROM, VALUES, SHOW, DESCRIBE, SUMMARIZE, PIVOT e UNPIVOT.
  • Recusado: qualquer coisa que possa mudar dados ou arquivos — CREATE, INSERT, UPDATE, DELETE, DROP, COPY, ATTACH, INSTALL, LOAD, e assim por diante. Abrir um arquivo .dash que alguém te enviou não pode mudar seus dados.
  • Uma instrução por consulta.
  • Um PIVOT dentro de outra consulta nomeia seus valores. Uma consulta que começa com PIVOT pode deixar que o DuckDB encontre os valores (PIVOT orders ON channel USING sum(amount)). Um aninhado dentro de um SELECT ou de um WITH precisa de uma lista explícita: ON channel IN ('Web', 'Store').
  • $name precisa nomear um bloco filter. A verificação de somente leitura julga o SQL com cada $name como TRUE. Um $ dentro de uma string, um identificador entre aspas, um comentário ou uma string $$ … $$ fica intocado.

As consultas rodam na conexão da própria janela, então elas veem tudo o que o editor SQL vê: arquivos abertos, bancos de dados anexados e estado no nível da conexão como tabelas TEMP.

Caminhos em SQL ​

Desde a v0.2.2, caminhos de arquivo relativos no SQL de um painel também são procurados a partir da pasta do arquivo .dash. Por exemplo, FROM 'sales.csv' pode ler o CSV ao lado do painel quando ele é aberto de outro diretório. Isso vale na janela e no ducklocal check.

O DuckDB ainda verifica o diretório de trabalho primeiro para um único arquivo nomeado diretamente no SQL: um arquivo de mesmo nome ali pode ter precedência. Um bloco source resolve seu caminho explicitamente contra a pasta do painel e evita essa ambiguidade. Caminhos absolutos e views registradas continuam disponíveis.

Limites ​

LimiteO que acontece
12 séries por gráficoAs séries adicionais ficam de fora, e um aviso diz quantas havia
1.500 pontos por sérieOs pontos são reduzidos por média em faixas para caber
200 barrasAs barras adicionais ficam de fora
8 fatias de pizzaAs menores se juntam em uma única fatia "outros"
200 colunas e 12 linhas de mapa de calorAs colunas e linhas adicionais ficam de fora
5–40 faixas de histogramaMais ou menos √linhas delas, cada uma com 1, 2, 2,5 ou 5 × uma potência de dez de largura
20.000 pontos de mapaOs pontos adicionais ficam de fora, e um aviso diz isso
12 faixas e 1.000 eventos por linha do tempoOs eventos adicionais são afinados de forma uniforme e um aviso diz isso; as linhas cujo horário não pode ser lido são contadas, não desenhadas

Valide um painel ​

O ducklocal check valida um arquivo sem abrir uma janela — o passo a executar antes de entregar um painel a alguém:

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

Primeiro as verificações estáticas: a sintaxe, os nomes e referências, os atributos obrigatórios, cada $name contra os blocos de filtro, e o SQL de cada consulta pelo próprio analisador do DuckDB. Depois cada consulta roda, somente leitura, com suas fontes e sem nada escolhido, e as colunas de cada gráfico são verificadas contra as colunas que sua consulta realmente retorna — incluindo que y, as coordenadas de um mapa e seu size são numéricos, e que a column de cada filtro é uma que a consulta do seu gráfico retorna. Executar importa: um cast que falha ou um glob que não corresponde a nada só aparece quando as linhas são lidas.

  • Sem --database as consultas rodam em memória, que é tudo de que um painel sobre seus próprios arquivos source precisa. Uma consulta que lê uma tabela que nenhuma fonte define é listada em unresolved em vez de falhar, e as colunas dos seus gráficos ficam sem verificação — ela provavelmente é destinada a um banco de dados.
  • Com --database PATH elas rodam contra aquele banco de dados, aberto como somente leitura. Passe-o sempre que as consultas lerem tabelas de um banco de dados.

Cada consulta que usa um filtro também é vinculada com um valor escolhido, sem executar essa variante. Isso detecta predicados que se referem a uma coluna indisponível naquela consulta. Blocos com erros não impedem que blocos corretos sejam verificados: os diagnósticos incluem tanto erros de especificação quanto falhas de consulta da mesma execução.

O sucesso imprime um resumo JSON das fontes, consultas (com suas colunas de resultado e quantas rows cada uma retornou), filtros e gráficos, mais empty: as consultas que rodaram e não retornaram linhas. Isso não é um erro, mas geralmente é uma regex, um filtro ou um join que não correspondeu a nada, então olhe cada uma antes de entregar o painel. --summary imprime uma linha JSON de contagens e os nomes das consultas não resolvidas e vazias. Um erro sai com status 2 para diagnósticos de especificação e lista todos os problemas de uma vez, um file:line: message cada. Falhas apenas de SQL, de banco de dados ou de arquivo saem com 1. O guia da CLI tem os detalhes.

Novo na 0.4.0

ducklocal check FILE --restricted --allow-read PATH verifica um painel que você não escreveu sob limites. Veja Limite o SQL que você não escreveu.

Mensagens comuns ​

MensagemCorreção
type is a string in quotesEscreva type = "line", não type = line
Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, textUse um dos tipos listados
plot block "p" requires yTodo tipo de gráfico precisa de um y; table, map, card e text não
plot "p" draws query "q", which the file does not defineAcrescente o bloco de consulta, ou corrija o nome em query = query.…
query names a query block: query = query.some_nameO atributo query recebe uma referência, não uma string
plot "p" draws y = "channel" (VARCHAR), which is not numericAponte y para uma coluna numérica, ou use type = "table"
A map plot places points by lat and lng; it takes no xUm mapa não tem eixos: informe lat e lng, ou deixe isso para os nomes das colunas
width is how many of the dashboard's 12 columns the plot spansEscreva um número inteiro de 1 a 12
query "q" reads $chanel, but no filter block is named "chanel"Corrija o nome, ou acrescente o bloco filter
filter "f" picks on plot "p", a line; a value is picked on a bar or table plotAponte o filtro para um gráfico de barras ou uma tabela
a dashboard query must be a single read-only statementMova as escritas para o editor SQL, ou nomeie os valores de um PIVOT aninhado com IN; veja Regras de SQL
Unknown block: "card"; a card is a plot: plot "x" { type = "card" … }Todo painel é um bloco plot, inclusive cartões e painéis de texto
"minutes" is a SQL keyword, so as a column alias it needs ASEscreva count(*) AS minutes, ou ponha o alias entre aspas
Unterminated heredoc: no line is exactly SQLAcrescente o delimitador de fechamento em uma linha própria

Edite no seu próprio editor ​

O ducklocal lsp é um servidor de linguagem para arquivos .dash: diagnósticos enquanto você digita, autocompletar para tipos de bloco, atributos, tipos de gráfico e os nomes depois de query. e plot., documentação ao passar o mouse, e ir para a definição de uma referência query.name ou plot.name até seu bloco. A configuração para Neovim e VS Code está no guia da CLI.

Publicado sob a licença Apache-2.0.