ducklocal schema ./data/Обнаружение отношений
Перечислите файлы, таблицы, представления и их столбцы до написания SQL.
Дайте Claude Code, Codex, Cursor и другим агентам для программирования рабочий процесс DuckDB без графического интерфейса для данных CSV, Parquet, JSON и DuckDB. Без автоматизации GUI, сервера баз данных и собственного API.
CLI по умолчанию выводит JSON и использует явные коды возврата для ошибок аргументов, SQL и ввода-вывода.
Официальный рабочий процесс не даёт агенту угадывать имена столбцов или принимать частичный предпросмотр за весь набор данных.
Выполните ducklocal schema ./data/, чтобы получить отношения, готовые к запросу выражения FROM, столбцы и типы. Для больших каталогов возвращается сводка с подсказками для детализации.
Используйте один SQL-запрос и небольшой --limit, чтобы посмотреть репрезентативные строки. Проверьте код возврата команды и поле truncated в JSON.
Выполняйте фильтры, соединения и агрегации в DuckDB, а не суммируйте усечённый предпросмотр в контексте агента. Возвращайте только те данные, которые нужны для ответа.
Любому агенту нужны две вещи: команда ducklocal в его PATH и инструкция по её использованию. И то и другое берётся из Command line & AI… в приложении (кнопка с роботом в заголовке окна или меню DuckLocal).
Нажмите Install command, затем Add to Claude Code. Навык записывается в ~/.claude/skills/ducklocal, где Claude Code находит его в любом проекте. Когда запрос подходит под навык, Claude Code загружает его и без подсказок следует порядку «сначала схема».
# In any project, ask in plain language:
Which channel brought in the most revenue in data/sales.csv?
Use DuckLocal and show me the query.
Чтобы навык работал только в одном проекте, скопируйте skills/ducklocal в .claude/skills/ этого проекта.
Нажмите Install command, затем Copy brief и вставьте инструкцию в AGENTS.md в корне проекта. Codex читает этот файл в начале сеанса. Инструкция в сокращённом виде:
DuckLocal is installed on this machine. Its command, ducklocal, runs DuckDB SQL over local CSV, TSV, Parquet, JSON and Excel files and databases, and prints JSON. - Start with `ducklocal --help` for the options. - See what there is to query, with columns, before writing SQL: `ducklocal schema ./data/` (or `--database file.duckdb`). - Profile what you will chart or summarize: `ducklocal schema data.csv --stats`. - Compute totals in SQL, not from sample rows; check `truncated` in the output. - It opens data read-only by default. Answer from the values it returns, and say which query produced them.
Если ваша версия Codex поддерживает навыки, можно вместо этого скопировать те же SKILL.md и references/cli.md в её каталог навыков.
Нажмите Install command, затем Copy brief и сохраните инструкцию как правило проекта, например .cursor/rules/ducklocal.mdc. После этого агент Cursor знает команду, когда работает в этом проекте. Его инструменту терминала нужно разрешение запускать ducklocal: разрешите schema и query и продолжайте подтверждать всё, что записывает файлы.
# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.
Точный текст инструкции берётся из установленного приложения; если ducklocal ещё нет в PATH, в нём будет полный путь к команде. Установить и посмотреть навык →
Агент, который читает строки и суммирует их в своём контексте, отвечает по тому, что ему показали. При файле в 1,2 млн строк и стандартном лимите в 1000 строк он видит меньше 0,1 % данных. Итог, который он назовёт, может выглядеть правдоподобно и при этом ошибаться на порядки.
DuckLocal не скрывает этот разрыв, а показывает его. Предпросмотр сообщает "truncated": true, а total_rows — сколько строк в результате было на самом деле. Если подсчёт остановился раньше, total_rows_exact равно false, и это число — лишь нижняя граница. Навык велит агенту считать это выборкой и отдавать вычисления DuckDB, который читает каждую строку.
$ ducklocal query --sql \ "SELECT * FROM 'events.csv'" {..., "row_count":1000, "truncated":true, "total_rows":101000, "total_rows_exact":false} $ ducklocal query --sql \ "SELECT count(*) AS n, sum(amount) AS total FROM 'events.csv'" {..., "rows":[[1204381,8812094.5]], "truncated":false}
Каждый вызов создаёт отдельное подключение DuckDB, проверяет, что вход содержит ровно один запрос, и записывает машиночитаемый результат в stdout. Ошибки выводятся как JSON в stderr с ненулевым кодом возврата.
$ ducklocal query --sql \ "SELECT channel, round(sum(revenue), 2) AS revenue FROM 'sales.csv' GROUP BY channel ORDER BY revenue DESC" {"columns":[...], "rows":[["Mobile app",290549.76],...], "row_count":4, "truncated":false, "elapsed_ms":14}
ducklocal schema ./data/Перечислите файлы, таблицы, представления и их столбцы до написания SQL.
ducklocal schema sales.csv --statsПолучите точные NULL-значения, уникальные значения, диапазоны, медианы и покрытие по датам.
ducklocal query --sql "…"По умолчанию получите типизированный JSON или таблицу Markdown с --format md.
ducklocal open --title "…" --run --sql "…"Откройте запрос в настольном приложении, когда результат нужно проверить или исследовать дальше.
Лимит возврата по умолчанию — 1000 строк плюс дополнительный бюджет в 2 000 000 ячеек. DuckLocal читает одну лишнюю строку, чтобы определить, был ли ответ обрезан, и отражает это в поле truncated.
Запросы с GROUP BY, ORDER BY и агрегатами по-прежнему вычисляются по всему входному набору, прежде чем вернуть ограниченный результат.
row_count, truncated и elapsed_msНавык DuckLocal с открытым исходным кодом учит агента изучать схему, просматривать ограниченную выборку, агрегировать в SQL, проверять усечение и отвечать по возвращённым значениям. Установите его для Claude Code из приложения или скопируйте ту же инструкцию в другой агент для программирования.
DuckLocal не загружает локальные файлы в сервис DuckLocal, но и не делает вид, что произвольный SQL безопасен. Режим базы данных только для чтения не является песочницей файловой системы или сети: такой SQL, как COPY, установка расширений или явный внешний доступ, может иметь побочные эффекты.
--read-write только для намеренного изменения базы данныхducklocal --help, прежде чем полагаться на командуНужен визуальный рабочий процесс? Посмотрите локальный анализ данных в настольном приложении →
ducklocal schema, чтобы обнаружить отношения и столбцы, а затем ducklocal query с одним SQL-запросом. По умолчанию команда возвращает структурированный JSON, не открывая настольное окно и не запуская сервер.ducklocal query принимает ровно один SQL-запрос. Скрипты из нескольких запросов отклоняются, а не выполняются частично, что упрощает проверку каждого вызова инструмента.AGENTS.md или в правило проекта.Похожие страницы: DuckDB GUI · Просмотр Parquet · Запросы к CSV с помощью SQL · SQL-дашборды · DuckLocal или DBeaver
Установите DuckLocal, добавьте команду в PATH и начните с вопроса о том, что на самом деле содержится в данных.