DuckDB Query: consulte arquivos com limite antes de abrir o resultado

ANÁLISE EDITORIAL

A Skill oficial DuckDB Query orienta um agente a transformar uma pergunta ou um trecho SQL em uma consulta executada pelo DuckDB contra arquivos locais ou bancos já anexados. O valor não está em prometer uma análise automática. Está em escolher o modo correto, verificar o estado, limitar o acesso no uso ad hoc, estimar o tamanho da resposta e só então executar uma consulta que possa ser revisada.

Esse cuidado é útil quando CSV, Parquet, JSON ou uma base DuckDB precisam ser consultados sem importar tudo para outro sistema. Também é necessário porque uma consulta aparentemente simples pode ler um arquivo errado, retornar milhões de linhas, expor dados sensíveis ou carregar uma extensão. A Skill organiza a sequência, mas não conhece a finalidade dos dados nem autoriza acesso por conta própria.

O que esta Skill faz de verdade

O SKILL.md recebe SQL bruto ou uma pergunta em linguagem natural. Primeiro procura um arquivo de estado criado por outras Skills do mesmo pacote. Se houver uma sessão, tenta confirmar que os bancos anexados continuam acessíveis. Se não houver sessão, ou se a solicitação apontar diretamente para um arquivo, usa o modo ad hoc em memória.

No modo ad hoc, a orientação é relevante para segurança: limitar allowed_paths aos arquivos citados, desabilitar acesso externo, impedir segredos persistentes e bloquear novas mudanças de configuração antes da consulta. No modo de sessão, a base anexada é considerada escolhida pelo usuário. Isso amplia a responsabilidade do operador, pois o estado pode apontar para dados reais e não recebe o mesmo isolamento do exemplo ad hoc.

A Skill também pede uma estimativa antes de devolver resultados potencialmente enormes. Consultas já limitadas ou agregadas podem seguir. Uma consulta sem LIMIT sobre mais de um milhão de linhas deve gerar aviso e confirmação. O objetivo é controlar tempo, custo e exposição, não garantir desempenho.

Para quem serve

Ela serve a analistas, desenvolvedores, profissionais de dados e equipes operacionais que precisam inspecionar arquivos tabulares com SQL, explorar uma base DuckDB existente ou responder perguntas pontuais sem montar um pipeline completo. É especialmente útil quando a tarefa combina linguagem natural, schema desconhecido e necessidade de mostrar o SQL antes da execução.

Também pode ajudar revisores que querem um fluxo repetível para conferir colunas, contar linhas, sumarizar dados ou testar uma hipótese pequena. O resultado deve preservar a diferença entre o que veio do arquivo, o que foi calculado pela consulta e o que é interpretação do agente.

Não é uma ferramenta de governança automática, anonimização ou controle de acesso empresarial. A Skill não verifica a legitimidade da origem do arquivo, não classifica dados pessoais e não substitui políticas de retenção, autorização ou revisão humana.

Compatibilidade e pré-requisitos

A versão auditada pertence ao pacote oficial duckdb/duckdb-skills. Ela foi escrita para clientes que entendem arquivos SKILL.md e conseguem executar comandos de shell. O conteúdo menciona Claude Code em alguns comandos de delegação, mas o fluxo central pode ser lido por outros clientes compatíveis, desde que caminhos, ferramentas e permissões sejam adaptados.

• DuckDB CLI instalado e disponível no caminho de execução.
• Permissão de leitura somente para os arquivos ou bancos aprovados.
• Schema, origem e sensibilidade dos dados conhecidos pelo operador.
• Espaço e tempo compatíveis com a consulta pretendida.
• Revisão do SQL gerado antes de executar em dados importantes.
• Autorização separada para instalar extensões ou acessar rede.

A release estável consultada foi a DuckDB v1.5.5. O pacote de Skills declara versão 0.2.4. Esses números descrevem componentes diferentes e não significam que todo exemplo foi testado em cada cliente ou plataforma.

Instalação recomendada

O repositório oficial documenta a instalação do pacote com o ecossistema Skills:

npx skills add duckdb/duckdb-skills

O comando usa rede e executa um pacote por npx. Confirme origem, versão e destino antes de aceitar. Instale apenas em um projeto ou perfil de teste quando ainda não houver política para Skills de terceiros. O SKILL.md fixado no commit auditado pode ser lido antes da instalação.

O download local do Bastidores é documental e contém somente SKILL.md, LICENSE e ORIGEM.md. Ele não instala o DuckDB, não inclui o binário do DuckDB, extensão, dependência, script, banco, dado ou configuração de usuário.

Configuração antes do primeiro uso

Comece sem sessão persistente. Separe um arquivo de teste sem dados pessoais e informe o caminho absoluto aprovado. Peça ao agente para mostrar a consulta, o modo escolhido e a lista exata de caminhos antes de executar. Se a pergunta estiver em linguagem natural, confira se as colunas usadas existem e se filtros, agrupamentos e unidades correspondem ao pedido.

Defina um limite de resultado. Para exploração, cem linhas costumam bastar para inspeção visual, mas o valor precisa refletir a tarefa. Para totais, prefira agregações. A documentação oficial do SELECT mostra a ordem lógica das cláusulas e ajuda a revisar filtros, agrupamentos, ordenação e limites.

Se houver arquivo de estado, leia o conteúdo antes de usá-lo. Confirme cada ATTACH, o caminho, o modo de acesso e a base pretendida. Não reutilize estado recebido de outra pessoa ou projeto sem auditoria.

Primeiro uso seguro

Use um CSV descartável e uma consulta limitada. Um pedido adequado seria: “mostre o schema e conte quantas linhas existem, sem acessar rede e sem escrever arquivos”. O agente deve detectar o modo ad hoc, limitar o caminho e executar em :memory:.

duckdb :memory: -csv -c "SELECT count() AS total FROM 'dados-teste.csv';"

O exemplo é ilustrativo. Ajuste o caminho e não execute antes de revisar o arquivo. Em seguida, peça uma amostra explícita com LIMIT. Compare os nomes e tipos das colunas com a origem. A documentação de Friendly SQL explica construções como FROM primeiro, GROUP BY ALL, SUMMARIZE e seleção por nomes.

Se uma extensão for necessária, pare e revise. Instalação de extensão consulta uma origem e grava componentes locais. Ela não deve ser tratada como continuação automática de uma consulta somente leitura.

Como o fluxo deve funcionar

1. Identificar se existe estado de sessão e verificar os anexos.
2. Escolher modo de sessão ou ad hoc com justificativa curta.
3. Confirmar que o DuckDB CLI está instalado.
4. Obter schema quando a pergunta depender de nomes e tipos.
5. Gerar SQL e mostrá-lo ao operador antes da primeira execução importante.
6. Estimar o tamanho e pedir confirmação para resultado excessivo.
7. Restringir caminhos e acesso externo no modo ad hoc.
8. Executar, devolver saída limitada e separar dados de interpretação.

O registro da execução deve conter arquivos ou bancos consultados, SQL final, versão do DuckDB, modo, limite aplicado, avisos e erros. Não grave conteúdo sensível no relatório quando uma contagem, hash ou amostra anonimizada for suficiente.

Resultado esperado

Uma boa entrega inclui a consulta final, uma tabela pequena ou agregação verificável e uma interpretação breve que não extrapola os dados. Se a resposta foi truncada, isso precisa ficar explícito. Se o schema foi inferido, registre essa condição e valide tipos importantes antes de calcular.

Em diagnóstico, o resultado pode ser um erro reproduzível com caminho, etapa e sugestão de correção. A orientação oficial de solução de problemas recomenda isolar a consulta e testar no CLI quando a falha puder depender do cliente ou de extensões.

Não espere que a Skill prove qualidade dos dados, causalidade ou representatividade. Ela organiza consulta e apresentação. Decisões de negócio exigem validação da fonte, das regras e das limitações do conjunto.

Permissões, privacidade e riscos

A principal permissão é leitura de arquivos e bancos. Um caminho amplo pode expor mais dados do que a tarefa pede. No modo ad hoc, use apenas caminhos aprovados e mantenha acesso externo desabilitado. No modo de sessão, trate o arquivo de estado como configuração sensível.

Consultas SQL também podem escrever, criar ou substituir tabelas. A Skill inclui referências de modificação, mas a primeira execução deve ser estritamente de leitura. Bloqueie CREATE, INSERT, UPDATE, DELETE, COPY TO e comandos de instalação até haver autorização clara e backup.

Resultados grandes podem vazar dados em logs e consumir muitos tokens. A estimativa de tamanho é um gate operacional, não uma garantia. Dados pessoais, financeiros ou contratuais devem seguir a política aplicável e não devem ser enviados a serviços externos apenas por conveniência.

Erros comuns

O DuckDB não está instalado. Não baixe automaticamente. Confirme a plataforma, a fonte oficial e a versão aprovada antes da instalação.

O arquivo não foi encontrado. Não amplie a busca para todo o disco. Restrinja a procura ao projeto autorizado e peça um caminho exato.

A tabela não existe na sessão. Liste tabelas disponíveis e confira o estado. Não substitua silenciosamente por uma tabela de nome parecido.

A consulta retorna linhas demais. Adicione LIMIT, agregação ou filtro. Resultados completos devem ser exportados somente com destino, formato e autorização definidos.

Uma extensão está ausente. Pare antes de instalar. Revise origem, permissões, compatibilidade e necessidade real.

O tipo inferido está errado. Inspecione o schema, parâmetros de leitura e amostras representativas. Datas, separadores e nulos merecem validação explícita.

Versão, licença e origem verificadas

A curadoria consultou o repositório oficial em 01/09/2026. A API pública do GitHub registrava 539 estrelas. O projeto ficou abaixo do piso editorial de 1.000, mas foi aceito como exceção porque é mantido pela organização oficial DuckDB, possui documentação ativa, pacote versionado 0.2.4, release estável v1.5.5 do produto e licença verificável. Estrelas não provam segurança ou adequação.

A Skill foi fixada no commit 7feda8e01e22bc0886c86123f3884947e36d8c69. A versão 0.2.4 aparece no manifesto oficial fixado.

A licença é MIT e permite redistribuição com preservação do aviso. O ZIP local contém três arquivos textuais permitidos e nada executável. SHA-256: 63f3b33fde80d4a6e703828d234c90b63f3204b1f90f9c60ed0da66d3a688403.

Checklist antes de automatizar

• Fixe o commit da Skill, a versão do DuckDB e o cliente usado.
• Confirme a origem, o schema e a sensibilidade dos dados.
• Use somente os caminhos aprovados e bloqueie acesso externo no modo ad hoc.
• Mostre o SQL e limite o resultado antes da primeira execução.
• Comece com leitura e dados de teste sem credenciais.
• Separe instalação de extensão, escrita e exportação em autorizações próprias.
• Registre modo, consulta, limite, versão, avisos e erros.
• Revise a interpretação humana antes de tomar decisão.

Fontes primárias

• Repositório oficial DuckDB Skills.
• SKILL.md Query fixado no commit auditado.
• Release estável DuckDB v1.5.5.
• SELECT na documentação oficial.
• Friendly SQL na documentação oficial.
• Solução de problemas na documentação oficial.