ducklocal schema ./data/Descobrir relações
Liste arquivos, tabelas, views e suas colunas antes de escrever 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.
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.
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.
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.
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.
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).
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.
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.
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.
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 →
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.
$ 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}
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.
$ 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/Liste arquivos, tabelas, views e suas colunas antes de escrever SQL.
ducklocal schema sales.csv --statsObtenha nulos exatos, valores distintos, intervalos, medianas e cobertura de datas.
ducklocal query --sql "…"Receba JSON tipado por padrão, ou uma tabela Markdown com --format md.
ducklocal open --title "…" --run --sql "…"Abra uma consulta no app desktop quando o resultado precisar de revisão ou exploração adicional.
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.
row_count, truncated e elapsed_ms explícitosA 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 →
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.
--read-write apenas para uma alteração intencional no banco de dadosducklocal --help antes de depender de um comandoPrecisa do fluxo visual? Veja a análise de dados locais no app desktop →
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.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.AGENTS.md ou em uma regra de projeto.Relacionados: GUI do DuckDB · Visualizador de Parquet · Consultar CSV com SQL · Painéis SQL · DuckLocal vs DBeaver
Instale o DuckLocal, coloque o comando no PATH e comece perguntando o que realmente há nos dados.