query

Vue d’ensemble du skill query

Ce que fait le skill query

Le skill query vous aide à exécuter des requêtes DuckDB sur une base de travail déjà attachée ou directement sur des fichiers que vous lui indiquez. Il est conçu pour celles et ceux qui veulent aller le plus vite possible d’une question à un résultat : SQL ponctuel, questions de données en langage naturel, ou analyse simple de fichiers avec DuckDB Friendly SQL.

Pour qui il est le plus adapté

Utilisez le skill query pour l’analyse de données si vos données sont déjà dans DuckDB, dans un fichier d’état de projet, ou dans un fichier local comme CSV/Parquet, et que vous voulez des réponses immédiates sans mettre en place tout un pipeline. Il est particulièrement utile aux analystes, aux ingénieurs et aux agents IA qui doivent explorer des données rapidement et de manière itérative.

En quoi ce skill est différent

Le principal atout distinctif de query est son choix de mode. Il peut fonctionner en mode session lorsqu’un état DuckDB existe déjà, ou en mode ad hoc lorsque l’entrée fait référence à des fichiers, ou encore lorsqu’aucun état n’est disponible. Cela réduit les approximations et rend le query skill utile aussi bien dans des workflows persistants que pour des usages ponctuels.

Comment utiliser le skill query

Installation et utilisation de base

Installez le skill query avec npx skills add duckdb/duckdb-skills --skill query. Puis appelez-le avec du SQL ou une question, par exemple : query "show daily revenue by country" ou query "select count(*) from 'events.csv'". Le schéma d’utilisation query usage fonctionne mieux lorsque la demande est assez précise pour se transformer en une requête nette.

Comment le skill choisit le mode session ou ad hoc

Le skill query commence par vérifier s’il existe un fichier d’état DuckDB dans .duckdb-skills/state.sql ou ~/.duckdb-skills/<project-id>/state.sql. S’il en trouve un et que les bases attachées fonctionnent encore, il passe en mode session. Si vous utilisez --file, si vous référencez des chemins de fichiers, ou si aucun état exploitable n’est disponible, il bascule en mode ad hoc et interroge directement les fichiers, ou :memory: si nécessaire. C’est l’aspect le plus important du query guide, car votre entrée doit correspondre au mode que vous voulez réellement utiliser.

Ce qu’il faut lire en premier dans le dépôt

Commencez par SKILL.md, car c’est là que se trouvent le flux d’exécution, les règles de mode et le comportement de repli. Pour décider si l’installation vous convient, cela suffit généralement. Si vous adaptez le skill à votre propre workflow, consultez aussi les fichiers référencés dans l’arborescence du dépôt, en particulier ceux qui définissent la gestion de l’état ou les contraintes de prompt. Dans ce dépôt, il n’y a ni rules/, ni resources/, ni scripts d’assistance supplémentaires à apprendre.

Mieux rédiger vos prompts pour obtenir de meilleures requêtes

Donnez au skill le minimum de contexte nécessaire pour construire la bonne requête : fichier ou table cible, métrique, granularité, filtres et plage temporelle. Une bonne entrée ressemble à query "For orders.csv, show revenue by month for 2024 and exclude refunds" ; une entrée faible ressemble à query "analyze the sales data". Dans le premier cas, le skill sait qu’il doit utiliser un accès basé sur les fichiers, quoi agréger et quels cas limites sont importants.

FAQ sur le skill query

Le skill query est-il réservé aux experts SQL ?

Non. Le skill query accepte du SQL brut ou des questions en langage naturel, donc les débutants peuvent l’utiliser pour des analyses simples. Le SQL reste toutefois utile lorsque vous avez besoin de jointures, de filtres ou de règles d’agrégation très précises.

Quand ne faut-il pas utiliser le skill query ?

N’utilisez pas ce skill si votre tâche exige une logique de transformation en plusieurs étapes qui relève plutôt d’un notebook, d’un job ETL ou de code applicatif. Il est optimisé pour poser et traiter des questions sur des données, pas pour construire un produit de données complet.

En quoi est-il différent d’un prompt générique ?

Un prompt générique peut produire une requête plausible, mais le skill query ajoute des règles opérationnelles : il vérifie l’état DuckDB, choisit entre mode session et mode ad hoc, contrôle la disponibilité de DuckDB et bascule de manière sûre si les pièces jointes échouent. Cela le rend plus fiable pour une évaluation au moment de l’installation et pour une utilisation répétée de query usage.

Est-ce un bon choix pour les fichiers et l’analyse locale ?

Oui. Si vous voulez faire query for Data Analysis sur des fichiers locaux CSV, Parquet ou autres fichiers lisibles par DuckDB, ce skill est particulièrement adapté, car il est conçu pour interroger directement les fichiers lorsque l’état de session est absent ou inadapté.

Comment améliorer le skill query

Fournir la forme exacte des données

Les améliorations les plus efficaces viennent du fait de nommer la source et la forme attendue du résultat. Indiquez les noms de tables, les noms de fichiers, les colonnes qui vous intéressent et la granularité souhaitée. Par exemple : query "from sessions.parquet, group by user_id and return avg session length for paid users only" donne au skill une structure suffisante pour éviter des résultats trop larges ou ambigus.

Lever les ambiguïtés avant la première exécution

Un échec fréquent consiste à demander des “insights” sans préciser ce qui doit être compté, comparé ou filtré. Si vous connaissez la métrique, la fenêtre de dates ou la règle de segmentation, dites-le dès le départ. Cela limite les allers-retours et rend la première réponse plus utile.

Vérifier tôt les contraintes liées au mode

Si vous vous attendez au mode session, assurez-vous que l’état du projet est présent et que les bases attachées sont toujours ouvertes. Si vous vous attendez au mode fichier, référencez le fichier directement dans le prompt ou passez --file. C’est important, car le skill query ne se comporte pas de la même manière selon qu’il peut réutiliser un état existant ou qu’il doit fonctionner en mode ad hoc.

Itérer en resserrant l’objectif de la requête

Après le premier résultat, améliorez le prompt suivant en ajoutant une contrainte à la fois : une plage temporelle plus courte, une meilleure clé de jointure, un niveau de regroupement différent ou une exclusion obligatoire. Cela permet au query skill d’avancer vers un résultat exploitable pour la décision, plutôt que vers un simple résumé vague.