Позвольте ИИ-агентам запрашивать локальные данные с помощью SQL

Дайте Claude Code, Codex, Cursor и другим агентам для программирования рабочий процесс DuckDB без графического интерфейса для данных CSV, Parquet, JSON и DuckDB. Без автоматизации GUI, сервера баз данных и собственного API.

CLI по умолчанию выводит JSON и использует явные коды возврата для ошибок аргументов, SQL и ввода-вывода.

Сначала обнаружение, потом запрос

Официальный рабочий процесс не даёт агенту угадывать имена столбцов или принимать частичный предпросмотр за весь набор данных.

  1. Составьте карту схемы

    Выполните ducklocal schema ./data/, чтобы получить отношения, готовые к запросу выражения FROM, столбцы и типы. Для больших каталогов возвращается сводка с подсказками для детализации.

  2. Предпросмотр в допустимых пределах

    Используйте один SQL-запрос и небольшой --limit, чтобы посмотреть репрезентативные строки. Проверьте код возврата команды и поле truncated в JSON.

  3. Вычислите ответ в SQL

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

Настройка в Claude Code, Codex или Cursor

Любому агенту нужны две вещи: команда ducklocal в его PATH и инструкция по её использованию. И то и другое берётся из Command line & AI… в приложении (кнопка с роботом в заголовке окна или меню DuckLocal).

Claude Code: установите навык

Нажмите 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/ этого проекта.

Codex: вставьте инструкцию в AGENTS.md

Нажмите 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 в её каталог навыков.

Cursor: сохраните инструкцию как правило проекта

Нажмите 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.

Почему агенту нельзя складывать предпросмотр

Агент, который читает строки и суммирует их в своём контексте, отвечает по тому, что ему показали. При файле в 1,2 млн строк и стандартном лимите в 1000 строк он видит меньше 0,1 % данных. Итог, который он назовёт, может выглядеть правдоподобно и при этом ошибаться на порядки.

DuckLocal не скрывает этот разрыв, а показывает его. Предпросмотр сообщает "truncated": true, а total_rows — сколько строк в результате было на самом деле. Если подсчёт остановился раньше, total_rows_exact равно false, и это число — лишь нижняя граница. Навык велит агенту считать это выборкой и отдавать вычисления DuckDB, который читает каждую строку.

Лимиты, бюджеты и формат вывода

Terminal
$ 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}

Одна команда — один SQL-запрос

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

  • Типизированные столбцы и строки в стабильной структуре JSON
  • Явные row_count, truncated и elapsed_ms
  • Код 2 для неверных аргументов; код 1 для ошибок выполнения
  • Ошибки JSON в stderr, stdout при этом остаётся пустым
  • Вывод Markdown для отчётов, читаемых человеком

Обучите рабочему процессу, а не только команде

Навык DuckLocal с открытым исходным кодом учит агента изучать схему, просматривать ограниченную выборку, агрегировать в SQL, проверять усечение и отвечать по возвращённым значениям. Установите его для Claude Code из приложения или скопируйте ту же инструкцию в другой агент для программирования.

Установить и изучить навык

Читать: чему Claude Dashboards научили меня в DuckLocal →

Локальный CLI — не скрытый облачный сервис и не песочница

DuckLocal не загружает локальные файлы в сервис DuckLocal, но и не делает вид, что произвольный SQL безопасен. Режим базы данных только для чтения не является песочницей файловой системы или сети: такой SQL, как COPY, установка расширений или явный внешний доступ, может иметь побочные эффекты.

  • Разрешайте пути вывода, перезапись и изменения базы данных
  • Разрешайте установку расширений и внешний доступ
  • Проверяйте место назначения перед повторной попыткой неудачной записи
  • Используйте --read-write только для намеренного изменения базы данных
  • Проверяйте ducklocal --help, прежде чем полагаться на команду

Вопросы о SQL для ИИ-агентов

Как ИИ-агент запрашивает локальные данные с помощью DuckLocal?
Агент выполняет ducklocal schema, чтобы обнаружить отношения и столбцы, а затем ducklocal query с одним SQL-запросом. По умолчанию команда возвращает структурированный JSON, не открывая настольное окно и не запуская сервер.
Возвращает ли CLI полные данные по умолчанию?
Нет. Вывод запроса намеренно ограничен: лимит по умолчанию — 1000 строк, а также действует бюджет в 2 000 000 ячеек. Ответ JSON сообщает, был ли он усечён. Полные агрегаты следует вычислять внутри SQL.
Может ли DuckLocal выполнять SQL-скрипты для агента?
Каждый вызов ducklocal query принимает ровно один SQL-запрос. Скрипты из нескольких запросов отклоняются, а не выполняются частично, что упрощает проверку каждого вызова инструмента.
Работает ли DuckLocal с Codex и Cursor или только с Claude Code?
Им может пользоваться любой агент, умеющий запускать команды в терминале. Claude Code получает официальный навык одним кликом в приложении. Для Codex, Cursor и других агентов кнопка Copy brief в приложении создаёт инструкцию, которую нужно вставить в AGENTS.md или в правило проекта.
DuckLocal — это MCP-сервер или песочница безопасности?
Нет. DuckLocal предоставляет интерфейс командной строки и дополнительный навык для агентов, но не MCP-сервер и не песочницу безопасности. Возможная запись, установка расширений и внешний доступ по-прежнему требуют обычного разрешения.

Дайте агенту рабочий процесс SQL «сначала схема»

Установите DuckLocal, добавьте команду в PATH и начните с вопроса о том, что на самом деле содержится в данных.