---
title: SQL для ИИ-агентов на локальных данных | DuckLocal CLI
description: Позвольте ИИ-агентам изучать схемы и запрашивать локальные файлы одним запросом DuckDB SQL с ограниченным JSON-выводом.
image: https://ducklocal.app/og-image.jpg?v=2
language: ru
---

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

**Сначала схема. Один запрос. Структурированный вывод.**

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

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

1. **Составьте карту схемы.** `ducklocal schema ./data/` возвращает отношения, готовые к запросу выражения `FROM`, столбцы и типы. Для больших каталогов возвращается сводка с подсказками для детализации.
2. **Предпросмотр в допустимых пределах.** Выполните один SQL-запрос с небольшим лимитом. Проверьте код возврата и поле `truncated` в JSON.
3. **Вычисляйте в SQL.** Выполняйте фильтры, соединения и агрегации в DuckDB, а не суммируйте частичный предпросмотр в контексте агента.

```bash
ducklocal schema ./data/
ducklocal schema sales.csv --stats
ducklocal query --sql "SELECT channel, sum(revenue) FROM 'sales.csv' GROUP BY channel"
```

Каждый вызов `query` создаёт отдельное подключение, проверяет, что передан ровно один SQL-запрос, и записывает машиночитаемый результат в stdout. Ошибки выводятся как JSON в stderr с ненулевым кодом возврата.

## Настройка в 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 загружает его и без подсказок следует порядку «сначала схема».

```text

# 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`](https://github.com/JetSquirrel/DuckLocal/tree/main/skills/ducklocal) в `.claude/skills/` этого проекта.

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

Нажмите **Install command**, затем **Copy brief** и вставьте инструкцию в `AGENTS.md` в корне проекта. Codex читает этот файл в начале сеанса. Инструкция в сокращённом виде:

```text
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` и продолжайте подтверждать всё, что записывает файлы.

```text

# Then ask the agent:
Compare monthly order counts in exports/orders-*.csv
for 2025 and 2026 with DuckLocal.
```

Точный текст инструкции берётся из установленного приложения; если `ducklocal` ещё нет в `PATH`, в нём будет полный путь к команде. [Установить и посмотреть навык →](https://ducklocal.app/docs/ru/cli#install-the-official-skill)

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

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

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

[Лимиты, бюджеты и формат вывода](https://ducklocal.app/docs/ru/cli#query-options)

```bash
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}
```

## Ограниченный и явный вывод

Лимит по умолчанию — 1000 строк при бюджете в 2 000 000 ячеек. DuckLocal читает одну лишнюю строку, чтобы определить, был ли результат обрезан.

Структура JSON включает:

- типизированные столбцы и строки
- `row_count`
- `truncated`
- `elapsed_ms`

Код возврата 2 означает неверные аргументы; код возврата 1 означает ошибку выполнения. `--format md` выводит тот же результат в виде таблицы Markdown для чтения человеком.

## Официальный навык для агентов

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

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

## Границы безопасности

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

Разрешайте пути вывода, перезапись, изменения базы данных, установку расширений и внешний доступ до выполнения.

## Ссылки

- [Скачать DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Полный справочник по CLI](https://ducklocal.app/docs/ru/cli)
- [Установить официальный навык](https://ducklocal.app/docs/ru/cli#install-the-official-skill)
- [Локальный анализ данных](https://ducklocal.app/ru/use-cases/local-data-analysis/)
- [Чему Claude Dashboards научили меня в DuckLocal](https://ducklocal.app/ru/blog/claude-dashboards-ducklocal/)
- [DuckDB GUI](https://ducklocal.app/ru/use-cases/duckdb-gui/)
- [Просмотр Parquet](https://ducklocal.app/ru/use-cases/parquet-viewer/)
- [Запросы к CSV с помощью SQL](https://ducklocal.app/ru/use-cases/query-csv-with-sql/)
- [SQL-дашборды](https://ducklocal.app/ru/use-cases/sql-dashboards/)
- [DuckLocal или DBeaver](https://ducklocal.app/ru/compare/ducklocal-vs-dbeaver/)

Source: https://ducklocal.app/ru/use-cases/ai-agent-sql/
