Deixe agentes de IA consultarem dados locais com SQL

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. Sem automação de GUI, servidor de banco de dados ou API personalizada.

A CLI imprime JSON por padrão e usa códigos de saída explícitos para falhas de argumentos, SQL e E/S.

Descubra primeiro, consulte depois

O fluxo de trabalho oficial evita que um agente adivinhe nomes de colunas ou trate uma prévia parcial como o conjunto de dados inteiro.

  1. Mapeie o esquema

    Execute ducklocal schema ./data/ para obter 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

    Use uma única instrução SQL e um --limit pequeno para inspecionar linhas representativas. Verifique o status de saída do comando e o campo truncated do JSON.

  3. Calcule a resposta em SQL

    Execute filtros, joins e agregações no DuckDB em vez de somar uma prévia truncada no contexto do agente. Retorne apenas as evidências de que a resposta precisa.

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.

# 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 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:

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.

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

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

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}

Um comando, uma instrução SQL

Cada invocação cria uma conexão DuckDB dedicada, valida que a entrada contém exatamente uma instrução 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.

Leia o contrato da consulta

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

Uma interface pequena com contratos explícitos

ducklocal schema ./data/

Descobrir relações

Liste arquivos, tabelas, views e suas colunas antes de escrever SQL.

ducklocal schema sales.csv --stats

Perfilar uma relação

Obtenha nulos exatos, valores distintos, intervalos, medianas e cobertura de datas.

ducklocal query --sql "…"

Executar uma instrução

Receba JSON tipado por padrão, ou uma tabela Markdown com --format md.

ducklocal open --title "…" --run --sql "…"

Entregue o trabalho a uma pessoa

Abra uma consulta no app desktop quando o resultado precisar de revisão ou exploração adicional.

Uma saída que avisa o agente quando está incompleta

O limite de retorno padrão é 1.000 linhas, com um orçamento adicional de 2.000.000 de células. O DuckLocal lê uma linha extra para determinar se a resposta foi cortada e expõe isso como truncated.

Consultas como GROUP BY, ORDER BY e agregações ainda são calculadas sobre a entrada completa antes de retornar seu resultado limitado.

  • Colunas e linhas tipadas em um envelope JSON estável
  • row_count, truncated e elapsed_ms explícitos
  • Saída 2 para argumentos inválidos; saída 1 para falhas de execução
  • Erros JSON em stderr, deixando stdout vazio
  • Saída Markdown para relatórios legíveis por pessoas

Ensine o fluxo de trabalho, não apenas o comando

A skill de código aberto do DuckLocal ensina um agente a inspecionar o esquema, pré-visualizar uma amostra limitada, agregar em SQL, verificar truncamento e responder a partir dos valores retornados. Instale-a para o Claude Code a partir do app ou copie o mesmo resumo para outro agente de programação.

Instalar e inspecionar a skill

Leia: O que os Dashboards do Claude me ensinaram sobre o DuckLocal →

Uma CLI local — não um serviço de nuvem oculto nem um sandbox

O DuckLocal não envia arquivos locais para um serviço do DuckLocal, mas também não finge que SQL arbitrário é inofensivo. O modo de banco de dados somente leitura não é um sandbox de sistema de arquivos ou de rede: SQL como COPY, instalação de extensões ou acesso externo explícito podem ter efeitos colaterais.

  • Autorize caminhos de saída, sobrescritas e mutações no banco de dados
  • Autorize a instalação de extensões e o acesso externo
  • Inspecione um destino antes de tentar novamente uma gravação que falhou
  • Use --read-write apenas para uma alteração intencional no banco de dados
  • Verifique ducklocal --help antes de depender de um comando

Perguntas sobre SQL para agentes de IA

Como um agente de IA consulta dados locais com o DuckLocal?
O agente executa ducklocal schema para descobrir relações e colunas e depois ducklocal query com uma única instrução SQL. O comando retorna JSON estruturado por padrão, sem abrir a janela desktop nem iniciar um servidor.
A CLI retorna dados completos por padrão?
Não. A saída da consulta é deliberadamente limitada: o limite padrão de linhas é 1.000 e também se aplica um orçamento de 2.000.000 de células. A resposta JSON informa se houve truncamento. Agregações completas devem ser calculadas dentro do SQL.
O DuckLocal pode executar scripts SQL para um agente?
Cada invocação de ducklocal query aceita exatamente uma instrução SQL. Scripts com múltiplas instruções são rejeitados em vez de executados parcialmente, o que torna cada chamada de ferramenta mais fácil de inspecionar.
O DuckLocal funciona com Codex e Cursor, ou só com o Claude Code?
Qualquer agente que consiga executar um comando de terminal pode usá-lo. O Claude Code recebe a skill oficial com um clique no app. Para Codex, Cursor e outros agentes, o botão Copy brief do app gera instruções para colar no AGENTS.md ou em uma regra de projeto.
O DuckLocal é um servidor MCP ou um sandbox de segurança?
Não. O DuckLocal oferece uma interface de linha de comando e uma skill de agente opcional, não um servidor MCP nem um sandbox de segurança. Gravações em potencial, instalação de extensões e acesso externo ainda exigem autorização normal.

Dê ao seu agente um fluxo de trabalho SQL que começa pelo esquema

Instale o DuckLocal, coloque o comando no PATH e comece perguntando o que realmente há nos dados.