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

CLI для ИИ и официальный навык ​

Обзор, ориентированный на задачи, см. в разделе SQL для ИИ-агентов на локальных данных. Эта страница — полный справочник по командам и выводу.

Запуск без окна ​

ducklocal --help перечисляет десять подкоманд:

КомандаЧто делает
ducklocal queryВыполняет одну инструкцию SQL и печатает результат как JSON
ducklocal schemaПеречисляет, что можно запрашивать, со столбцами; --stats — статистику столбцов одного отношения
ducklocal openПоказывает SQL, дашборд или данные в работающем окне; --state считывает обратно то, что оно показывает
ducklocal checkПроверяет дашборд .dash
ducklocal metricsПеречисляет метрики семантической модели; compile или query компилируют и запрашивают их
ducklocal commentsЧитает и отвечает на комментарии к обзору, оставленные людьми в дашборде
ducklocal proposeПредлагает изменение дашборда, чтобы человек его проверил и применил
ducklocal projectПроверяет переносимую папку анализа и её потребности; relink исправляет перемещённые пути
ducklocal sessionСчитывает, как анализ пришёл к своему результату
ducklocal presenceПоказывает, кто работает над открытым дашбордом и куда попадёт правка

ducklocal lsp — языковой сервер, который редакторы запускают для файлов .dash, — и ducklocal profile, устаревший псевдоним для schema --stats, по-прежнему работают, но не показываются в --help.

propose, project и session, а также параметры --restricted, --wait и --if-revision появились в 0.4.0 и описаны в разделе Работа с агентами. metrics и --format html новее 0.4.1: они уже в ветке main и войдут в следующий выпуск. metrics описана в разделе Семантические метрики.

ducklocal query выполняет SQL, не инициализируя GUI, историю, зарегистрированные файлы, языковые настройки и глобальное соединение GUI. Каждый вызов создаёт отдельное соединение. Вызов DuckLocal без команд — или только с путями к файлам, каталогами и шаблонами glob — открывает обычный GUI. Чтобы открыть в GUI путь, имя которого совпадает с командой (query, schema, open, check, metrics, comments, propose, project, session, presence, profile или lsp), поставьте перед ним ./, например ./query.

Получение команды ​

DuckLocal поддерживает macOS 12+ на Apple silicon, Windows (x86_64) и Linux (x86_64). CLI работает прямо из исполняемого файла приложения, поэтому отдельный бинарный файл DuckDB CLI устанавливать не нужно.

Быстрее всего попасть в PATH можно из приложения (0.1.1 и новее): откройте Command line & AI… — кнопку с роботом в строке заголовка или меню DuckLocal — и нажмите Install command. Тот же диалог устанавливает навык для ИИ-агентов; см. Установка официального навыка. Если пропустить установку, вызывайте исполняемый файл там, где он лежит:

bash
# macOS
/Applications/DuckLocal.app/Contents/MacOS/ducklocal --help
# Linux: wherever you extracted the tarball
./ducklocal-linux-x86_64/ducklocal --help
# Windows (PowerShell): wherever you extracted the zip
.\ducklocal-windows-x86_64\ducklocal.exe --help

Из рабочей копии исходного кода cargo build --locked собирает ./target/debug/ducklocal. Примеры ниже предполагают, что ducklocal есть в PATH. В более старых выпусках может не быть query; сначала проверьте --help. Поддержка JSON и Parquet встроена, а не скачивается во время запроса.

Параметры query ​

bash
ducklocal --help
ducklocal --version
ducklocal query --help
ducklocal query --sql "SELECT 1 AS n"
ducklocal query --sql "SELECT 1 AS n" --format md
ducklocal query --sql-file analysis.sql --limit 100
ducklocal query --sql-file - < analysis.sql
ducklocal query --database warehouse.duckdb --sql "SHOW TABLES"
  • Нужно ровно одно из --sql SQL и --sql-file FILE. Файлы должны быть в UTF-8; - читает stdin. SQL должен содержать ровно одну инструкцию. Парсер DuckDB проверяет это до открытия целевой базы данных и до любого выполнения; комментарии, точки с запятой в кавычках и завершающие точки с запятой работают. Скрипты отклоняются, а не выполняются частично.
  • --database PATH открывает существующий файл, по умолчанию только для чтения. Не указывайте его, чтобы получить новую базу данных в памяти. --read-write требует --database и явно разрешает запись и создание базы данных (но не родительских каталогов). Ошибки базы данных никогда не приводят к переходу в память. Когда DuckDB отказывается открыть файл, сообщение об ошибке начинается с причины, которую DuckLocal читает из заголовка файла — файл записан более новым DuckDB, файл эпохи v0.9, файл SQLite или вообще не база данных, — и с того, что выполнить вместо этого (для более нового файла — копию ATTACH … (STORAGE_VERSION) / COPY FROM DATABASE, которую нужно сделать в том выпуске; для SQLite — ATTACH, который его читает), — и только потом идёт собственное сообщение DuckDB.
  • --limit N — положительное целое, по умолчанию 1000, ограничивает число возвращаемых строк. Также действует бюджет в 2 000 000 ячеек. После достижения предела CLI продолжает считать ещё до 100 000 строк, не кодируя их значения, и сообщает total_rows и total_rows_exact. Это ограничивает вывод, а не вычисления или память: сортировка и агрегаты всё равно могут обрабатывать весь вход. Ошибка выполнения, возникшая после предела вывода, всё равно приводит к сбою команды.
  • --format json (по умолчанию) — это контракт, описанный ниже. --format md отображает тот же результат как таблицу Markdown для документа или агента, который его читает. --format html выводит его как одну самодостаточную веб-страницу; см. Вывод HTML. Больше ничего не меняется: тот же SQL, те же пределы, те же ошибки.
  • Повторяющиеся или неизвестные флаги, отсутствующие значения, пустой SQL и недопустимые пределы — ошибки. Параметры используют отдельные значения, а не --flag=value. Относительные пути разрешаются относительно рабочего каталога процесса, а не каталога SQL-файла. Заключайте пути оболочки в кавычки; внутри SQL удваивайте апострофы ('O''Brien.csv'). Идентификаторы SQL заключаются в двойные кавычки.

Режим только для чтения — не песочница файловой системы или сети. SQL вроде COPY может писать файлы, даже когда база данных доступна только для чтения. Авторизуйте пути вывода, перезапись, изменения базы данных, установку расширений и внешний доступ до выполнения. DuckLocal не устанавливает расширения автоматически и не повторяет операции. Явные INSTALL/LOAD в SQL остаются возможными при наличии разрешения; установленные расширения могут автозагружаться. Неудачная команда могла уже выполнить побочные эффекты (например, до сбоя вывода); проверьте место назначения, прежде чем повторять попытку.

Вывод Markdown ​

--format md — это отображение, а не второй контракт: значения те же, что в JSON, записанные так, как их показывает таблица результатов.

ЗначениеОтображается как
NULLNULL
целое, decimal, floatровно те цифры, которые несёт значение — DECIMAL(38,10) сохраняет свой масштаб, NaN/inf/-inf пишутся словами
DATEYYYY-MM-DD
TIMESTAMPYYYY-MM-DD HH:MM:SS[.fffffffff], причём дробная часть только если она есть у значения, и с таким числом цифр, сколько у неё есть. Часовой пояс не добавляется; --format json сохраняет исходный счётчик
TIMEHH:MM:SS[.ffffff]
INTERVALкак его записывает DuckDB: 1 month 2 days 00:00:00.000003
BLOB, GEOMETRY0x00ff, сокращается через …, когда длинно
LIST, STRUCT, MAP[1, 2], {x: 1}, сокращается через … после 120 символов

| в ячейке экранируется, а перевод строки становится <br>, поэтому значение не может разорвать таблицу, в которой находится. После результата без строк идёт _0 rows._, а после результата, урезанного --limit или бюджетом ячеек, — _Truncated at 2 of 5000 rows, so this is not the whole answer._ (of at least … после подсчёта 100 000 строк) — предварительный просмотр не должен читаться как полный ответ. Ошибки не меняются: JSON в stderr, пустой stdout.

Вывод HTML ​

bash
ducklocal query --sql "SELECT * FROM 'sales.csv'" --format html > sales.html

--format html записывает те же значения, что и --format md, в виде одной веб-страницы:

  • Число строк и столбцов, затраченное время и SQL, давший результат, в свёрнутом виде.
  • Имена столбцов с их типами. Числа выровнены по правому краю, NULL помечены.
  • Щёлкните заголовок, чтобы отсортировать; NULL остаются в конце. Введите текст в поле фильтра, чтобы оставить только подходящие строки.
  • Если результат обрезан --limit или бюджетом ячеек, страница сообщает об этом, как и Markdown.

Стили и скрипт встроены, и страница ничего не загружает, поэтому она открывается с диска и публикуется как есть, например на GitHub Pages. Каждая ячейка экранируется для HTML.

Карта того, что можно запрашивать ​

ducklocal schema отвечает на вопрос «что здесь есть и какие у этого столбцы?» одним вызовом, тогда как DESCRIBE отвечает на него по одному отношению за раз. Это первое, что должен запустить агент.

bash
ducklocal schema ./data/                          # files, folders, globs
ducklocal schema --database warehouse.duckdb      # tables and views
ducklocal schema warehouse.duckdb --table orders  # one relation, whole
ducklocal schema ./logs/ --full                   # everything, however large

PATH раскрываются так же, как при перетаскивании в окно: файлы данных папки рекурсивно (скрытые пропускаются, не более 256), совпадения glob и файл базы данных так, как если бы он был указан через --database. Возвращается один объект JSON:

json
{"detail":"full","relations":[{"name":"data/orders.csv","kind":"file","from":"'data/orders.csv'","rows":null,"column_count":2,"path":"data/orders.csv","columns":[{"name":"channel","type":"VARCHAR"},{"name":"amount","type":"BIGINT"}]}],"without_columns":0}
ПолеЗначение
nameПуть файла в том виде, в каком он задан (относительно рабочего каталога, если он внутри него), или имя таблицы в том виде, в каком до неё доходит SQL на этом соединении: без схемы в схеме по умолчанию, schema.table в остальных случаях
kindfile, glob, table, view или workbook
fromSQL, который её читает, готовый идти после FROM: путь в кавычках или идентификатор в кавычках, где это нужно
rowsОценка каталога для таблицы, точная для Parquet (из его footer), null там, где для точности нужно сканирование — CSV, JSON, представления
column_count, columnsСтолбцы в том виде, в каком их описывает DuckDB
filesДля glob: сколько файлов он сопоставляет

Glob, все совпадения которого одного формата, — одно отношение, читаемое так же, как его читает source в .dash (ducklocal schema 'logs/*.csv'); --stats профилирует его как одно. Glob по смешанным форматам и папка перечисляют свои файлы по одному.

Небольшой каталог возвращается целиком ("detail": "full"). После 12 отношений или 400 столбцов вместо него возвращается сводка ("detail": "summary"). 5 отношений с наибольшим числом строк сохраняют свои столбцы; остальные перечисляют имя, тип, строки и число столбцов, а without_columns их считает. Чтобы получить больше, hint называет два способа: --table NAME для одного отношения (сопоставление по его имени, простому имени таблицы или имени файла) и --full для всех. Книга перечисляется со своими sheets и без столбцов, поскольку у неё нет табличной функции; --stats читает её первый лист. PATH, которого не существует, или --table, который ничего не называет, — код выхода 2.

Текст в gzip, такой как .json.gz и .csv.gz, здесь считается файлом данных — как и для блоков source и для окна. Файл, записи которого лежат в одном списке — скажем, {"Records": [...]} в CloudTrail, — возвращается с hint: SQL, который читает эти записи как строки, поскольку иначе одна строка и один столбец описывают только обёртку.

Изучение и преобразование файлов ​

После того как вы убедились, что файл действительно существует:

bash
ducklocal query --sql "DESCRIBE SELECT * FROM 'sales.csv'"
ducklocal query --sql "SELECT * FROM 'sales.csv'" --limit 20
ducklocal query --sql "SELECT sum(amount) AS total FROM 'sales.csv'"
# Only after authorizing this output path:
ducklocal query --sql "COPY (SELECT * FROM 'sales.csv') TO 'sales.parquet' (FORMAT PARQUET)"
ducklocal query --sql "SELECT count(*), sum(amount) FROM 'sales.parquet'"
ducklocal query --sql "DESCRIBE SELECT * FROM 'events.json'"

Не гадайте, что amount существует: сначала выполните ducklocal schema или DESCRIBE. Вычисляйте полные агрегаты в SQL, а не суммируйте усечённый предварительный просмотр. Вызовы CLI не разделяют зарегистрированные представления GUI или таблицы в памяти друг друга. Сохраняйте явно, когда это нужно:

bash
# These are separate statements and separate invocations, with explicit write permission.
ducklocal query --database warehouse.duckdb --read-write --sql "CREATE TABLE sales AS SELECT * FROM 'sales.csv'"
ducklocal query --database warehouse.duckdb --sql "SELECT count(*) FROM sales"

Конфликт блокировки базы данных — ошибка. Закройте другого писателя (включая GUI) или используйте разрешённую копию; никогда не удаляйте файлы блокировки и не создавайте молча другую базу данных.

JSONL и вложенный JSON ​

read_ndjson_objects — читатель для JSON с разделителями-переводами строк (один объект на строку, .jsonl/.ndjson); read_json/read_json_auto читают документы JSON (массив или один объект). Для файла JSONL указывайте читателя явно, а не полагайтесь на автоопределение. json_extract_string(col, '$.a.b[0].c') проходит по вложенному пути — ключам объектов и индексам массивов — и возвращает VARCHAR:

bash
ducklocal query --sql "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"

Используйте json_extract вместо этого, когда лист не является строкой и вы хотите получить его как JSON.

Статистика столбцов ​

ducklocal schema --stats отвечает на вопросы, которые определяют график, масштаб и формат чисел, до того, как на них что-либо построят. DESCRIBE говорит, что столбец имеет тип DOUBLE; его статистика говорит, что он использует два знака после запятой, что его наибольшее значение в тысячу раз больше медианы и что в его датах пропущено одиннадцать дней в середине.

bash
ducklocal schema sales.csv --stats
ducklocal schema ./exports/ --table orders.parquet --stats
ducklocal schema --database warehouse.duckdb --table "my orders" --stats

--stats профилирует одно отношение: то единственное, которое названо в аргументах, или то, которое выбрал --table, — два или больше без --table дают код выхода 2 с подсказкой об этом. Его нельзя сочетать с --full. ducklocal profile TARGET [--database PATH] из более ранних выпусков выдаёт тот же отчёт и по-прежнему работает.

Отношение — это файл данных (csv, tsv, txt, parquet, json, ndjson, jsonl) либо книга (xlsx, xls, xlsb, ods; её первый лист импортируется как временная таблица TEMP и профилируется), либо, с --database, имя таблицы или представления. Имя с точкой читается как schema.table, и каждая часть заключается в кавычки, поэтому имя с пробелом или заглавной буквой работает как написано. Отношение, которое ничего не называет, — ошибка аргументов (код выхода 2), а не SQL.

Возвращается один объект JSON: target, relation (SQL, по которому выполнялась статистика), row_count, elapsed_ms и columns в собственном порядке отношения. По каждому столбцу:

ПолеЗначение
name, typeкак их сообщает DESCRIBE
nullsстроки, где столбец равен NULL
distinctточное значение, а не оценка
uniqueприсутствует и равно true, когда distinct равно row_count
min, maxкак текст, поэтому DECIMAL сохраняет свои цифры
decimalsцифры после точки, которые столбец фактически использует, а не его объявленный масштаб
medianзначение, которое есть в столбце, а не интерполяция между двумя из них
max_over_medianво сколько раз наибольшее значение больше медианы — число, которое решает, использовать линейную ось или логарифмическую
covered_days, span_days, missing_daysдни, которые называет столбец, дни между его концами и разница: 0 — непрерывный ряд, любое другое значение — дыры, по которым линия провела бы черту

decimals, median и max_over_median появляются у числовых столбцов; поля дней — у дат и меток времени. Столбцы LIST, STRUCT, MAP и UNION сообщают только nulls — min и max для них не определены.

Текстовый столбец, в котором лежат числа и одно короткое слово, например NA из R, также сообщает null_marker и null_marker_rows. Тогда отчёт добавляет hint с вызовом read_csv, который читает столбец как числа.

Статистика точна и читает всё отношение, поэтому стоит полного сканирования. --limit не применяется: профиль выборки — не профиль.

Показ работы в работающем окне ​

ducklocal open передаёт что-либо окну DuckLocal, которое уже работает, — запуская его, если ни одного нет, — и выводит его на передний план. Так агент показывает свою работу человеку, который может продолжить с этого места:

bash
ducklocal open --title "Revenue by channel" --run --sql "SELECT channel, sum(amount) AS total FROM 'orders.csv' GROUP BY 1"
ducklocal open sales.dash                    # a dashboard tab
ducklocal open ./data/ --sql-file analysis.sql
echo "SELECT 42" | ducklocal open --sql-file - --no-launch
  • PATH открываются так же, как при перетаскивании в окно: файл .dash — как вкладка, файл базы данных DuckDB — как база данных окна, файлы данных, папки и glob — как присоединённые представления. Относительные PATH разрешаются относительно каталога команды. Запрос, пришедший пока окно ещё запускается, ждёт, пока завершится его стартовое открытие.
  • --sql или --sql-file (- читает stdin) открывает новую вкладку запроса с заголовком --title. --run выполняет его, как только присоединятся PATH.
  • --no-launch завершается с kind not_running вместо запуска окна — для машины, где незапрошенное появление окна было бы нежелательным.

Успех печатает {"delivered": true, "launched": BOOL}: доставку, а не результат. То, что открывается, работает в собственной сессии окна — с его соединением, присоединёнными представлениями, историей, — и любая ошибка показывается там, а не в stdout. Код 2 для аргументов; 1 с kind not_running (окно недоступно), refused (окно отклонило запрос) или launch.

Окно слушает порт loopback. Оно записывает порт и случайный токен в файл, который может прочитать только ваша учётная запись (см. Настройки и данные приложения); другой пользователь машины или веб-страница, нацеленная на localhost, до него не дотянутся.

Чтение того, что показывает окно ​

ducklocal open --state идёт в обратную сторону: ничего не открывает, никогда не запускает окно и печатает то, что показывает работающее окно, — чтобы агент мог продолжить с места, где остановился человек, вместо того чтобы просить его вставить свой запрос.

bash
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active
json
{"database":":memory:","attached":[{"path":"/Users/me/data/orders.csv","name":"orders","rows":224}],"active_tab":1,"tabs":[{"kind":"query","title":"Query 1","active":false,"sql":"SELECT …","result":{"status":"rows","columns":[…],"row_count":5,"truncated":false,"preview":[["Web","132771.24"],…],"sql":"SELECT …","elapsed_ms":4}},{"kind":"dashboard","title":"sales","active":true,"path":"/Users/me/data/sales.dash","unsaved":false,"dashboard":{"running":false,"error":null,"stale":null,"plots":[…],"filters":[{"name":"channel","plot":"revenue_by_channel","column":"channel","picked":true,"value":"Web"}]}}]}
  • database — открытый файл базы данных или ":memory:"; attached перечисляет файлы, которые окно зарегистрировало как представления, с именем представления name. Запрос CLI не может читать эти представления — используйте path.
  • Вкладка query имеет sql — текст редактора, выполнялся он или нет, — и result: status равен empty, running, rows, affected, failed, explain или profile. Для строк: columns, row_count, truncated, preview (первые 20 строк в том виде, в каком их показывает таблица, в виде строк), elapsed_ms и sql, который их произвёл; для affected — count и elapsed_ms; для ошибки — error.
  • После того как человек выбрал столбцы на вкладке «График», у результата есть также chart: type, x, y, split и dash — блоки query и plot, которые рисуют тот же график в дашборде.
  • explain — то, что показывает Explain: plan, вывод EXPLAIN DuckDB в виде массива текстовых строк, и elapsed_ms.
  • profile — то, что показывает Profile (см. Редактор SQL): plan, дерево операторов, измеренное EXPLAIN ANALYZE, в виде массива корней, каждый {operator, seconds, rows, estimated, children} — seconds это собственное время оператора без его дочерних, rows — что он произвёл, estimated — догадка оптимизатора для rows (null там, где план её не указывает), children — та же структура снова. operator_seconds — сумма собственного времени всех операторов, которую складывают доли, а не время по часам; elapsed_ms — весь прогон.
  • Вкладка dashboard имеет path, unsaved и dashboard: путь comments_file, plots (имя, тип, заголовок, запрос, строки, open_comments и failure, когда график не может отрисоваться) и filters с тем, что каждый выбрал: picked, value (первое значение), values (все выбранные значения по порядку) и multiple. value: null при picked: true означает, что выбрано значение NULL.

Используйте --state sales.dash, чтобы оставить только вкладки, показывающие этот дашборд, или --state --active — только активную вкладку. Путь, который не открыт, даёт код выхода 1, kind not_open, с открытыми дашбордами в подсказке. active_tab — индекс активной вкладки в возвращённом tabs или null, если её среди них нет; database и attached по-прежнему включаются.

--state принимает либо один PATH .dash, либо --active, но не оба. --no-launch принимается и ничего не меняет. Другие параметры, включая --sql и --run, недопустимы (код 2). Код 1 с kind not_running, когда окно не запущено, и timeout, когда оно не отвечает в течение 5 секунд.

Проверка спецификации дашборда ​

Сам формат — блоки, атрибуты, типы графиков, правила SQL и типичные сообщения — описан в разделе Дашборды (.dash); в этом разделе речь о команде.

Файл .dash объявляет дашборд так, как Terraform объявляет инфраструктуру — запросы и графики как блоки, ссылки между ними, — а не программирует его. Его легко писать и сравнивать человеку или агенту.

hcl
query "latency" {
  sql = <<SQL
    SELECT timestamp, service, avg(latency) AS latency
    FROM logs
    GROUP BY timestamp, service
  SQL
}

plot "latency" {
  type   = "line"
  query  = query.latency
  x      = timestamp
  y      = latency
  series = service
}
bash
ducklocal check dashboard.dash
ducklocal check dashboard.dash --database warehouse.duckdb
ducklocal check dashboard.dash --summary

Блок source называет файлы данных относительно файла .dash, которые должны читать запросы, а блок view хранит SQL, общий для нескольких запросов. Блок query содержит один атрибут sql — одну инструкцию только для чтения, в виде heredoc или строки. Принимаются SELECT, WITH, FROM-первым, VALUES, SHOW, DESCRIBE, SUMMARIZE и PIVOT; всё, что могло бы писать, — DDL, DML, COPY, ATTACH, INSTALL — становится диагностикой, и GUI отказывается это выполнять, потому что запросы дашборда выполняются при каждом открытии файла. Блок plot содержит type (один из line, bar, stacked_bar, area, scatter, pie, heatmap, histogram, map, timeline, table, card, text), query (ссылку вида query.latency на блок запроса в том же файле), его столбцы и необязательные title и width. Блок filter делает столбчатую диаграмму или таблицу кликабельной — одно значение или несколько при multiple = true для столбчатой диаграммы, — и запрос читает выбор как $name. # и // комментируют до конца строки. В разделе Дашборды (.dash) есть каждый атрибут.

График text — исключение: он содержит title, text или и то и другое и не принимает query. Карточки могут также использовать note и tone; см. Карточки и текстовые панели.

Сначала идут статические проверки: SQL каждого запроса проходит через настоящий парсер DuckDB на одноразовом соединении — так же, как query проверяет перед выполнением, — и каждый $name сверяется с блоками фильтров: SQL разбирается и выполняется с каждым $name, равным TRUE, — именно так дашборд работает, пока ничего не выбрано.

Затем выполняется каждый запрос — точно так, как его выполнило бы открытие дашборда: только для чтения, со своими источниками, через тот же путь кода и с тем же бюджетом строк, — и столбцы каждого графика сверяются со столбцами, которые запрос действительно возвращает: y, не являющийся числовым, — ошибка для любого типа графика, как и нечисловые координаты или size карты, и column фильтра, который запрос его графика не возвращает.

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

Каждый запрос, читающий фильтр, также связывается с выбранным значением, но без выполнения этого варианта. Это ловит столбец фильтра, отсутствующий в потребляющем запросе, даже когда начальная версия с $name = TRUE работает. Фильтр также должен ссылаться на столбец, который возвращает его собственный график.

Выполнение, а не только планирование, важно: некоторые сбои — например, приведение типа, которое сборка не может выполнить, или значение, которое не преобразуется, — появляются только после чтения строк, и проверка, которая их пропустит, передаст дашборд, который не сможет отрисоваться. Запросы выполняются полностью, поэтому проверка на большой базе данных занимает столько же времени, сколько открытие дашборда.

Успех — это один объект JSON, перечисляющий источники файла (с каждым resolved путём), представления, запросы (с их результирующими столбцами и rows — сколько вернул каждый при пустом выборе, плюс truncated: true, когда его урезал бюджет строк дашборда), фильтры (с queries, которые читают каждый), графики, unresolved и empty — запросы, которые выполнились и не вернули строк. Пустой запрос проходит все остальные проверки, но обычно это регулярное выражение, фильтр или соединение, которое ничего не нашло, поэтому посмотрите на каждый. С --summary успех — это одна компактная строка JSON:

json
{"file":"sales.dash","ok":true,"sources":1,"views":0,"queries":3,"filters":1,"plots":6,"unresolved":[],"empty":[]}

Пять полей блоков — это счётчики; unresolved перечисляет запросы, которые не удалось проверить, а empty — те, что не вернули строк.

Ошибочный блок пропускается, а валидные блоки продолжают проходить проверку. Ошибки спецификации и сбои запросов собираются в одном прогоне, по одному file:line: message на каждую. Если есть хоть одна диагностика спецификации, код выхода 2 с kind spec; если падает только выполнение SQL или связывание, код выхода 1 с kind sql. Сбои базы данных и ввода-вывода также дают код 1. --summary не скрывает диагностику.

Тот же файл открывается как вкладка дашборда в GUI — ducklocal dashboard.dash, ducklocal open dashboard.dash или перетаскиванием в окно — с графиками на сетке из 12 столбцов, а график, который не может отрисоваться, показывает причину прямо на месте. См. Дашборды (.dash).

Метрики из семантической модели ​

bash
ducklocal metrics                       # ./model.ossie.yaml
ducklocal metrics compile --metric error_count,event_count --by events.ip
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data

ducklocal metrics читает модель Apache Ossie, model.ossie.yaml, и перечисляет её метрики и поля. compile печатает единственный SELECT DuckDB, отвечающий на запрос, и не читает данные; query выполняет его так же, как ducklocal query, и добавляет объект semantic с SQL и sha256 модели. Запрос, на который модель не может ответить точно, отклоняется с кодом выхода 2 и kind, например metric_fanout. Формат модели, все параметры и все отказы описаны в разделе Семантические метрики.

Проверка комментариев к дашборду ​

Люди проверяют дашборд, комментируя его графики в окне — наведите курсор на график, нажмите облачко с репликой (см. Проверка с комментариями). ducklocal comments — сторона агента: он читает ветки и отвечает на них без окна.

bash
ducklocal comments sales.dash [--all]
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" [--resolve]
ducklocal comments sales.dash --resolve c1
ducklocal comments sales.dash --reopen c1
ducklocal comments sales.dash --add revenue_by_channel --text "Is this net of refunds?"
  • Без действия печатает открытые ветки: {file, comments_file, open, threads}. --all включает решённые.
  • Каждая ветка имеет id, plot и то, что нужно агенту, чтобы найти её в спецификации: plot_title, plot_query и plot_lines — первую и последнюю строку блока plot (null, когда спецификация не разбирается). plot_missing равно true, когда графика с таким именем больше нет. Затем resolved и comments, каждый с author (user или agent), у комментария агента — его name (имя, которое показывает presence), text и at (RFC 3339, местное время).
  • --reply ID --text TEXT добавляет ответ агента. Ответ в решённую ветку открывает её заново, если только не указан также --resolve.
  • --resolve ID и --reopen ID меняют состояние ветки; --add PLOT --text TEXT начинает ветку, подписанную агентом.
  • Номер ветки работает как её ID: --reply 1 означает c1. --add отказывается от графика, которого нет в спецификации (код 2), а подсказка перечисляет её графики.
  • Действие печатает {thread} в изменённом виде.

Ветки хранятся рядом со спецификацией, в FILE.comments.json. Работающее окно замечает изменение в течение секунды и показывает его на графике. Неизвестный ID ветки даёт код 2 с подсказкой перечислить ветки; отсутствующий файл спецификации — код 1.

Проверка от начала до конца: прочитайте открытые ветки, измените спецификацию, выполните ducklocal check, затем ответьте в каждой ветке тем, что изменилось, и выполните --resolve. Используйте --reply без --resolve, чтобы что-то переспросить у человека.

Показ активности агента ​

check и comments автоматически сообщают работающему окну, над каким дашбордом работает агент. presence может объявить правку до того, как она произойдёт:

bash
ducklocal presence sales.dash --doing editing --plot revenue_by_channel,daily_revenue
ducklocal presence sales.dash --doing reading --agent "Analyst"
ducklocal presence sales.dash --doing idle
  • --doing принимает reading, editing или idle (done — псевдоним для idle).
  • --plot принимает имена графиков через запятую. При editing новые имена разрешены и появляются как заполнители. При reading или idle неизвестное имя даёт код 2.
  • Показываемое имя берётся из --agent, затем DUCKLOCAL_AGENT, затем из обнаруженного окружения агента (Claude, Codex, Cursor или Gemini), с откатом к Agent.
  • Вывод — {delivered}. Без работающего окна выдаётся {"delivered":false} без ошибки и без запуска окна.

Имя остаётся в углу дашборда, пока команды поддерживают сеанс активным. Нажмите на него, чтобы увидеть журнал активности. Тридцать секунд тишины или --doing idle завершают сеанс; изменённые и добавленные графики остаются помеченными до просмотра, а уведомления об удалённых графиках — до закрытия. См. Как агент работает.

Редактирование спецификации дашборда с помощью LSP ​

ducklocal lsp — сервер Language Server Protocol для файлов .dash, работающий через stdio, который запускают редакторы. Он даёт любому редактору с поддержкой LSP то же, что есть у собственного редактора спецификаций в GUI:

  • Диагностика: та, которую сообщает check, публикуется при каждом открытии и изменении (полная синхронизация документа, все с уровнем Error — это ошибки, а не стиль).
  • Автодополнение: типы блоков, имена атрибутов, типы графиков и имена после query. и plot., каждое с текстовой правкой, которая заменяет набираемое слово.
  • Наведение: документация по блокам, атрибутам и ссылкам.
  • Переход к определению: от ссылки query.name или plot.name к имени её блока.

С --database PATH SQL каждого запроса дополнительно проверяется настоящим парсером DuckDB, как это делает check --database.

Направьте общую поддержку LSP вашего редактора на ducklocal lsp для файлов *.dash — команда не принимает аргументов документа; редактор общается с ней через stdio. В Neovim (0.10+):

lua
vim.api.nvim_create_autocmd("FileType", {
  pattern = "dash",
  callback = function(event)
    vim.lsp.start({
      name = "ducklocal",
      cmd = { "ducklocal", "lsp" },
      root_dir = vim.fs.dirname(vim.api.nvim_buf_get_name(event.buf)),
    })
  end,
})

В VS Code любое расширение с поддержкой LSP делает то же с командой ducklocal, аргументами ["lsp"] и селектором документов dash. Коды выхода: 0 после чистых shutdown/exit, 1 когда клиент уходит без них, 2 при плохой командной строке или неудачном рукопожатии протокола.

Контракт JSON ​

Успешные запросы записывают в stdout ровно один объект JSON, за которым идёт перевод строки:

json
{"columns":[{"name":"n","type":"Int32"}],"rows":[[1]],"row_count":1,"truncated":false,"total_rows":1,"total_rows_exact":true,"elapsed_ms":1}

columns и каждая строка сохраняют порядок столбцов и повторяющиеся имена столбцов. type — это отладочное представление Arrow, а не исходное имя типа SQL в DuckDB (например, HUGEINT и DECIMAL могут использовать один и тот же носитель Arrow). row_count считает возвращённые строки. total_rows считает произведённые строки, включая те, что посчитаны после предела вывода; total_rows_exact: false означает, что подсчёт остановился, пройдя до 100 000 дополнительных строк, поэтому этот итог — нижняя граница. Ни один из счётчиков не является счётчиком затронутых строк. elapsed_ms измеряет подготовку, выполнение и кодирование строк, но не загрузку файлов и установку соединения. Результаты с нулём строк сохраняют метаданные. DDL/DML показывают фактический результат DuckDB, включая столбцы Count: INSERT/COPY обычно возвращают [[N]]; CREATE TABLE обычно не возвращает строк. Они не классифицируются по первому ключевому слову SQL.

Кодирование ячеек:

Значение SQLКодирование в JSON
NULLnull (никогда строка "NULL")
Boolean, конечное floatJSON boolean/number
Целое в пределах ±9 007 199 254 740 991JSON number
Большее целое, включая HUGEINT/UHUGEINT{"encoding":"integer","value":"9007199254740992"}
Decimal{"encoding":"decimal","value":"123.450"} с точным десятичным текстом
Текст, enumстрока JSON
Blob, geometry{"encoding":"hex","value":"00ff"}; байты в нижнем регистре, geometry использует WKB
Date{"encoding":"date","unit":"Day","value":"1","iso":"1970-01-02"}; дни с 1970-01-01
Timestamp{"encoding":"timestamp","unit":"Nanosecond","value":"123456789","iso":"1970-01-01T00:00:00.123456789"}; знаковый счётчик с начала эпохи Unix; единица может быть также Second/Millisecond/Microsecond
Time{"encoding":"time","unit":"Microsecond","value":"123456","iso":"00:00:00.123456"}; счётчик с полуночи
Interval{"encoding":"interval","months":1,"days":2,"nanos":"3000"}
NaN, положительная/отрицательная бесконечность{"encoding":"float","value":"NaN"} / "inf" / "-inf"
List, arrayмассив JSON, рекурсивно закодированный (включая вложенные null)
Struct{"encoding":"struct","fields":[["name",VALUE],...]}
Map{"encoding":"map","entries":[[KEY,VALUE],...]}; не объект JSON, поэтому ключи сохраняют свои типы
Union{"encoding":"union-value","value":VALUE}; только активное значение, тег члена не сохраняется

Временные value — точные счётчики, поэтому дробная точность не теряется; бесконечные сигнальные значения дат и меток времени остаются исходными счётчиками. Рядом iso — то же значение в тексте ISO 8601 для чтения, с таким числом цифр дроби, сколько вмещает единица. Метка времени из столбца с часовым поясом (метаданные Arrow) — это момент в UTC, и её iso заканчивается на Z. --format md также отображает даты и метки времени удобочитаемо. Поскольку закреплённая обёртка Arrow для DuckDB не умеет различать вложенные HUGEINT, UHUGEINT и DECIMAL(38,0), ненулевые вхождения дают явную ошибку вместо молчаливой смены знака или точности. Явно приводите такие поля к VARCHAR в SQL. Неизвестные неподдерживаемые типы тоже дают ошибку; не путайте ошибку с пустым результатом. Кодирование Union — представление активного значения, а не обратимое сохранение union.

Ошибки записывают один объект JSON в stderr, оставляя stdout пустым:

json
{"error":{"kind":"argument","message":"Unknown query option: --limt","hint":"Did you mean --limit?"}}

hint присутствует, когда следующий шаг известен, в терминах самого CLI: флаг, которым должен был быть опечатанный, --read-write для записи, отклонённой на базе данных только для чтения, ducklocal schema для несуществующей таблицы, TRY_CAST для значения, которое не преобразуется, разбиение скрипта, в котором больше одной инструкции, или AS для ключевого слова, использованного как простой псевдоним столбца (SELECT count(*) AS minutes или заключите его в кавычки). Агент должен действовать по ней, прежде чем переписывать SQL. Она отсутствует, когда к собственному сообщению DuckDB нечего добавить, например при синтаксической ошибке.

Коды выхода: 0 — успех, 2 — недопустимые аргументы или число инструкций, 1 — сбой SQL, базы данных, ввода-вывода или вывода. Виды ошибок: argument, sql, database, io, output, spec для check и not_running, not_open, refused, timeout или launch для open. Проверяйте код выхода перед разбором stdout и смотрите на truncated перед тем, как сообщать о полноте. Справка и версия — исключения в виде обычного текста. Сбои транспорта, например закрытый канал stdout, не могут гарантировать пустой или полный поток вывода.

Установка официального навыка ​

Навык учит агента привычкам, которые делают его ответы честными: изучать схему, смотреть ограниченную выборку, вычислять агрегаты в SQL, проверять truncated и отвечать по возвращённым значениям. Он охватывает изучение схемы, статистику столбцов, преобразования, запросы к базам данных, дашборды .dash и комментарии к ним, а также передачу работы в окно и чтение её обратно; он не даёт просмотра S3, команд для пространственных данных, памяти сеанса или сервера MCP.

Из приложения. Откройте Command line & AI… (кнопка с роботом в строке заголовка или меню DuckLocal):

  • Install command помещает ducklocal в ваш PATH, чтобы оболочка агента могла его запускать.
  • Add to Claude Code записывает навык в ~/.claude/skills/ducklocal, где Claude Code находит его в любом проекте. Записываются только два собственных файла навыка; всё остальное в этой папке сохраняется. Когда обновление DuckLocal приносит более новый навык, диалог предлагает Update skill.
  • Copy brief копирует короткое объяснение для любого другого агента — Codex, Cursor, окна чата, — называя команду и способ её использования.

Вручную. Навык находится в skills/ducklocal. Чтобы добавить его в один проект (пример для Claude Code):

bash
# Run from the DuckLocal checkout; replace the destination with your project.
mkdir -p /path/to/your-project/.claude/skills
cp -R skills/ducklocal /path/to/your-project/.claude/skills/

Сначала изучите существующее место назначения, а не перезаписывайте локальные изменения. Другие агенты могут использовать те же SKILL.md и references/cli.md в своём поддерживаемом каталоге навыков.

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