Дашборды (.dash)
Файл .dash описывает дашборд как данные: блоки source называют файлы данных, блоки query содержат SQL, блоки plot рисуют результаты, а блоки filter позволяют щелчком на одном графике сузить остальные. Писать код не нужно. И люди, и ИИ-агенты могут создать файл, просмотреть его в диффе и проверить до того, как кто-либо его откроет.
Файл .dash строит обычные графики, таблицы, числа и карты по сохранённым запросам. Его текстовый формат также удобен для работы с ИИ-агентом: агент пишет или правит файл, ducklocal check проверяет, что он выполняется, а вы комментируете графики, чтобы попросить изменения.
Полный пример
Этот дашборд запрашивает файл из учебника. Скачайте sales.dash в тот же каталог, где лежит sales.csv, и откройте его.
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).
Графики располагаются на сетке из 12 столбцов: каждый занимает свою width, графики заполняют строку слева направо, а график, который больше не помещается, начинает следующую строку. Перетаскивайте разделители между строками, чтобы менять их размер; дашборд выше вкладки прокручивается. График, который не может отрисоваться, — его запрос завершился ошибкой или отсутствует столбец — показывает причину в собственной панели, а остальная часть дашборда продолжает рисоваться. Открытые дашборды возвращаются при следующем запуске, а недавно открытые перечислены в разделе Дашборды боковой панели.
Наведите курсор на график, чтобы увидеть его элементы управления в правом верхнем углу:
- SQL показывает SQL, который последним выполнял запрос этого графика — с подставленными источниками и текущими выбранными значениями фильтров, так что он выполняется в текущем виде, — вместе с Копировать и Открыть во вкладке запроса. График возвращает обратно.
- Значок диалога открывает комментарии графика.
- Развернуть этот график расширяет его на всю вкладку дашборда. Используйте Назад к дашборду (Esc) или нажмите Esc, чтобы вернуться к сетке.
В представлении SQL есть подсветка синтаксиса. Щёлкните правой кнопкой по ячейке таблицы дашборда, чтобы скопировать ячейку, её строку с разделителями-табуляциями или её столбец в отображаемом порядке.
Щёлкните заголовок столбца графика table, чтобы отсортировать его: по убыванию, по возрастанию, затем снова в порядке запроса. Числа сортируются как числа, а NULL — последним; строка, выбранная для фильтра, остаётся выбранной и после сортировки.
Просмотр спецификации на панели инструментов переключает вкладку на редактор файла с подсветкой синтаксиса (SQL в heredoc-блоках раскрашивается как в редакторе SQL), автодополнением и диагностикой по ходу ввода. Сохранить или ⌘S записывает изменения и перерисовывает дашборд. Если сохранённый файл не проходит проверку, вкладка сохраняет последний рабочий дашборд и показывает ошибку над ним. То же происходит, когда файл меняет другая программа. Назад к дашборду возвращает к графикам. Перезагрузить перечитывает файл и заново выполняет все запросы.
Рецензирование с комментариями
Комментарии позволяют рецензировать дашборд как документ и передавать изменения ИИ-агенту. Идея этого сценария разобрана в статье What Claude Dashboards taught me about DuckLocal.
В окне наведите курсор на график и нажмите значок диалога. Поверх дашборда открывается карточка с заголовком графика, уже имеющимися обсуждениями и полем для ввода. Напишите, что нужно изменить, — «отсортируй по величине канала, начиная с самого большого» — и нажмите Комментировать (или ⌘/Ctrl+Enter). У каждого обсуждения есть Ответить и Решено; решённое обсуждение остаётся приглушённым, пока кто-нибудь на него не ответит. У графика с открытыми обсуждениями остаётся значок с их числом, так что сразу видно, что ждёт ответа.
Агент читает и отвечает на обсуждения с помощью ducklocal comments, окно ему не нужно:
ducklocal comments sales.dash{
"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 и отвечает:
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" --resolveОкно следит за обоими файлами. В течение секунды график перерисовывается по изменённой спецификации, а ответ агента появляется в его обсуждении с пометкой Агент.
Обсуждения хранятся рядом с дашбордом, в NAME.dash.comments.json, поэтому они перемещаются вместе с ним, как и его файлы source. Это рабочие заметки, а не часть дашборда: не добавляйте их в систему контроля версий или удалите файл, когда рецензирование закончено.
Этому циклу учит официальный навык для агентов, поэтому агенту с этим навыком достаточно сказать «ответь на комментарии в sales.dash».
Новое в 0.4.0
Агент может предложить изменение, а не редактировать файл. Тогда вкладка предлагает Проверить с диффом и проверками, и применить его можете только вы.
Посмотрите, как работает агент
Пока агент выполняет check, comments или presence для этого открытого дашборда, его имя появляется в углу вместе со знаком его создателя — Claude, OpenAI, Gemini, Cursor, DeepSeek — или его инициалом. Нажмите на имя, чтобы увидеть журнал сеанса. Когда он редактирует файл, изменённые и добавленные графики остаются помеченными (Claude изменил это, Claude добавил это), пока вы некоторое время на них не посмотрите; удалённый график оставляет уведомление, которое можно закрыть.
Агент может объявить о следующей правке: ducklocal presence sales.dash --doing editing --plot revenue_by_channel. Этот график получает рамку; имя графика, которого ещё нет, получает заглушку под дашбордом. Сеанс завершается после 30 секунд без активности или при явном --doing idle. Завершивший работу агент остаётся в углу, пока обсуждение, на которое он ответил, ждёт вашего ответа, а на его аватаре показано число. Комментарии фиксируют, какой агент их написал, и показывают его знак. Параметры описаны в справочнике CLI. Эти индикаторы показывают локальную активность; они не отправляют работу агенту.
Блоки
Файл — это последовательность блоков, каждый из которых состоит из типа, имени в кавычках и тела:
source "name" { ... }
view "name" { ... }
query "name" { ... }
plot "name" { ... }
filter "name" { ... }
dashboard "name" { ... }Имена должны быть уникальны в пределах своего типа: два запроса не могут иметь одинаковое имя, как и два графика, — но запрос и график могут.
Новое в 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 по тем же правилам, что и у запроса, и каждый запрос, который его называет, читает его как таблицу:
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 или строки |
Блок query содержит sql и ничего больше. Он может читать $name для фильтра.
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 | Что представляют собой числа: см. Форматы чисел и изменение. 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 для таблицы — ошибка проверки |
О том, что делает фильтр, см. Фильтры.
dashboard
Один необязательный блок dashboard содержит настройки для всего файла:
dashboard "Ops" {
timezone = "+08:00" # or "UTC", or "local"
}timezone — часовой пояс, в котором показывается каждый TIMESTAMPTZ дашборда; пояс указывается над графиками. Принимаются смещение ("+08:00"), "UTC" и "local"; имена IANA, такие как Asia/Shanghai, — нет. Обычный TIMESTAMP не имеет пояса и показывается как записан, а столбец, по которому выбирает фильтр, сохраняет хранимое значение, чтобы выбор продолжал совпадать. Файл содержит не более одного блока dashboard.
Типы графиков
| Тип | Что рисует |
|---|---|
line | Линию на каждую серию, без заливки |
area | Залитую область на каждую серию |
bar | Столбик на каждую строку, по одному цвету на серию. С series столбики серий стоят рядом в каждой группе. При одной серии каждый столбик подписывается своим значением |
stacked_bar | Один столбик на каждый x с уложенными друг на друга series: положительные части вверх от нуля, отрицательные вниз, итог сверху и во всплывающей подсказке |
heatmap | x по горизонтали и series по вертикали, каждая ячейка раскрашена по y в одной синей гамме, темнее при большем значении (светлее в тёмной теме). Пара, которую запрос не возвращает, остаётся пустой |
histogram | Строки, подсчитанные в каждом диапазоне числового x, с корзинами круглой ширины. Пусть его запрос возвращает сами строки, а не группировку |
scatter | Точку на каждую точку данных, без соединения, по одному цвету на серию |
pie | Один срез на каждое значение x с размером по y, от большего к меньшему; после 8 срезов самые маленькие объединяются в «прочие». Рисуется кольцом с итогом в середине; щёлкните запись в легенде, чтобы выделить срез, и ещё раз, чтобы вернуть |
text | Заголовок, пояснительный текст или и то и другое; запрос не выполняется |
map | Точку на каждую строку в её lat и lng; см. Карты |
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.
Новое в 0.4.0
line или scatter дашборда по времени размещается по времени, поэтому неравномерные промежутки выглядят неравномерными, а рисуется он в порядке времени независимо от ORDER BY. Строка с NULL во времени опускается, о чём есть примечание. NULL-значение, возвращённое запросом, разрывает линию. area остаётся равномерно распределённой и сообщает об этом. Серия сохраняет свой цвет по имени, а каждый график сообщает, если его запрос был усечён.
Карточка показывает первую строку своего запроса. Когда запрос возвращает больше одной строки, карточка сообщает об этом под числом; когда он не возвращает ни одной, она показывает —.
Карточки и текстовые панели
Карточки могут пояснять число через note и давать ему цвет состояния через tone. Карточки в одной строке делят размер шрифта значения. Текстовые панели добавляют заголовки или контекст, не выполняя SQL:
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. Диаграммы, круговые и карты используют восемь различимых оттенков, подстроенных под текущую тему, и легенду при нескольких сериях.
Форматы чисел и изменение
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 следует за ним и говорит, по сравнению с чем. Вычисляйте изменение в запросе карточки:
plot "revenue_total" {
type = "card"
query = query.totals
value = revenue
format = "usd0"
delta = growth
delta_format = "pct1"
note = "vs last week"
}Компоновка
width — сколько из двенадцати столбцов дашборда занимает график. Графики заполняют строку слева в том порядке, в каком записаны, и переносятся, когда следующий не помещается, поэтому четыре карточки (по 3) образуют строку чисел, а две диаграммы с width = 6 стоят рядом под ними. Строка, которой не хватает до двенадцати, оставляет остаток пустым. Строка из одних карточек начинается с небольшой высоты, строка из одних таблиц — с высоты самой длинной своей таблицы, но не больше высоты графика. Строка из текстовых панелей подстраивается под свой текст; остальные строки начинаются с высоты графика. Маркеры изменения размера строк появляются при наведении.
Карты
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), потому что для загрузки плиток нужна сеть. Отправляется только то, какие плитки нужны, что примерно выявляет просматриваемую область и никогда — строку ваших данных. Плитки кэшируются на диске на неделю (см. Настройки и данные приложения); без сети или при выключенной подложке карта рисуется только поверх сетки широты и долготы. Тот же переключатель действует для карты на вкладке График результатов запроса.
Фильтры
Фильтр делает график кликабельным и позволяет выбранному на нём значению сужать другие запросы:
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 теперь связывает и вариант с выбранным значением, поэтому отсутствующий столбец обнаруживается до первого щелчка.
Новое в 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-блоки
Heredoc хранит текст на нескольких строках — на практике SQL:
sql = <<SQL
SELECT 1
SQL- Разделитель после
<<— любое слово (по соглашениюSQL), и в его строке после него не должно быть ничего. - Heredoc заканчивается на первой строке, которая точно совпадает с разделителем, с точностью до окружающих пробелов.
- Отступ закрывающей строки удаляется из каждой строки текста, поэтому SQL может стоять на отступе блока, не неся его с собой.
Правила SQL
Дашборд выполняет свои запросы при каждом открытии, перезагрузке или сохранении, а также когда 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 разрешает свой путь явно относительно папки дашборда и избегает этой неоднозначности. Абсолютные пути и зарегистрированные представления остаются доступными.
Ограничения
| Ограничение | Что происходит |
|---|---|
| 12 серий на график | Дальнейшие серии опускаются, а уведомление сообщает, сколько их было |
| 1 500 точек на серию | Точки усредняются по корзинам, чтобы поместиться |
| 200 столбиков | Дальнейшие столбики опускаются |
| 8 срезов круговой диаграммы | Самые маленькие объединяются в один срез «прочие» |
| 200 столбцов и 12 строк тепловой карты | Дальнейшие столбцы и строки опускаются |
| 5–40 корзин гистограммы | Примерно √строк, каждая шириной 1, 2, 2,5 или 5 × степень десяти |
| 20 000 точек карты | Дальнейшие точки опускаются, и уведомление об этом сообщает |
| 12 дорожек и 1 000 событий на временную шкалу | Дальнейшие события прореживаются равномерно, о чём сообщает уведомление; строки, время которых не читается, подсчитываются, а не рисуются |
Проверка дашборда
ducklocal check проверяет файл, не открывая окно, — это шаг, который стоит выполнить, прежде чем передать дашборд кому-либо:
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.
Новое в 0.4.0
ducklocal check FILE --restricted --allow-read PATH проверяет с ограничениями дашборд, который написали не вы. См. Ограничение SQL, который написали не вы.
Частые сообщения
| Сообщение | Решение |
|---|---|
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 |
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.
