Перейти к содержимому

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

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

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

Полный пример ​

Этот дашборд запрашивает файл из учебника. Скачайте 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).

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

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

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

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

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

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

Рецензирование с комментариями ​

Комментарии позволяют рецензировать дашборд как документ и передавать изменения ИИ-агенту. Идея этого сценария разобрана в статье What Claude Dashboards taught me about DuckLocal.

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

Агент читает и отвечает на обсуждения с помощью ducklocal comments, окно ему не нужно:

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. Это рабочие заметки, а не часть дашборда: не добавляйте их в систему контроля версий или удалите файл, когда рецензирование закончено.

Этому циклу учит официальный навык для агентов, поэтому агенту с этим навыком достаточно сказать «ответь на комментарии в 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. Эти индикаторы показывают локальную активность; они не отправляют работу агенту.

Блоки ​

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

hcl
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 по тем же правилам, что и у запроса, и каждый запрос, который его называет, читает его как таблицу:

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 или строки

Блок 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 его не принимают
seriesline, bar, stacked_bar, area, scatter, heatmap, timelineСтолбец, значения которого разбивают строки на отдельные серии; строки heatmap; дорожки timeline
titleвсеЗаголовок графика в виде строки в кавычках; подпись карточки
widthвсеСколько из 12 столбцов сетки занимает график, 1–12. По умолчанию 12 или 3 для карточки
valuecardСтолбец для показа из первой строки. По умолчанию: первый столбец
notecardТекст под значением: строка в кавычках или имя столбца без кавычек, чтобы взять его из первой строки
tonecard"accent", "good", "warning" или "critical"; задаёт цвет верхней линии и значения
formatграфики и cardЧто представляют собой числа: см. Форматы чисел и изменение. map и table его не принимают
deltacardЧисловой столбец с изменением, показывается под значением
delta_formatcardФормат изменения. По умолчанию: формат карточки
down_is_goodcardtrue делает падение зелёным, а рост красным — для затрат, задержек или оттока
descriptionвсе, 0.4.0+Что показывает график и как его читать; появляется при наведении на ⓘ рядом с заголовком
texttextОсновной текст в виде строки или heredoc; укажите title, text или и то и другое, без query
captiontimelineСтолбец, говорящий, чем было каждое событие; пишется под его точкой, если помещается, и при наведении
lat, lngmapСтолбцы широты и долготы в градусах. Любой из них можно опустить, если имя числового столбца указывает на координату — lat, latitude, geo_lat; lng, lon, longitude
colormapСтолбец для раскраски точек; если не указан, он выбирается, когда текстовый столбец имеет лишь несколько значений
sizemapЧисловой столбец для размера точек
size_scalemap"sqrt" (по умолчанию) или "log" — как масштабируется size
tooltipmapСписок столбцов, которые показывает подсказка точки: [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, если не указан
multiplebar, stacked_bartrue делает так, что каждый щелчок добавляет своё значение, а второй щелчок убирает его; $name становится IN (…). Таблица выбирает одну строку, поэтому multiple для таблицы — ошибка проверки

О том, что делает фильтр, см. Фильтры.

dashboard ​

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

hcl
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: положительные части вверх от нуля, отрицательные вниз, итог сверху и во всплывающей подсказке
heatmapx по горизонтали и 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:

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. Диаграммы, круговые и карты используют восемь различимых оттенков, подстроенных под текущую тему, и легенду при нескольких сериях.

Форматы чисел и изменение ​

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

Компоновка ​

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

Карты ​

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), потому что для загрузки плиток нужна сеть. Отправляется только то, какие плитки нужны, что примерно выявляет просматриваемую область и никогда — строку ваших данных. Плитки кэшируются на диске на неделю (см. Настройки и данные приложения); без сети или при выключенной подложке карта рисуется только поверх сетки широты и долготы. Тот же переключатель действует для карты на вкладке График результатов запроса.

Фильтры ​

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

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 теперь связывает и вариант с выбранным значением, поэтому отсутствующий столбец обнаруживается до первого щелчка.

Новое в 0.4.0

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

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

Значения ​

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

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

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

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

Heredoc-блоки ​

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

hcl
  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 проверяет файл, не открывая окно, — это шаг, который стоит выполнить, прежде чем передать дашборд кому-либо:

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.

Новое в 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.

Опубликовано под лицензией Apache-2.0.