---
title: SQL para agentes de IA em dados locais | DuckLocal CLI
description: Deixe agentes de IA inspecionarem esquemas e consultarem arquivos locais com SQL DuckDB de uma única instrução e saída JSON limitada.
image: https://ducklocal.app/og-image.jpg?v=2
language: pt
---

# Deixe agentes de IA consultarem dados locais com SQL

**Esquema primeiro. Uma instrução. Saída estruturada.**

O DuckLocal dá ao Claude Code, Codex, Cursor e outros agentes de programação um fluxo de trabalho DuckDB headless para dados em CSV, Parquet, JSON e DuckDB. Ele não exige automação de GUI, servidor de banco de dados ou API personalizada.

## Descubra primeiro, consulte depois

1. **Mapeie o esquema.** `ducklocal schema ./data/` retorna relações, expressões `FROM` prontas para consulta, colunas e tipos. Catálogos grandes retornam um resumo com dicas para detalhar.
2. **Pré-visualize dentro dos limites.** Execute uma instrução SQL com um limite pequeno. Verifique o status de saída e o campo `truncated` do JSON.
3. **Calcule em SQL.** Faça filtros, joins e agregações no DuckDB em vez de somar uma prévia parcial no contexto do agente.

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

Cada invocação de `query` cria uma conexão dedicada, valida exatamente uma instrução SQL e grava um resultado legível por máquina em stdout. Os erros são JSON em stderr com um código de saída diferente de zero.

## Configure no Claude Code, no Codex ou no Cursor

Todo agente precisa de duas coisas: o comando `ducklocal` no `PATH` e instruções de como usá-lo. As duas vêm de **Command line & AI…** no app (o botão de robô na barra de título ou o menu DuckLocal).

### Claude Code: instale a skill

Clique em **Install command** e depois em **Add to Claude Code**. A skill é gravada em `~/.claude/skills/ducklocal`, onde o Claude Code a encontra em todos os projetos. Quando um pedido combina com ela, o Claude Code carrega a skill e segue o fluxo de “esquema primeiro” sem que você precise pedir.

```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.
```

Para usar a skill em um só projeto, copie [`skills/ducklocal`](https://github.com/JetSquirrel/DuckLocal/tree/main/skills/ducklocal) para o `.claude/skills/` desse projeto.

### Codex: cole as instruções no AGENTS.md

Clique em **Install command** e depois em **Copy brief**, e cole as instruções no `AGENTS.md` na raiz do seu projeto. O Codex lê esse arquivo no início de cada sessão. As instruções, resumidas:

```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.
```

Se a sua versão do Codex aceita skills, você também pode copiar os mesmos `SKILL.md` e `references/cli.md` para o diretório de skills dele.

### Cursor: salve as instruções como regra de projeto

Clique em **Install command** e depois em **Copy brief**, e salve as instruções como uma regra de projeto, por exemplo `.cursor/rules/ducklocal.mdc`. Assim o agente do Cursor conhece o comando sempre que trabalha nesse projeto. A ferramenta de terminal dele precisa de permissão para executar `ducklocal`: libere `schema` e `query`, e continue aprovando tudo que grave arquivos.

```text

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

O texto exato das instruções vem do app instalado e inclui o caminho completo do comando se `ducklocal` ainda não estiver no `PATH`. [Instale e inspecione a skill →](https://ducklocal.app/docs/pt/cli#install-the-official-skill)

## Por que o agente não deve somar a pré-visualização

Um agente que lê linhas e as soma no próprio contexto responde com base no que viu. Com um arquivo de 1,2 milhão de linhas e o limite padrão de 1.000 linhas, ele vê menos de 0,1% dos dados. O total que ele informa pode parecer plausível e ainda assim estar errado em várias ordens de grandeza.

O DuckLocal deixa essa lacuna visível em vez de silenciosa. Uma pré-visualização informa `"truncated": true`, e `total_rows` mostra quantas linhas o resultado realmente tinha. Quando a contagem para antes, `total_rows_exact` é `false` e o total é só um limite inferior. A skill diz ao agente para tratar isso como amostra e devolver a conta ao DuckDB, que lê todas as linhas.

[Limites, orçamentos e o formato de saída](https://ducklocal.app/docs/pt/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}
```

## Saída limitada e explícita

O limite padrão é 1.000 linhas, com um orçamento de 2.000.000 de células. O DuckLocal lê uma linha extra para determinar se o resultado foi cortado.

O envelope JSON inclui:

- colunas e linhas tipadas
- `row_count`
- `truncated`
- `elapsed_ms`

O código de saída 2 significa argumentos inválidos; o código de saída 1 significa falha na execução. `--format md` renderiza o mesmo resultado como uma tabela Markdown para uma pessoa ler.

## Skill de agente oficial

A skill de código aberto ensina um agente a inspecionar o esquema, pré-visualizar uma amostra limitada, agregar em SQL, verificar truncamento e responder a partir dos valores retornados. Ela pode ser instalada para o Claude Code a partir do app, ou usada como um resumo para outro agente.

Um agente pode entregar trabalho ao app desktop em execução com `ducklocal open` e depois ler as abas visíveis e as prévias de resultado com `ducklocal open --state`.

## Limite de segurança

O DuckLocal não envia arquivos locais para um serviço do DuckLocal, mas não é um sandbox de segurança. O modo de banco de dados somente leitura não impede que o SQL grave outros arquivos ou acesse a rede.

Autorize caminhos de saída, sobrescritas, mutações no banco de dados, instalação de extensões e acesso externo antes da execução.

## Links

- [Baixar o DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [Referência completa da CLI](https://ducklocal.app/docs/pt/cli)
- [Instalar a skill oficial](https://ducklocal.app/docs/pt/cli#install-the-official-skill)
- [Análise de dados locais](https://ducklocal.app/pt/use-cases/local-data-analysis/)
- [O que os Dashboards do Claude me ensinaram sobre o DuckLocal](https://ducklocal.app/pt/blog/claude-dashboards-ducklocal/)
- [GUI do DuckDB](https://ducklocal.app/pt/use-cases/duckdb-gui/)
- [Visualizador de Parquet](https://ducklocal.app/pt/use-cases/parquet-viewer/)
- [Consultar CSV com SQL](https://ducklocal.app/pt/use-cases/query-csv-with-sql/)
- [Painéis SQL](https://ducklocal.app/pt/use-cases/sql-dashboards/)
- [DuckLocal vs DBeaver](https://ducklocal.app/pt/compare/ducklocal-vs-dbeaver/)

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