# Painéis (.dash)

> Monte painéis do DuckLocal como arquivos .dash de SQL do DuckDB: gráficos, filtros cruzados, comentários que um agente de IA pode responder e validação com ducklocal check.

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

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](#review-with-comments) para pedir mudanças.

## Um exemplo completo {#a-complete-example}

Este painel consulta o [arquivo de exemplo do tutorial](tutorial.md#sample-file). Baixe [sales.dash](https://ducklocal.app/docs/samples/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](cli.md#show-work-in-the-running-window)).

Os gráficos são dispostos em uma grade de 12 colunas: cada um ocupa seu [`width`](#layout),
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](#review-with-comments) 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](#filters) 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 {#review-with-comments}

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](https://ducklocal.app/pt/blog/claude-dashboards-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`](cli.md#review-comments-on-a-dashboard), 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](cli.md#install-the-official-skill) ensina esse
ciclo, então um agente que a tem só precisa ouvir *"trate os comentários de
sales.dash"*.

::: info Novo na 0.4.0
Um agente pode [propor uma mudança](agent-workflows.md#propose) 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 {#agent-presence}

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](cli.md#agent-presence) cobre as opções. Esses indicadores mostram atividade local; eles não enviam trabalho a um agente.

## Blocos {#blocks}

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.

::: info 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 {#source}

| Atributo | Obrigatório | Valor |
| --- | --- | --- |
| `path` | sim | Um 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

| Atributo | Obrigatório | Valor |
| --- | --- | --- |
| `sql` | sim | Uma instrução SQL somente leitura, como um [heredoc](#heredocs) ou uma string |

Um bloco de consulta contém `sql` e nada mais. Ele pode ler `$name` para um
[filtro](#filters).

### plot

| Atributo | Para | Valor |
| --- | --- | --- |
| `type` | todos, obrigatório | `"line"`, `"bar"`, `"stacked_bar"`, `"area"`, `"scatter"`, `"pie"`, `"heatmap"`, `"histogram"`, `"map"`, `"timeline"`, `"table"`, `"card"` ou `"text"` — uma string entre aspas |
| `query` | todos exceto `text`, obrigatório | Uma referência a um bloco de consulta: `query.by_channel` |
| `x` | gráficos, obrigatório | A coluna no eixo horizontal; as fatias de um `pie`; o número que um `histogram` agrupa em faixas; o tempo de um `timeline` |
| `y` | gráficos, obrigatório | A coluna a plotar; precisa ser numérica. Os tamanhos das fatias de um `pie`. Um `histogram` e um `timeline` não usam nenhuma |
| `series` | `line`, `bar`, `stacked_bar`, `area`, `scatter`, `heatmap`, `timeline` | Uma coluna cujos valores dividem as linhas em uma série cada; as linhas de um `heatmap`; as faixas de um `timeline` |
| `title` | todos | Um título para o gráfico, como uma string entre aspas; o rótulo de um cartão |
| `width` | todos | Quantas das 12 colunas da grade o gráfico ocupa, `1`–`12`. Padrão 12, ou 3 para um cartão |
| `value` | `card` | A coluna a mostrar, da primeira linha. Padrão: a primeira coluna |
| `note` | `card` | Texto abaixo do valor: uma string entre aspas, ou um nome de coluna puro para ler da primeira linha |
| `tone` | `card` | `"accent"`, `"good"`, `"warning"` ou `"critical"`; colore a linha superior e o valor |
| `format` | gráficos e `card` | O que os números são: veja [Formatos de número e variação](#number-formats-and-change). Um `map` ou `table` não usa nenhum |
| `delta` | `card` | Uma coluna numérica com a variação, mostrada abaixo do valor |
| `delta_format` | `card` | Um formato para a variação. Padrão: o do cartão |
| `down_is_good` | `card` | `true` deixa uma queda verde e uma alta vermelha, para custos, latência ou churn |
| `description` | todos, **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 |
| `text` | `text` | Texto do corpo como string ou heredoc; informe `title`, `text`, ou ambos, sem `query` |
| `caption` | `timeline` | A coluna que diz o que cada evento foi, escrita abaixo do ponto dele quando cabe e ao passar o mouse |
| `lat`, `lng` | `map` | Colunas 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` |
| `color` | `map` | Uma coluna para colorir os pontos; omitida, uma é escolhida quando uma coluna de texto tem poucos valores |
| `size` | `map` | Uma coluna numérica para dimensionar os pontos |
| `size_scale` | `map` | `"sqrt"` (o padrão) ou `"log"`, para como `size` escala |
| `tooltip` | `map` | Uma 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

| Atributo | Obrigatório | Valor |
| --- | --- | --- |
| `plot` | sim | O gráfico em que um clique escolhe um valor: `plot.revenue_by_channel`. Um `bar`, um `stacked_bar` ou um `table` |
| `column` | para um `table` | A coluna cujo valor é escolhido. Para um `bar` ou `stacked_bar`, seu `x` quando omitida |
| `multiple` | `bar`, `stacked_bar` | `true` 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](#filters) 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 {#plot-types}

| Tipo | Desenha |
| --- | --- |
| `line` | Uma linha por série, sem preenchimento |
| `area` | Uma área preenchida por série |
| `bar` | Uma 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_bar` | Uma barra por `x`, com sua `series` empilhada: partes positivas subindo de zero, negativas descendo, com o total em cima e na dica de ferramenta |
| `heatmap` | `x` 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 |
| `histogram` | As 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 |
| `scatter` | Um ponto por dado, sem conexão, uma cor por série |
| `pie` | Uma 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 |
| `text` | Um título, texto explicativo, ou ambos; nenhuma consulta roda |
| `map` | Um ponto por linha, em seu `lat` e `lng`; veja [Mapas](#maps) |
| `timeline` | Um 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 |
| `table` | O resultado da consulta como grade, com as colunas dimensionadas ao conteúdo; clique em um cabeçalho para ordenar |
| `card` | Um 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.

::: info 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 {#cards-and-text-panels}

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 {#number-formats-and-change}

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

| Valor | Lê |
| --- | --- |
| `"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 {#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 {#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]
}
```

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](settings-and-data.md#where-things-are-stored)); 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 {#filters}

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.

::: info 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

| Forma | Exemplo | Usado para |
| --- | --- | --- |
| String | `"Revenue by channel"` | `type`, `title`, `path`, `size_scale`, `tone`, `note` literal, `text`, nomes de coluna entre aspas, `sql` curto |
| Heredoc | `<<SQL` … `SQL` | `sql`, `text` |
| Referência | `query.daily`, `plot.revenue_by_channel` | a `query` de um gráfico, o `plot` de um filtro |
| Nome puro | `channel` | atributos de coluna |
| Número | `6` | `width` |
| 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 {#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 {#sql-rules}

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](#source) resolve seu caminho explicitamente contra a pasta do painel e evita essa ambiguidade. Caminhos absolutos e views registradas continuam disponíveis.

## Limites

| Limite | O que acontece |
| --- | --- |
| 12 séries por gráfico | As séries adicionais ficam de fora, e um aviso diz quantas havia |
| 1.500 pontos por série | Os pontos são reduzidos por média em faixas para caber |
| 200 barras | As barras adicionais ficam de fora |
| 8 fatias de pizza | As menores se juntam em uma única fatia "outros" |
| 200 colunas e 12 linhas de mapa de calor | As colunas e linhas adicionais ficam de fora |
| 5–40 faixas de histograma | Mais ou menos √linhas delas, cada uma com 1, 2, 2,5 ou 5 × uma potência de dez de largura |
| 20.000 pontos de mapa | Os pontos adicionais ficam de fora, e um aviso diz isso |
| 12 faixas e 1.000 eventos por linha do tempo | Os 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 {#validate-a-dashboard}

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](cli.md#check-a-dashboard-spec) tem os detalhes.

::: info 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](agent-workflows.md#restricted).
:::

### Mensagens comuns

| Mensagem | Correção |
| --- | --- |
| `type is a string in quotes` | Escreva `type = "line"`, não `type = line` |
| `Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, text` | Use um dos tipos listados |
| `plot block "p" requires y` | Todo 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 define` | Acrescente o bloco de consulta, ou corrija o nome em `query = query.…` |
| `query names a query block: query = query.some_name` | O atributo `query` recebe uma referência, não uma string |
| `plot "p" draws y = "channel" (VARCHAR), which is not numeric` | Aponte `y` para uma coluna numérica, ou use `type = "table"` |
| `A map plot places points by lat and lng; it takes no x` | Um 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 spans` | Escreva 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 plot` | Aponte o filtro para um gráfico de barras ou uma tabela |
| `a dashboard query must be a single read-only statement` | Mova as escritas para o editor SQL, ou nomeie os valores de um `PIVOT` aninhado com `IN`; veja [Regras de SQL](#sql-rules) |
| `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 AS` | Escreva `count(*) AS minutes`, ou ponha o alias entre aspas |
| `Unterminated heredoc: no line is exactly SQL` | Acrescente 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](cli.md#edit-a-dashboard-spec-with-lsp).
