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. Тот же диалог устанавливает навык для ИИ-агентов; см. Установка официального навыка. Если пропустить установку, вызывайте исполняемый файл там, где он лежит:
# 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
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, записанные так, как их показывает таблица результатов.
| Значение | Отображается как |
|---|---|
NULL | NULL |
| целое, decimal, float | ровно те цифры, которые несёт значение — DECIMAL(38,10) сохраняет свой масштаб, NaN/inf/-inf пишутся словами |
DATE | YYYY-MM-DD |
TIMESTAMP | YYYY-MM-DD HH:MM:SS[.fffffffff], причём дробная часть только если она есть у значения, и с таким числом цифр, сколько у неё есть. Часовой пояс не добавляется; --format json сохраняет исходный счётчик |
TIME | HH:MM:SS[.ffffff] |
INTERVAL | как его записывает DuckDB: 1 month 2 days 00:00:00.000003 |
BLOB, GEOMETRY | 0x00ff, сокращается через …, когда длинно |
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
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 отвечает на него по одному отношению за раз. Это первое, что должен запустить агент.
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 largePATH раскрываются так же, как при перетаскивании в окно: файлы данных папки рекурсивно (скрытые пропускаются, не более 256), совпадения glob и файл базы данных так, как если бы он был указан через --database. Возвращается один объект 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 в остальных случаях |
kind | file, glob, table, view или workbook |
from | SQL, который её читает, готовый идти после 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, который читает эти записи как строки, поскольку иначе одна строка и один столбец описывают только обёртку.
Изучение и преобразование файлов
После того как вы убедились, что файл действительно существует:
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 или таблицы в памяти друг друга. Сохраняйте явно, когда это нужно:
# 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:
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; его статистика говорит, что он использует два знака после запятой, что его наибольшее значение в тысячу раз больше медианы и что в его датах пропущено одиннадцать дней в середине.
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, которое уже работает, — запуская его, если ни одного нет, — и выводит его на передний план. Так агент показывает свою работу человеку, который может продолжить с этого места:
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завершается с kindnot_runningвместо запуска окна — для машины, где незапрошенное появление окна было бы нежелательным.
Успех печатает {"delivered": true, "launched": BOOL}: доставку, а не результат. То, что открывается, работает в собственной сессии окна — с его соединением, присоединёнными представлениями, историей, — и любая ошибка показывается там, а не в stdout. Код 2 для аргументов; 1 с kind not_running (окно недоступно), refused (окно отклонило запрос) или launch.
Окно слушает порт loopback. Оно записывает порт и случайный токен в файл, который может прочитать только ваша учётная запись (см. Настройки и данные приложения); другой пользователь машины или веб-страница, нацеленная на localhost, до него не дотянутся.
Чтение того, что показывает окно
ducklocal open --state идёт в обратную сторону: ничего не открывает, никогда не запускает окно и печатает то, что показывает работающее окно, — чтобы агент мог продолжить с места, где остановился человек, вместо того чтобы просить его вставить свой запрос.
ducklocal open --state
ducklocal open --state sales.dash
ducklocal open --state --active{"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, выводEXPLAINDuckDB в виде массива текстовых строк, и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 объявляет инфраструктуру — запросы и графики как блоки, ссылки между ними, — а не программирует его. Его легко писать и сравнивать человеку или агенту.
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
}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:
{"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).
Метрики из семантической модели
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 dataducklocal metrics читает модель Apache Ossie, model.ossie.yaml, и перечисляет её метрики и поля. compile печатает единственный SELECT DuckDB, отвечающий на запрос, и не читает данные; query выполняет его так же, как ducklocal query, и добавляет объект semantic с SQL и sha256 модели. Запрос, на который модель не может ответить точно, отклоняется с кодом выхода 2 и kind, например metric_fanout. Формат модели, все параметры и все отказы описаны в разделе Семантические метрики.
Проверка комментариев к дашборду
Люди проверяют дашборд, комментируя его графики в окне — наведите курсор на график, нажмите облачко с репликой (см. Проверка с комментариями). ducklocal comments — сторона агента: он читает ветки и отвечает на них без окна.
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 может объявить правку до того, как она произойдёт:
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+):
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, за которым идёт перевод строки:
{"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 |
|---|---|
| NULL | null (никогда строка "NULL") |
| Boolean, конечное float | JSON boolean/number |
| Целое в пределах ±9 007 199 254 740 991 | JSON 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 пустым:
{"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):
# 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 в своём поддерживаемом каталоге навыков.
