query

Descripción general de query skill

Qué hace query skill

El skill query te ayuda a ejecutar consultas de DuckDB sobre una base de datos de trabajo adjunta o sobre archivos que indiques directamente. Está pensado para quienes quieren pasar de una pregunta al resultado lo más rápido posible: SQL ad hoc, preguntas de datos en lenguaje natural o análisis sencillo basado en archivos con DuckDB Friendly SQL.

Para quién encaja mejor

Usa query para análisis de datos cuando ya tienes la información en DuckDB, en un archivo de estado del proyecto o en un archivo local como CSV/Parquet, y quieres respuestas inmediatas sin montar un pipeline completo. Es especialmente útil para analistas, ingenieros y agentes de IA que necesitan inspeccionar datos de forma rápida e iterativa.

Por qué este skill es distinto

El principal diferenciador de query es la selección de modo. Puede funcionar en modo sesión cuando ya existe un estado previo de DuckDB, o en modo ad hoc cuando la entrada referencia archivos o cuando no hay estado disponible. Eso reduce la ambigüedad y hace que el query skill sea útil tanto en flujos persistentes como en usos puntuales.

Cómo usar query skill

Instalación e invocación básica

Instala el skill query con npx skills add duckdb/duckdb-skills --skill query. Después, ejecútalo con SQL o con una pregunta, por ejemplo: query "show daily revenue by country" o query "select count(*) from 'events.csv'". El patrón de uso de query funciona mejor cuando la solicitud es lo bastante específica como para convertirse en una única consulta clara.

Cómo decide entre modo sesión y modo ad hoc

El skill query primero comprueba si existe un archivo de estado de DuckDB en .duckdb-skills/state.sql o en ~/.duckdb-skills/<project-id>/state.sql. Si encuentra uno y las bases de datos adjuntas siguen funcionando, usa el modo sesión. Si pasas --file, haces referencia a rutas de archivos o no hay un estado utilizable, cambia a modo ad hoc y consulta los archivos directamente, o :memory: cuando hace falta. Esta es la parte más importante de la query guide, porque tu entrada debe corresponder al modo que realmente quieres usar.

Qué leer primero en el repositorio

Empieza por SKILL.md, porque contiene el flujo de ejecución, las reglas de modo y el comportamiento de fallback. Para decidir si instalarlo, normalmente eso basta. Si vas a adaptar el skill a tu propio flujo de trabajo, también revisa los archivos referenciados en el árbol del repositorio, especialmente los que definan el manejo del estado o las restricciones del prompt. En este repositorio no hay rules/, resources/ ni scripts auxiliares adicionales que aprender.

Escribe mejores prompts para obtener mejores consultas

Dale al skill el mínimo contexto que necesita para construir la consulta correcta: archivo o tabla objetivo, métrica, granularidad, filtros y rango temporal. Una entrada sólida se ve así: query "For orders.csv, show revenue by month for 2024 and exclude refunds"; una débil, así: query "analyze the sales data". El primer ejemplo le indica al skill si debe usar acceso a archivos, qué debe agregar y qué casos límite importan.

FAQ de query skill

¿query skill es solo para expertos en SQL?

No. El skill query acepta SQL sin procesar o preguntas en lenguaje natural, así que los principiantes pueden usarlo para análisis sencillos. Aun así, SQL sigue siendo útil cuando necesitas joins, filtros o reglas de agregación exactas.

¿Cuándo no debería usar query skill?

No lo uses si tu tarea necesita lógica de transformación en varios pasos que pertenece a un notebook, a un trabajo de ETL o a código de aplicación. Está optimizado para formular y responder preguntas sobre datos, no para construir un producto de datos completo.

¿Cómo se compara con un prompt genérico?

Un prompt genérico puede generar una consulta plausible, pero el skill query añade reglas operativas: comprueba el estado de DuckDB, elige entre modo sesión y modo ad hoc, verifica que DuckDB esté disponible y hace un fallback seguro cuando falla la conexión a bases adjuntas. Eso lo vuelve más fiable para la evaluación en el momento de la instalación y para el uso repetido de query.

¿Es una buena opción para archivos y análisis local?

Sí. Si quieres usar query para análisis de datos en CSV locales, Parquet u otros archivos que DuckDB pueda leer, este skill encaja muy bien porque está diseñado para consultar archivos directamente cuando no existe estado de sesión o cuando este no es el adecuado.

Cómo mejorar query skill

Proporciona la forma exacta de los datos

Las mejoras más fuertes vienen de nombrar el origen y la forma de salida. Incluye nombres de tablas, nombres de archivos, las columnas que te importan y la granularidad que quieres obtener. Por ejemplo: query "from sessions.parquet, group by user_id and return avg session length for paid users only" le da al skill suficiente estructura para evitar resultados amplios o ambiguos.

Elimina la ambigüedad antes de la primera ejecución

Un fallo habitual es pedir “insights” sin decir qué se debe contar, comparar o filtrar. Si ya conoces la métrica, la ventana temporal o la regla de segmentación, inclúyela desde el principio. Eso reduce el ida y vuelta y hace que la primera respuesta sea más útil.

Revisa pronto las restricciones específicas del modo

Si esperas modo sesión, asegúrate de que el estado del proyecto esté presente y de que sus bases de datos adjuntas sigan abiertas. Si esperas modo de archivos, referencia el archivo directamente en el prompt o pasa --file. Esto importa porque el skill query se comporta de manera distinta según si puede reutilizar el estado existente o si debe trabajar ad hoc.

Itera afinando el objetivo de la consulta

Después del primer resultado, mejora el siguiente prompt añadiendo una restricción cada vez: un rango temporal más estrecho, una clave de join mejor, un nivel de agrupación distinto o una exclusión obligatoria. Eso mantiene al query skill avanzando hacia un resultado listo para decidir, en lugar de quedarse en un resumen vago.