query

Visão geral da skill query

O que a skill query faz

A skill query ajuda você a executar consultas DuckDB tanto em um banco de dados de trabalho anexado quanto diretamente em arquivos que você informar. Ela foi feita para quem quer chegar do problema ao resultado o mais rápido possível: SQL ad hoc, perguntas de dados em linguagem natural ou análises simples baseadas em arquivos com DuckDB Friendly SQL.

Para quem ela é mais indicada

Use a skill query para análise de dados quando você já tiver os dados no DuckDB, em um arquivo de estado do projeto ou em um arquivo local como CSV/Parquet e quiser respostas imediatas sem montar um pipeline completo. Ela é especialmente útil para analistas, engenheiros e agentes de IA que precisam inspecionar dados com rapidez e de forma iterativa.

O que diferencia esta skill

O principal diferencial da query é a escolha de modo. Ela pode operar em modo de sessão quando já existe estado anterior do DuckDB, ou em modo ad hoc quando a entrada referencia arquivos ou quando não há estado disponível. Isso reduz adivinhação e torna a query skill útil tanto em fluxos persistentes quanto em usos pontuais.

Como usar a skill query

Instalação e uso básico

Instale a skill query com npx skills add duckdb/duckdb-skills --skill query. Depois, chame-a com SQL ou com uma pergunta, por exemplo: query "show daily revenue by country" ou query "select count(*) from 'events.csv'". O padrão de uso da query funciona melhor quando o pedido é específico o bastante para virar uma consulta clara.

Como a skill escolhe entre modo de sessão e modo ad hoc

A skill query primeiro verifica se existe um arquivo de estado DuckDB em .duckdb-skills/state.sql ou ~/.duckdb-skills/<project-id>/state.sql. Se encontrar um e os bancos anexados ainda funcionarem, ela usa o modo de sessão. Se você passar --file, referenciar caminhos de arquivo ou não houver estado aproveitável, ela muda para o modo ad hoc e consulta os arquivos diretamente, ou :memory: quando necessário. Esta é a parte mais importante do query guide, porque a sua entrada precisa corresponder ao modo que você realmente quer usar.

O que ler primeiro no repositório

Comece por SKILL.md, porque ele reúne o fluxo de execução, as regras de modo e o comportamento de fallback. Para decisões de instalação, isso normalmente já basta. Se você estiver adaptando a skill para o seu próprio fluxo de trabalho, também vale inspecionar os arquivos referenciados na árvore do repositório, especialmente qualquer coisa que defina tratamento de estado ou restrições de prompt. Neste repositório não há rules/, resources/ ou scripts auxiliares extras para aprender.

Escreva prompts melhores para obter consultas melhores

Dê à skill o mínimo de contexto necessário para montar a consulta certa: arquivo ou tabela de destino, métrica, granularidade, filtros e intervalo de tempo. Uma boa entrada parece com query "For orders.csv, show revenue by month for 2024 and exclude refunds"; uma entrada fraca parece com query "analyze the sales data". A primeira diz à skill se deve usar acesso baseado em arquivo, o que deve ser agregado e quais casos-limite importam.

FAQ da skill query

A skill query é só para especialistas em SQL?

Não. A skill query aceita SQL bruto ou perguntas em linguagem natural, então iniciantes também podem usá-la para análises diretas. Ainda assim, SQL ajuda quando você precisa de joins, filtros ou regras de agregação exatas.

Quando não devo usar a skill query?

Não use quando a tarefa exigir lógica de transformação em várias etapas, mais adequada a um notebook, job de ETL ou código de aplicação. Ela é otimizada para fazer e responder perguntas sobre dados, não para construir um produto de dados completo.

Como ela se compara a um prompt genérico?

Um prompt genérico pode gerar uma consulta plausível, mas a skill query adiciona regras operacionais: verifica o estado do DuckDB, escolhe entre modo de sessão e ad hoc, confirma se o DuckDB está disponível e faz fallback com segurança quando anexos falham. Isso a torna mais confiável para avaliação na instalação e para uso repetido da query.

Ela é uma boa opção para arquivos e análise local?

Sim. Se você quer usar a query para análise de dados em CSV, Parquet ou outros arquivos legíveis pelo DuckDB no ambiente local, esta skill é uma ótima escolha, porque foi projetada para consultar arquivos diretamente quando o estado de sessão está ausente ou não faz sentido.

Como melhorar a skill query

Informe a forma exata dos dados

As melhores melhorias vêm de nomear a origem e a forma de saída. Inclua nomes de tabelas, nomes de arquivos, as colunas que importam e a granularidade desejada. Por exemplo: query "from sessions.parquet, group by user_id and return avg session length for paid users only" dá estrutura suficiente para evitar resultados amplos ou ambíguos.

Elimine a ambiguidade antes da primeira execução

Um modo comum de falha é pedir “insights” sem dizer o que deve ser contado, comparado ou filtrado. Se você já souber a métrica, a janela de datas ou a regra de segmentação, coloque isso logo no início. Isso reduz o vai e vem e torna a primeira resposta mais útil.

Verifique cedo as restrições específicas do modo

Se você espera usar o modo de sessão, garanta que o estado do projeto está presente e que os bancos anexados ainda abrem corretamente. Se você espera usar o modo arquivo, referencie o arquivo diretamente no prompt ou passe --file. Isso importa porque a skill query se comporta de forma diferente dependendo de conseguir reaproveitar o estado existente ou precisar operar ad hoc.

Itere refinando o objetivo da consulta

Depois do primeiro resultado, melhore o próximo prompt adicionando uma restrição de cada vez: um intervalo de tempo mais curto, uma chave de junção melhor, um nível diferente de agrupamento ou uma exclusão obrigatória. Isso mantém a query skill avançando para um resultado pronto para decisão, em vez de um resumo vago.