# Дашборды (.dash)

> Стройте дашборды DuckLocal в виде файлов .dash с SQL для DuckDB: графики, перекрёстные фильтры, комментарии, на которые отвечает ИИ-агент, и проверка с помощью ducklocal check.

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

Файл `.dash` описывает дашборд как данные: блоки **source** называют файлы
данных, блоки **query** содержат SQL, блоки **plot** рисуют результаты, а блоки
**filter** позволяют щелчком на одном графике сузить остальные. Писать код не
нужно. И люди, и ИИ-агенты могут создать файл, просмотреть его в диффе и проверить
до того, как кто-либо его откроет.

Файл `.dash` строит обычные графики, таблицы, числа и карты по сохранённым
запросам. Его текстовый формат также удобен для работы с ИИ-агентом: агент пишет
или правит файл, `ducklocal check` проверяет, что он выполняется, а вы
[комментируете графики](#review-with-comments), чтобы попросить изменения.

## Полный пример {#a-complete-example}

Этот дашборд запрашивает [файл из учебника](tutorial.md#sample-file). Скачайте
[sales.dash](https://ducklocal.app/docs/samples/sales.dash) в тот же каталог, где
лежит `sales.csv`, и откройте его.

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

Он открывается тремя числами сверху, столбчатой и линейной диаграммой рядом и
таблицей под ними. Каждый запрос выполняется один раз, сколько бы графиков из него
ни строилось: `totals` питает все три карточки, а `daily` — и линейную диаграмму,
и таблицу. Щёлкните столбик в **Revenue by channel**, и карточки, линейная
диаграмма и таблица сузятся до этого канала; сама столбчатая диаграмма остаётся
целой, чтобы можно было щёлкнуть другой.

## Открытие дашборда

Любой из этих способов открывает файл `.dash` вкладкой дашборда рядом с вашими
запросами:

- **+** в конце полосы вкладок, затем **Открыть дашборд**;
- перетаскивание файла в окно;
- указание его в командной строке: `ducklocal sales.dash`;
- из скрипта или агента — в уже запущенное окно:
  `ducklocal open sales.dash` (см. [руководство по
  CLI](cli.md#show-work-in-the-running-window)).

Графики располагаются на сетке из 12 столбцов: каждый занимает свою
[`width`](#layout), графики заполняют строку слева направо, а график, который
больше не помещается, начинает следующую строку. Перетаскивайте разделители между
строками, чтобы менять их размер; дашборд выше вкладки прокручивается. График,
который не может отрисоваться, — его запрос завершился ошибкой или отсутствует
столбец — показывает причину в собственной панели, а остальная часть дашборда
продолжает рисоваться. Открытые дашборды возвращаются при следующем запуске, а
недавно открытые перечислены в разделе **Дашборды** боковой панели.

Наведите курсор на график, чтобы увидеть его элементы управления в правом верхнем
углу:

- **SQL** показывает SQL, который последним выполнял запрос этого графика — с
  подставленными источниками и текущими выбранными значениями фильтров, так что
  он выполняется в текущем виде, — вместе с **Копировать** и **Открыть во вкладке
  запроса**. **График** возвращает обратно.
- Значок диалога открывает [комментарии](#review-with-comments) графика.
- **Развернуть этот график** расширяет его на всю вкладку дашборда. Используйте
  **Назад к дашборду (Esc)** или нажмите **Esc**, чтобы вернуться к сетке.

В представлении SQL есть подсветка синтаксиса. Щёлкните правой кнопкой по ячейке
таблицы дашборда, чтобы скопировать ячейку, её строку с разделителями-табуляциями
или её столбец в отображаемом порядке.

Щёлкните заголовок столбца графика `table`, чтобы отсортировать его: по убыванию,
по возрастанию, затем снова в порядке запроса. Числа сортируются как числа, а
`NULL` — последним; строка, выбранная для [фильтра](#filters), остаётся выбранной и
после сортировки.

**Просмотр спецификации** на панели инструментов переключает вкладку на редактор
файла с подсветкой синтаксиса (SQL в heredoc-блоках раскрашивается как в редакторе
SQL), автодополнением и диагностикой по ходу ввода. **Сохранить** или **⌘S**
записывает изменения и перерисовывает дашборд. Если сохранённый файл не проходит
проверку, вкладка сохраняет последний рабочий дашборд и показывает ошибку над ним.
То же происходит, когда файл меняет другая программа. **Назад к дашборду**
возвращает к графикам. **Перезагрузить** перечитывает файл и заново выполняет все
запросы.

## Рецензирование с комментариями {#review-with-comments}

Комментарии позволяют рецензировать дашборд как документ и передавать изменения
ИИ-агенту. Идея этого сценария разобрана в статье [What Claude Dashboards taught
me about DuckLocal](https://ducklocal.app/ru/blog/claude-dashboards-ducklocal/).

**В окне** наведите курсор на график и нажмите значок диалога. Поверх дашборда
открывается карточка с заголовком графика, уже имеющимися обсуждениями и полем для
ввода. Напишите, что нужно изменить, — *«отсортируй по величине канала, начиная с
самого большого»* — и нажмите **Комментировать** (или **⌘/Ctrl+Enter**). У каждого
обсуждения есть **Ответить** и **Решено**; решённое обсуждение остаётся
приглушённым, пока кто-нибудь на него не ответит. У графика с открытыми
обсуждениями остаётся значок с их числом, так что сразу видно, что ждёт ответа.

**Агент** читает и отвечает на обсуждения с помощью [`ducklocal
comments`](cli.md#review-comments-on-a-dashboard), окно ему не нужно:

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

Каждое обсуждение называет свой график, запрос графика и строки его блока `plot`
в файле, поэтому агент знает, что править. Он меняет спецификацию, выполняет
`ducklocal check` и отвечает:

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

Окно следит за обоими файлами. В течение секунды график перерисовывается по
изменённой спецификации, а ответ агента появляется в его обсуждении с пометкой
**Агент**.

Обсуждения хранятся рядом с дашбордом, в `NAME.dash.comments.json`, поэтому они
перемещаются вместе с ним, как и его файлы `source`. Это рабочие заметки, а не
часть дашборда: не добавляйте их в систему контроля версий или удалите файл, когда
рецензирование закончено.

Этому циклу учит [официальный навык для
агентов](cli.md#install-the-official-skill), поэтому агенту с этим навыком
достаточно сказать *«ответь на комментарии в sales.dash»*.

::: info Новое в 0.4.0
Агент может [предложить изменение](agent-workflows.md#propose), а не редактировать
файл. Тогда вкладка предлагает **Проверить** с диффом и проверками, и применить его
можете только вы.
:::

### Посмотрите, как работает агент {#agent-presence}

Пока агент выполняет `check`, `comments` или `presence` для этого открытого
дашборда, его имя появляется в углу вместе со знаком его создателя — Claude,
OpenAI, Gemini, Cursor, DeepSeek — или его инициалом. Нажмите на имя, чтобы увидеть
журнал сеанса. Когда он редактирует файл, изменённые и добавленные графики остаются
помеченными (**Claude изменил это**, **Claude добавил это**), пока вы некоторое
время на них не посмотрите; удалённый график оставляет уведомление, которое можно
закрыть.

Агент может объявить о следующей правке:
`ducklocal presence sales.dash --doing editing --plot revenue_by_channel`. Этот
график получает рамку; имя графика, которого ещё нет, получает заглушку под
дашбордом. Сеанс завершается после 30 секунд без активности или при явном
`--doing idle`. Завершивший работу агент остаётся в углу, пока обсуждение, на
которое он ответил, ждёт вашего ответа, а на его аватаре показано число.
Комментарии фиксируют, какой агент их написал, и показывают его знак. Параметры
описаны в [справочнике CLI](cli.md#agent-presence). Эти индикаторы показывают
локальную активность; они не отправляют работу агенту.

## Блоки {#blocks}

Файл — это последовательность блоков, каждый из которых состоит из типа, имени в
кавычках и тела:

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

Имена должны быть уникальны в пределах своего типа: два запроса не могут иметь
одинаковое имя, как и два графика, — но запрос и график могут.

::: info Новое в 0.4.1
Блок `view` хранит общую для нескольких запросов обработку, `filter` может собирать
несколько значений (`multiple = true`), график `timeline` размещает события по их
реальному расстоянию во времени, а один блок `dashboard` задаёт часовой пояс, в
котором показываются все `TIMESTAMPTZ`.
:::

### source

| Атрибут | Обязателен | Значение |
| --- | --- | --- |
| `path` | да | Файл `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.jsonl` или `.ndjson` (в том числе сжатый gzip, например `.csv.gz`) или шаблон из них (`exports/orders-*.csv`), читаемый как одно отношение |

Блок source даёт файлам данных имя, по которому их читают запросы: при
`source "sales"` запрос пишет `FROM sales`. Путь **относительно файла `.dash`**, а
не того каталога, из которого запущен DuckLocal, поэтому дашборд и его данные можно
переносить вместе; `~` и абсолютные пути тоже работают.

Блок source никак не затрагивает подключение: он превращается в
`WITH sales AS (…)` перед каждым запросом, который его называет, поэтому в боковой
панели ничего не появляется, ничего не переживает вкладку, а source затеняет
таблицу с тем же именем только для запросов этого дашборда. Имя должно быть простым
идентификатором (буквы, цифры и `_`). Книга Excel не может быть источником;
откройте её в DuckLocal и запрашивайте таблицу, в которую она превращается.

### view

Представление хранит однажды написанную обработку, общую для нескольких запросов.
Оно содержит один атрибут `sql` по тем же правилам, что и у запроса, и каждый
запрос, который его называет, читает его как таблицу:

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

Представление читает источники и представления, определённые выше него, делит
пространство имён с источниками и не принимает `$filter` — читайте фильтр в
запросах, которые читают это представление. Как и source, оно ставится перед каждым
запросом, который его называет, и ничего не создаёт в подключении. Используйте его,
когда запросы иначе повторяли бы один и тот же CTE, например при разворачивании
вложенного JSON.

### query

| Атрибут | Обязателен | Значение |
| --- | --- | --- |
| `sql` | да | Одна инструкция SQL только для чтения, в виде [heredoc](#heredocs) или строки |

Блок query содержит `sql` и ничего больше. Он может читать `$name` для
[фильтра](#filters).

### plot

| Атрибут | Для | Значение |
| --- | --- | --- |
| `type` | все, обязательно | `"line"`, `"bar"`, `"stacked_bar"`, `"area"`, `"scatter"`, `"pie"`, `"heatmap"`, `"histogram"`, `"map"`, `"timeline"`, `"table"`, `"card"` или `"text"` — строка в кавычках |
| `query` | все, кроме `text`, обязательно | Ссылка на блок query: `query.by_channel` |
| `x` | графики, обязательно | Столбец на горизонтальной оси; срезы `pie`; число, которое раскладывает по корзинам `histogram`; время `timeline` |
| `y` | графики, обязательно | Столбец для отрисовки; должен быть числовым. Размеры срезов `pie`. `histogram` и `timeline` его не принимают |
| `series` | `line`, `bar`, `stacked_bar`, `area`, `scatter`, `heatmap`, `timeline` | Столбец, значения которого разбивают строки на отдельные серии; строки `heatmap`; дорожки `timeline` |
| `title` | все | Заголовок графика в виде строки в кавычках; подпись карточки |
| `width` | все | Сколько из 12 столбцов сетки занимает график, `1`–`12`. По умолчанию 12 или 3 для карточки |
| `value` | `card` | Столбец для показа из первой строки. По умолчанию: первый столбец |
| `note` | `card` | Текст под значением: строка в кавычках или имя столбца без кавычек, чтобы взять его из первой строки |
| `tone` | `card` | `"accent"`, `"good"`, `"warning"` или `"critical"`; задаёт цвет верхней линии и значения |
| `format` | графики и `card` | Что представляют собой числа: см. [Форматы чисел и изменение](#number-formats-and-change). `map` и `table` его не принимают |
| `delta` | `card` | Числовой столбец с изменением, показывается под значением |
| `delta_format` | `card` | Формат изменения. По умолчанию: формат карточки |
| `down_is_good` | `card` | `true` делает падение зелёным, а рост красным — для затрат, задержек или оттока |
| `description` | все, **0.4.0+** | Что показывает график и как его читать; появляется при наведении на ⓘ рядом с заголовком |
| `text` | `text` | Основной текст в виде строки или heredoc; укажите `title`, `text` или и то и другое, без `query` |
| `caption` | `timeline` | Столбец, говорящий, чем было каждое событие; пишется под его точкой, если помещается, и при наведении |
| `lat`, `lng` | `map` | Столбцы широты и долготы в градусах. Любой из них можно опустить, если имя числового столбца указывает на координату — `lat`, `latitude`, `geo_lat`; `lng`, `lon`, `longitude` |
| `color` | `map` | Столбец для раскраски точек; если не указан, он выбирается, когда текстовый столбец имеет лишь несколько значений |
| `size` | `map` | Числовой столбец для размера точек |
| `size_scale` | `map` | `"sqrt"` (по умолчанию) или `"log"` — как масштабируется `size` |
| `tooltip` | `map` | Список столбцов, которые показывает подсказка точки: `[name, passengers]` |

Атрибуты-столбцы называют столбцы результата запроса, сопоставляясь без учёта
регистра. Простое имя пишите без кавычек (`x = date`); имя, не являющееся простым
идентификатором, заключайте в кавычки (`y = "revenue (EUR)"`). Атрибут, который типу
графика не нужен, — `lat` у линейной диаграммы, `x` у карты, `series` у круговой, —
это ошибка, а не то, что молча игнорируется.

### filter

| Атрибут | Обязателен | Значение |
| --- | --- | --- |
| `plot` | да | График, на котором щелчок выбирает значение: `plot.revenue_by_channel`. `bar`, `stacked_bar` или `table` |
| `column` | для `table` | Столбец, значение которого выбирается. Для `bar` или `stacked_bar` — его `x`, если не указан |
| `multiple` | `bar`, `stacked_bar` | `true` делает так, что каждый щелчок добавляет своё значение, а второй щелчок убирает его; `$name` становится `IN (…)`. Таблица выбирает одну строку, поэтому `multiple` для таблицы — ошибка проверки |

О том, что делает фильтр, см. [Фильтры](#filters).

### dashboard

Один необязательный блок `dashboard` содержит настройки для всего файла:

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

`timezone` — часовой пояс, в котором показывается каждый `TIMESTAMPTZ` дашборда;
пояс указывается над графиками. Принимаются смещение (`"+08:00"`), `"UTC"` и
`"local"`; имена IANA, такие как `Asia/Shanghai`, — нет. Обычный `TIMESTAMP` не
имеет пояса и показывается как записан, а столбец, по которому выбирает фильтр,
сохраняет хранимое значение, чтобы выбор продолжал совпадать. Файл содержит не
более одного блока `dashboard`.

## Типы графиков {#plot-types}

| Тип | Что рисует |
| --- | --- |
| `line` | Линию на каждую серию, без заливки |
| `area` | Залитую область на каждую серию |
| `bar` | Столбик на каждую строку, по одному цвету на серию. С `series` столбики серий стоят рядом в каждой группе. При одной серии каждый столбик подписывается своим значением |
| `stacked_bar` | Один столбик на каждый `x` с уложенными друг на друга `series`: положительные части вверх от нуля, отрицательные вниз, итог сверху и во всплывающей подсказке |
| `heatmap` | `x` по горизонтали и `series` по вертикали, каждая ячейка раскрашена по `y` в одной синей гамме, темнее при большем значении (светлее в тёмной теме). Пара, которую запрос не возвращает, остаётся пустой |
| `histogram` | Строки, подсчитанные в каждом диапазоне числового `x`, с корзинами круглой ширины. Пусть его запрос возвращает сами строки, а не группировку |
| `scatter` | Точку на каждую точку данных, без соединения, по одному цвету на серию |
| `pie` | Один срез на каждое значение `x` с размером по `y`, от большего к меньшему; после 8 срезов самые маленькие объединяются в «прочие». Рисуется кольцом с итогом в середине; щёлкните запись в легенде, чтобы выделить срез, и ещё раз, чтобы вернуть |
| `text` | Заголовок, пояснительный текст или и то и другое; запрос не выполняется |
| `map` | Точку на каждую строку в её `lat` и `lng`; см. [Карты](#maps) |
| `timeline` | Одно событие на каждую строку в её момент `x`, размещённое по реальному расстоянию от других, так что промежутки видны. `series` даёт каждому участнику дорожку, `caption` говорит, что произошло, а `tooltip` перечисляет столбцы, показываемые при наведении. Не принимает `y`; рисует не более 12 дорожек и 1 000 событий (дальше прореживаются равномерно, о чём сообщается), а строки, время которых не читается, подсчитывает, а не рисует |
| `table` | Результат запроса в виде таблицы, столбцы подогнаны под содержимое; щёлкните заголовок, чтобы отсортировать |
| `card` | Одно число крупно, с `title` в качестве подписи. Разряды группируются, длинная дробь округляется (`11439704.020000005` → `11,439,704.02`), а значение уменьшается, чтобы поместиться в карточку, а не обрезается |

Наведите курсор на график, чтобы увидеть значения в том формате, в каком их
показывает ось (`4.4M`, а не `4400000`).

Столбчатая диаграмма подписывает **каждую** категорию. Когда подписи не помещаются
под столбиками, диаграмма ложится на бок, а подписи встают столбцом слева. Только
ось времени прореживает подписи, оставляя столько, сколько помещается, — всегда
первую и последнюю, — а столбик по столбцу `DATE` заполняет дни, по которым запрос
ничего не вернул, пустыми полосами, чтобы затишье читалось как разрыв, а не
исчезало. Оси линейной, площадной и точечной диаграмм прореживают подписи так же.

Ось x для всех типов графиков категориальная: значения располагаются равномерно в
том порядке, в каком их возвращает запрос, а не по расстоянию между ними. Поэтому
`scatter` по двум числовым столбцам — не настоящий график x–y.

Строки рисуются в том порядке, в каком их возвращает запрос, поэтому завершайте
запрос, питающий график, выражением `ORDER BY`.

::: info Новое в 0.4.0
`line` или `scatter` дашборда по времени размещается по времени, поэтому
неравномерные промежутки выглядят неравномерными, а рисуется он в порядке времени
независимо от `ORDER BY`. Строка с NULL во времени опускается, о чём есть
примечание. NULL-значение, возвращённое запросом, разрывает линию. `area`
остаётся равномерно распределённой и сообщает об этом. Серия сохраняет свой цвет
по имени, а каждый график сообщает, если его запрос был усечён.
:::

Карточка показывает первую строку своего запроса. Когда запрос возвращает больше
одной строки, карточка сообщает об этом под числом; когда он не возвращает ни
одной, она показывает `—`.

### Карточки и текстовые панели {#cards-and-text-panels}

Карточки могут пояснять число через `note` и давать ему цвет состояния через
`tone`. Карточки в одной строке делят размер шрифта значения. Текстовые панели
добавляют заголовки или контекст, не выполняя 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
}
```

Текстовая панель принимает только `type`, `title`, `text` и `width`. Для более
длинного пояснения используйте `text = <<TEXT` с закрывающей строкой `TEXT`.
Диаграммы, круговые и карты используют восемь различимых оттенков, подстроенных
под текущую тему, и легенду при нескольких сериях.

### Форматы чисел и изменение {#number-formats-and-change}

`format` задаёт вид значения карточки, оси значений, подписей столбиков и
всплывающих подсказок:

| Значение | Читается как |
| --- | --- |
| `"num0"`, `"num1"`, `"num2"` | Число с указанным числом знаков после запятой |
| `"pct"` (то же, что `"pct1"`), `"pct0"`, `"pct2"` | Доля: 0.421 читается как 42,1 %, поэтому возвращайте дробь, а не ×100 |
| `"usd"`, `"eur"`, `"gbp"`, `"cny"` | Деньги с двумя знаками после запятой |
| `"usd0"`, `"eur0"`, `"gbp0"`, `"cny0"`, `"jpy"` | Деньги в целых единицах |

Карточка показывает изменение через `delta` под значением в виде `▲ 12.3%` или
`▼ $125`. Оно зелёное, когда изменение хорошее, и красное, когда нет, а `note`
следует за ним и говорит, по сравнению с чем. Вычисляйте изменение в запросе
карточки:

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

### Компоновка {#layout}

`width` — сколько из двенадцати столбцов дашборда занимает график. Графики
заполняют строку слева в том порядке, в каком записаны, и переносятся, когда
следующий не помещается, поэтому четыре карточки (по `3`) образуют строку чисел, а
две диаграммы с `width = 6` стоят рядом под ними. Строка, которой не хватает до
двенадцати, оставляет остаток пустым. Строка из одних карточек начинается с
небольшой высоты, строка из одних таблиц — с высоты самой длинной своей таблицы, но
не больше высоты графика. Строка из текстовых панелей подстраивается под свой текст;
остальные строки начинаются с высоты графика. Маркеры изменения размера строк
появляются при наведении.

### Карты {#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]
}
```

Карта рисует каждую строку точкой в проекции Web Mercator, подогнанной под точки,
поверх сетки широты и долготы с подписями в градусах.

- **`color`**: до пяти значений получают по цвету; при большем числе четыре самых
  частых получают цвета, а остальные делят цвет «прочие». Легенда отображает их
  обратно. Если не указан, точки раскрашиваются по текстовому столбцу лишь с
  несколькими уникальными значениями, когда такой столбец есть в результате.
- **`size`**: *площадь* точки следует за значением, поэтому вдвое большее значение
  даёт вдвое больше краски. `size_scale = "log"` подходит для значений,
  охватывающих порядки величины. Легенда в углу расшифровывает размеры.
- **`tooltip`**: без него всплывающая подсказка точки перечисляет столбец размера и
  остальные числа, затем координаты.

Под точками карта может рисовать базовую карту **OpenStreetMap**. Она выключена,
пока вы не включите её через **Вид → Онлайн-подложка (OpenStreetMap)**, потому что
для загрузки плиток нужна сеть. Отправляется только то, какие плитки нужны, что
примерно выявляет просматриваемую область и никогда — строку ваших данных. Плитки
кэшируются на диске на неделю (см. [Настройки и данные
приложения](settings-and-data.md#where-things-are-stored)); без сети или при
выключенной подложке карта рисуется только поверх сетки широты и долготы. Тот же
переключатель действует для карты на вкладке **График** результатов запроса.

## Фильтры {#filters}

Фильтр делает график кликабельным и позволяет выбранному на нём значению сужать
другие запросы:

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

Запрос читает фильтр как **`$name`, условие**: пишите его там, где должно стоять
условие. Пока ничего не выбрано, это `TRUE`, поэтому дашборд открывается точно так
же, как без фильтра. Как только значение выбрано, оно становится
`("channel" = 'Web')` — столбец, названный в `column` фильтра, сравнивается с
выбранным значением; ячейка, отображаемая как `NULL`, совпадает с SQL NULL или с
литеральным текстом `NULL`. При `multiple = true` для столбчатой или уложенной
диаграммы каждый щелчок добавляет своё значение, а второй щелчок убирает его, и
`$name` становится `("channel" IN ('Web', 'App'))`, с `OR "channel" IS NULL`,
когда NULL входит в их число. Несколько фильтров сочетаются так, как их сочетает
запрос.

- **На столбчатой диаграмме** щёлкните столбик, чтобы выбрать его: он сохраняет
  свой цвет, а остальные тускнеют. Щёлкните его снова, чтобы снять выбор. При
  `multiple = true` каждый щелчок добавляет значение, а второй щелчок убирает его.
- **На таблице** выберите строку щелчком или стрелками.
- Действующие выборы показываются чипами над графиками; ✕ на каждом чипе сбрасывает
  его фильтр, а **Сбросить все** сбрасывает все выборы. Фильтр с множественным
  выбором показывает по одному чипу на каждое выбранное значение.
- **График, на котором выбирают, никогда не сужается своим собственным фильтром.**
  Его запрос читает `$channel` как `TRUE`, даже когда канал выбран, — иначе один
  щелчок свёл бы столбчатую диаграмму к только что нажатому столбику, и щёлкать
  дальше было бы не по чему. Это перекрёстная фильтрация, как в Mosaic или
  crossfilter.
- **Повторно выполняются только изменившиеся запросы.** Выбор заново выполняет
  запросы, чей SQL он меняет; запрос, не читающий фильтр, сохраняет свой результат.

Фильтр хранит одно значение за раз или несколько при `multiple = true`. Графики, на
которых можно выбирать, показывают под заголовком подсказку о фильтрации щелчком.
Серии сохраняют свои цвета, когда фильтрация меняет оставшиеся группы. Запрос,
использующий `$channel`, должен предоставлять столбец фильтра там, где используется
это условие; `ducklocal check` теперь связывает и вариант с выбранным значением,
поэтому отсутствующий столбец обнаруживается до первого щелчка.

::: info Новое в 0.4.0
Выбор ячейки, отображаемой как `NULL`, выбирает только SQL NULL, а текст `'NULL'` —
только сам себя. Графики, на которых можно выбирать, больше не показывают подсказку
о фильтрации щелчком под заголовком.
:::

Выбранное значение попадает в SQL как литерал в кавычках, и DuckDB приводит его к
типу столбца при сравнении, поэтому даты и числа работают так же, как текст. Выборы
действуют, пока открыта вкладка, и переживают перезагрузку, если фильтр ещё есть в
файле; между запусками они не запоминаются.

## Значения

| Форма | Пример | Используется для |
| --- | --- | --- |
| Строка | `"Revenue by channel"` | `type`, `title`, `path`, `size_scale`, `tone`, литерал `note`, `text`, имена столбцов в кавычках, короткий `sql` |
| Heredoc | `<<SQL` … `SQL` | `sql`, `text` |
| Ссылка | `query.daily`, `plot.revenue_by_channel` | `query` графика, `plot` фильтра |
| Голое имя | `channel` | атрибуты-столбцы |
| Число | `6` | `width` |
| Список | `[name, "Unique IPs"]` | `tooltip` |

Строка заканчивается на своей строке и понимает `\n`, `\t`, `\"` и `\\`.

`#` и `//` начинают комментарий, который длится до конца строки. Атрибутам не нужен
разделитель; переводы строк — просто пробельные символы.

Это весь язык: никаких переменных, функций, условий и никакой интерполяции, кроме
`$name` фильтра.

### Heredoc-блоки {#heredocs}

Heredoc хранит текст на нескольких строках — на практике SQL:

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

- Разделитель после `<<` — любое слово (по соглашению `SQL`), и в его строке после
  него не должно быть ничего.
- Heredoc заканчивается на первой строке, которая точно совпадает с разделителем, с
  точностью до окружающих пробелов.
- Отступ закрывающей строки удаляется из каждой строки текста, поэтому SQL может
  стоять на отступе блока, не неся его с собой.

## Правила SQL {#sql-rules}

Дашборд выполняет свои запросы при каждом открытии, перезагрузке или сохранении, а
также когда DuckLocal запускается с восстановленной вкладкой, поэтому запрос может
только **читать**:

- **Разрешено:** `SELECT`, `WITH …`, запросы, начинающиеся с `FROM`, `VALUES`,
  `SHOW`, `DESCRIBE`, `SUMMARIZE`, `PIVOT` и `UNPIVOT`.
- **Запрещено:** всё, что может изменить данные или файлы, — `CREATE`, `INSERT`,
  `UPDATE`, `DELETE`, `DROP`, `COPY`, `ATTACH`, `INSTALL`, `LOAD` и так далее.
  Открытие присланного вам файла `.dash` не может изменить ваши данные.
- **Одна инструкция на запрос.**
- **`PIVOT` внутри другого запроса называет свои значения.** Запрос, начинающийся
  с `PIVOT`, может оставить значения на усмотрение DuckDB
  (`PIVOT orders ON channel USING sum(amount)`). Вложенному в `SELECT` или `WITH`
  нужен явный список: `ON channel IN ('Web', 'Store')`.
- **`$name` должен называть блок filter.** Проверка только для чтения оценивает
  SQL, считая каждый `$name` равным `TRUE`. `$` внутри строки, идентификатора в
  кавычках, комментария или строки `$$ … $$` не затрагивается.

Запросы выполняются в собственном подключении окна, поэтому видят всё то же, что и
редактор SQL: открытые файлы, присоединённые базы данных и состояние уровня
подключения, например таблицы `TEMP`.

### Пути в SQL

Начиная с v0.2.2 относительные пути к файлам в SQL дашборда ищутся и от папки
файла `.dash`. Например, `FROM 'sales.csv'` может прочитать CSV рядом с дашбордом,
даже если его открывают из другого каталога. Это действует и в окне, и в
`ducklocal check`.

DuckDB по-прежнему сначала проверяет рабочий каталог для одного файла, названного
непосредственно в SQL: файл с тем же именем там может иметь приоритет.
Блок [source](#source) разрешает свой путь явно относительно папки дашборда и
избегает этой неоднозначности. Абсолютные пути и зарегистрированные представления
остаются доступными.

## Ограничения

| Ограничение | Что происходит |
| --- | --- |
| 12 серий на график | Дальнейшие серии опускаются, а уведомление сообщает, сколько их было |
| 1 500 точек на серию | Точки усредняются по корзинам, чтобы поместиться |
| 200 столбиков | Дальнейшие столбики опускаются |
| 8 срезов круговой диаграммы | Самые маленькие объединяются в один срез «прочие» |
| 200 столбцов и 12 строк тепловой карты | Дальнейшие столбцы и строки опускаются |
| 5–40 корзин гистограммы | Примерно √строк, каждая шириной 1, 2, 2,5 или 5 × степень десяти |
| 20 000 точек карты | Дальнейшие точки опускаются, и уведомление об этом сообщает |
| 12 дорожек и 1 000 событий на временную шкалу | Дальнейшие события прореживаются равномерно, о чём сообщает уведомление; строки, время которых не читается, подсчитываются, а не рисуются |

## Проверка дашборда {#validate-a-dashboard}

`ducklocal check` проверяет файл, не открывая окно, — это шаг, который стоит
выполнить, прежде чем передать дашборд кому-либо:

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

Сначала статические проверки: синтаксис, имена и ссылки, обязательные атрибуты,
каждый `$name` против блоков filter, и SQL каждого запроса через собственный парсер
DuckDB. Затем **выполняется каждый запрос** в режиме только чтения, со своими
источниками и без выбранных значений, а столбцы каждого графика сверяются со
столбцами, которые его запрос действительно возвращает, — в том числе что `y`,
координаты карты и её `size` числовые, и что `column` каждого фильтра есть среди
возвращаемых запросом его графика. Выполнение важно: неудачное приведение типа или
шаблон, не совпавший ни с чем, обнаруживаются только при чтении строк.

- **Без `--database`** запросы выполняются в памяти — этого достаточно дашборду на
  собственных файлах `source`. Запрос, читающий таблицу, которую не определяет ни
  один источник, попадает в `unresolved`, а не в ошибки, а столбцы его графиков не
  проверяются: вероятно, он предназначен для базы данных.
- **С `--database PATH`** они выполняются на этой базе данных, открытой только для
  чтения. Передавайте его всегда, когда запросы читают таблицы базы данных.

Каждый запрос, использующий фильтр, дополнительно связывается с выбранным значением
без выполнения этого варианта. Так обнаруживаются условия, ссылающиеся на столбец,
недоступный в этом запросе. Блоки с ошибками не мешают проверке корректных блоков:
диагностика включает и ошибки спецификации, и сбои запросов из одного и того же
запуска.

При успехе выводится JSON-сводка источников, запросов (с их столбцами результата и
числом `rows`, которое вернул каждый), фильтров и графиков, а также `empty`:
запросы, которые выполнились и не вернули строк. Это не ошибка, но обычно
регулярное выражение, фильтр или соединение, не совпавшие ни с чем, поэтому
проверьте каждый перед передачей дашборда. `--summary` выводит одну строку JSON с
подсчётами и именами неразрешённых и пустых запросов. Ошибка завершается со
статусом **2** для диагностики спецификации и перечисляет все проблемы сразу, по
одной `file:line: message` на каждую. Сбои только SQL, базы данных или файла
завершаются с **1**. Подробности — в [руководстве по
CLI](cli.md#check-a-dashboard-spec).

::: info Новое в 0.4.0
`ducklocal check FILE --restricted --allow-read PATH` проверяет с ограничениями
дашборд, который написали не вы. См. [Ограничение SQL, который написали не
вы](agent-workflows.md#restricted).
:::

### Частые сообщения

| Сообщение | Решение |
| --- | --- |
| `type is a string in quotes` | Напишите `type = "line"`, а не `type = line` |
| `Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, text` | Используйте один из перечисленных типов |
| `plot block "p" requires y` | Каждому типу диаграммы нужен `y`; `table`, `map`, `card` и `text` — нет |
| `plot "p" draws query "q", which the file does not define` | Добавьте блок query или исправьте имя в `query = query.…` |
| `query names a query block: query = query.some_name` | Атрибут `query` принимает ссылку, а не строку |
| `plot "p" draws y = "channel" (VARCHAR), which is not numeric` | Направьте `y` на числовой столбец или используйте `type = "table"` |
| `A map plot places points by lat and lng; it takes no x` | У карты нет осей: задайте `lat` и `lng` или оставьте это именам столбцов |
| `width is how many of the dashboard's 12 columns the plot spans` | Напишите целое число от 1 до 12 |
| `query "q" reads $chanel, but no filter block is named "chanel"` | Исправьте имя или добавьте блок `filter` |
| `filter "f" picks on plot "p", a line; a value is picked on a bar or table plot` | Направьте фильтр на столбчатую диаграмму или таблицу |
| `a dashboard query must be a single read-only statement` | Перенесите записи в редактор SQL или назовите значения вложенного `PIVOT` через `IN`; см. [Правила SQL](#sql-rules) |
| `Unknown block: "card"; a card is a plot: plot "x" { type = "card" … }` | Каждая панель — это блок plot, включая карточки и текстовые панели |
| `"minutes" is a SQL keyword, so as a column alias it needs AS` | Напишите `count(*) AS minutes` или заключите псевдоним в кавычки |
| `Unterminated heredoc: no line is exactly SQL` | Добавьте закрывающий разделитель на отдельной строке |

## Редактирование в своём редакторе

`ducklocal lsp` — это языковой сервер для файлов `.dash`: диагностика по мере ввода,
дополнение типов блоков, атрибутов, типов графиков и имён после `query.` и `plot.`,
документация при наведении и переход к определению от ссылки `query.name` или
`plot.name` к её блоку. Настройка для Neovim и VS Code — в [руководстве по
CLI](cli.md#edit-a-dashboard-spec-with-lsp).
