Requêtes - Rédiger et Exécuter des Requêtes de Données

La fonctionnalité Requêtes vous permet de rédiger, exécuter et gérer des requêtes SQL sur vos bases de données connectées. Ce guide couvre l'interface de l'éditeur de requêtes, les options d'exécution, la gestion des paramètres et les considérations spécifiques aux types de bases de données.

Accéder aux Requêtes

1. Accédez à votre rapport dans l'application
2. Cliquez sur l'onglet Requête dans la navigation du rapport
3. Sélectionnez une requête existante ou créez-en une nouvelle

Note : L'interface de requête comprend des onglets pour Requête, Tableau, Paramètres, Requête Rendu et Historique des Exécutions.

Interface de l'Éditeur de Requêtes

L'éditeur de requêtes s'adapte en fonction du type de connexion de votre base de données :

Génération de Requêtes Assistée par IA

PyQueryHub inclut un assistant IA intelligent qui peut générer des requêtes SQL à partir de descriptions en langage naturel :

Utilisation de l'Assistant IA :

1. Cliquez sur le bouton Assistant IA dans la barre d'outils de l'éditeur de requêtes
2. Décrivez ce que vous voulez en anglais simple (par ex., "Montrez-moi tous les utilisateurs qui se sont inscrits au cours des 7 derniers jours")
3. L'IA générera une requête MySQL basée sur le schéma de votre base de données et votre description
4. Révisez et modifiez la requête générée si nécessaire
5. Cliquez sur Générer & Exécuter pour exécuter la requête immédiatement

Fonctionnalités de l'Assistant IA :

• Traitement du langage naturel - Comprend des demandes de données complexes en anglais simple
• Connaissance du schéma - Utilise la structure réelle de votre base de données pour générer des requêtes précises
• Optimisation MySQL - Génère des requêtes spécifiquement optimisées pour la syntaxe MySQL
• Compréhension du contexte - Interprète les relations entre les tables et les modèles de requête courants
• Exécution instantanée - Les requêtes générées peuvent être exécutées immédiatement ou personnalisées davantage

Exemples de prompts :

• "Afficher les ventes par région pour le mois en cours"
• "Trouver les clients qui n'ont pas effectué d'achat depuis 90 jours"
• "Obtenir les 10 meilleurs produits par chiffre d'affaires ce trimestre"
• "Lister tous les utilisateurs avec des profils incomplets"

Connexions aux Bases de Données SQL

Pour les bases de données traditionnelles (MySQL, PostgreSQL, BigQuery, etc.) :

• Éditeur de Code Monaco : Éditeur SQL complet avec coloration syntaxique
• Mise en Page Redimensionnable : Faites glisser le séparateur pour ajuster le ratio éditeur/résultats
• Panneau de Schéma de Base de Données : Basculez le panneau de droite pour parcourir les tables et les colonnes
• Auto-complétion : Mots-clés SQL et suggestions de schéma de base de données
• Métriques d'Exécution : Affichez le temps d'exécution de la requête et la taille des données

Exécution de Requêtes SQL :

1. Rédigez votre SQL dans l'éditeur Monaco
2. Cliquez sur le bouton Exécuter ou appuyez sur Ctrl/Cmd + Entrée
3. Les résultats apparaissent ci-dessous avec des colonnes triables
4. Les métriques d'exécution sont affichées (temps, taille des données)

Connexions Google Sheets

Pour les connexions Google Sheets, l'interface est différente :

• Sélecteur de Feuille de Calcul : Choisissez parmi les feuilles de calcul de votre Google Drive
• Sélecteur de Feuille : Sélectionnez la feuille/l'onglet spécifique dans la feuille de calcul
• Pas d'Éditeur SQL : Google Sheets ne prend pas en charge les requêtes SQL
• Importation de Données Brutes : Les données complètes de la feuille sont importées pour le traitement des graphiques

Utilisation de Google Sheets :

1. Sélectionnez une feuille de calcul dans le menu déroulant
2. Choisissez la feuille/l'onglet spécifique que vous souhaitez utiliser
3. Les données sont importées automatiquement - aucune exécution de requête n'est nécessaire
4. Tout le filtrage et le traitement se font dans la configuration du graphique

---

Onglet Tableau

Affichez les résultats de votre dernière requête dans un tableau en plein écran :

• La pagination est fixée à 50 lignes par page
• Vous pouvez trier par n'importe quel en-tête de colonne
• Vue en plein écran pour une analyse détaillée des données

---

Onglet Paramètres

Si votre requête utilise des paramètres (définis en YAML), l'onglet Paramètres vous permet de :

1. Remplir ou ajuster les valeurs des paramètres via un formulaire
2. Ré-exécuter la requête avec de nouvelles valeurs pour voir les résultats mis à jour
3. Tester différentes combinaisons de paramètres

---

Onglet Requête Rendu

Voyez le SQL réel envoyé à la base de données après le traitement des modèles Liquid :

• Éditeur en lecture seule affichant la requête finale
• Pratique pour déboguer la substitution de paramètres
• Copiez l'instruction finale pour une utilisation externe

---

Panneau d'Options de Requête & Schéma

Cliquez sur le bouton de basculement du panneau en haut à droite pour ouvrir/fermer le panneau d'Options de Requête & Schéma, qui comprend trois onglets principaux :

Onglet Schéma

L'onglet Schéma offre de puissantes fonctionnalités d'exploration de base de données et d'injection de code :

• Connexion à la Base de Données : Basculez entre vos connexions de base de données configurées via un menu déroulant
• Nom de la Requête : Modifiez et renommez votre requête directement dans le panneau
• Navigateur de Schéma : Vue arborescente extensible de la structure de votre base de données
• Injection de Table : Cliquez sur l'icône de flèche (▷) à côté de n'importe quelle table pour injecter le nom de la table dans votre requête
• Injection de Champ : Cliquez sur des champs individuels pour injecter des noms de colonnes dans votre SQL
• Actualisation du Schéma : Bouton d'actualisation (🔄) pour mettre à jour le schéma de la base de données si la structure change
• Aperçu SQL : Cliquez sur l'icône d'expansion à côté des tables pour injecter le SQL complet de la table pour un aperçu

Fonctionnalités d'Injection de Schéma

Le panneau de schéma facilite la rédaction de requêtes grâce à ces capacités d'injection :

Injection de Nom de Table :

• Cliquez sur l'icône ▷ à côté de n'importe quelle table (par ex., detailed_support_analytics, quarterly_sales, wine)
• Le nom de la table est automatiquement inséré à la position de votre curseur dans l'éditeur de requêtes
• Parfait pour les clauses FROM et les instructions JOIN

Injection de Nom de Champ :

• Développez n'importe quelle table pour voir ses colonnes avec les types de données
• Cliquez sur des champs individuels (par ex., report_month: date, product_name: string)
• Les noms de champs sont injectés directement dans votre requête
• Permet de gagner du temps de frappe et d'éviter les erreurs de nom de colonne

Actualisation du Schéma :

• Le schéma de la base de données est mis en cache pour des raisons de performance
• Cliquez sur l'icône d'actualisation (🔄) lorsque la structure de votre base de données change
• Met à jour les listes de tables, les noms de colonnes et les types de données
• Essentiel lorsque de nouvelles tables ou colonnes sont ajoutées

Aperçu & Structure SQL :

• Utilisez la fonctionnalité d'aperçu pour voir les structures complètes des tables
• Injectez des définitions SQL de table entières pour référence
• Utile pour comprendre les types de données et les contraintes

Onglet Aperçu

L'onglet Aperçu offre une exploration interactive des données avec des aperçus automatiques des tables :

Sélection & Aperçu de Table :

• Cliquez sur n'importe quelle table dans le navigateur de schéma pour charger automatiquement un aperçu de 100 enregistrements
• Les données de la table apparaissent instantanément dans l'onglet Aperçu sans exécuter de requête
• Parfait pour explorer la structure et le contenu des données avant de rédiger du SQL
• Pas besoin d'écrire SELECT * FROM table LIMIT 100 - c'est automatique

Injection de Nom de Champ depuis l'Aperçu :

• Cliquez sur n'importe quel en-tête de colonne dans l'aperçu pour injecter le nom du champ dans votre requête
• Les noms de champs sont insérés à la position de votre curseur dans l'éditeur SQL
• Combinez avec l'injection de table pour une construction rapide de requêtes
• Élimine les erreurs de frappe et accélère le développement des requêtes

Flux de Travail d'Exploration de Données :

1. Parcourez les tables dans l'onglet Schéma
2. Cliquez sur un nom de table pour voir un aperçu des données dans l'onglet Aperçu
3. Cliquez sur les en-têtes de colonne pour injecter les noms de champs dans votre requête
4. Utilisez l'icône d'actualisation si la structure de la table change
5. Construisez des requêtes efficacement avec une référence visuelle des données

Cette fonctionnalité rend l'exploration des données intuitive - vous pouvez voir des échantillons de données réels tout en construisant vos requêtes, ce qui facilite la compréhension des types de données, des formats et des modèles de contenu.

Onglet Paramètres

L'onglet Paramètres offre des options de configuration complètes de l'éditeur de requêtes :

Configuration de la Requête :

• Nom : Modifiez le nom de la requête directement dans le panneau
• Connexion : Basculez entre différentes connexions de base de données via un menu déroulant

Options d'Insertion de Champ :

• Inclure le nom de la table dans l'insertion de champ : Lorsque cette option est activée, cliquer sur les champs injecte le format table.colonne au lieu de simplement colonne
• Ajouter des guillemets aux noms de table lors des insertions : Enveloppe automatiquement les noms de table de backticks lors de l'injection (par ex., `nom_table`)
• Inclure le jeu de données pour les tables : Pour les bases de données comme BigQuery, inclut le préfixe du jeu de données (par ex., jeu_de_donnees.table.colonne)

Auto-complétion & Suggestions :

• Activer l'auto-complétion : Active/désactive la fonctionnalité d'auto-complétion de l'éditeur Monaco
• Suggérer les tables : Inclut les noms de tables dans les suggestions d'auto-complétion
• Suggérer les colonnes : Inclut les noms de colonnes dans les suggestions d'auto-complétion
• Suggérer les mots-clés SQL : Inclut les mots-clés SQL (SELECT, FROM, WHERE, etc.) dans les suggestions
• Ajouter des guillemets dans les suggestions d'auto-complétion : Ajoute automatiquement des guillemets autour des noms de table/colonne dans les suggestions

Style de Code :

• Casse des mots-clés : Choisissez entre MAJUSCULES ou minuscules pour les mots-clés SQL
  • MAJUSCULES : SELECT, FROM, WHERE (style SQL traditionnel)
  • minuscules : select, from, where (préférence moderne)

Thème de l'Éditeur :

• Mode Clair : Thème d'éditeur lumineux avec texte sombre sur fond clair
• Mode Sombre : Thème d'éditeur sombre avec texte clair sur fond sombre (par défaut)

Ces paramètres sont enregistrés en tant que cookies de navigateur et persistent entre les sessions. Chaque paramètre affecte immédiatement le comportement de l'éditeur de requêtes, vous permettant de personnaliser l'expérience de développement pour qu'elle corresponde à vos préférences et à vos normes de codage.

Assistant de Requête IA

PyQueryHub inclut un assistant de requête alimenté par l'IA :

• Prompts en Langage Naturel : Décrivez les données dont vous avez besoin en anglais simple
• Génération de Requêtes : L'IA génère du SQL en fonction de votre schéma de base de données et de votre prompt
• Affinement de Requêtes : Améliorez les requêtes existantes avec l'aide de l'IA
• Suivi de l'Utilisation des Jetons : L'utilisation de l'IA est suivie par espace de travail avec des limites de quota

Planification de Requêtes et Alertes

Les requêtes peuvent être planifiées pour s'exécuter automatiquement :

• Configuration de la Planification : Définissez des heures d'exécution récurrentes
• Intégration des Alertes : Déclenchez des notifications lorsque les résultats des requêtes remplissent des conditions spécifiques
• Suivi de l'Historique : Toutes les exécutions planifiées sont enregistrées avec les détails de l'exécution

---

Exécution de Requêtes et Résultats

Méthodes d'Exécution

• Bouton Exécuter : Cliquez sur le bouton Exécuter dans l'interface
• Raccourci Clavier : Appuyez sur Ctrl/Cmd + Entrée pour exécuter
• Texte Sélectionné : Exécutez uniquement la partie sélectionnée de votre requête
• Exécution en Arrière-plan : Les requêtes volumineuses s'exécutent de manière asynchrone avec un suivi de la progression

Affichage des Résultats

• Résultats en Ligne : Les résultats apparaissent sous l'éditeur dans l'onglet Requête
• Tableau en Plein Écran : Passez à l'onglet Tableau pour une vue agrandie
• Colonnes Triables : Cliquez sur les en-têtes de colonne pour trier les résultats
• Pagination : Les résultats sont paginés pour les grands ensembles de données
• Options d'Exportation : Téléchargez les résultats dans divers formats

Métriques d'Exécution

Chaque exécution de requête fournit des métriques détaillées :

• Temps d'Exécution : Durée d'exécution de la requête en millisecondes
• Taille des Données : Taille des données retournées en octets
• Nombre de Lignes : Nombre de lignes retournées
• Historique des Exécutions : Exécutions précédentes avec horodatages et données de performance

Gestion des Erreurs

• Erreurs de Syntaxe : Les problèmes de syntaxe SQL sont mis en évidence dans l'éditeur
• Erreurs de Base de Données : Les erreurs de connexion et d'exécution sont clairement affichées
• Gestion des Délais d'Attente : Les requêtes de longue durée disposent d'une gestion appropriée des délais d'attente
• Logique de Réessai : Les requêtes échouées peuvent être facilement ré-exécutées

---

Paramètres de Requête et Modèles

Les requêtes prennent en charge les paramètres dynamiques via les modèles Liquid :

Système de Paramètres

• Définition YAML : Les paramètres sont définis au format YAML
• Prise en Charge des Types : Texte, nombres, dates, listes déroulantes, etc.
• Valeurs par Défaut : Définissez des valeurs par défaut pour les paramètres
• Validation : La validation des paramètres garantit l'intégrité des données

Modèles Liquid

PyQueryHub utilise les modèles Liquid pour l'injection de paramètres :

• Substitution de Paramètres : Syntaxe {{ nom_parametre }}
• Logique Conditionnelle : Instructions @{% if %} pour les requêtes dynamiques
• Filtres : Appliquez des formatages et des transformations
• Instructions Assign : Créez des variables dérivées

Interface des Paramètres

• Formulaires Auto-générés : Les paramètres créent des contrôles de formulaire interactifs
• Mises à Jour en Temps Réel : Modifiez les valeurs des paramètres et ré-exécutez les requêtes
• Historique des Paramètres : Les valeurs des paramètres précédentes sont enregistrées avec les exécutions de requêtes

Pour une documentation détaillée sur les paramètres, consultez le guide Paramètres.

Historique des Requêtes et Versionnement

Historique des Exécutions

• Piste d'Audit Complète : Chaque exécution de requête est enregistrée
• Stockage des Résultats : Les résultats des requêtes sont stockés pour une récupération rapide
• Suivi des Paramètres : Les valeurs des paramètres utilisées pour chaque exécution sont sauvegardées
• Métriques de Performance : Temps d'exécution et taille des données pour chaque exécution

Versionnement des Requêtes

• Stockage des Requêtes Originales : Les requêtes originales et rendues sont sauvegardées
• Instantanés des Paramètres : Les paramètres utilisés pour chaque exécution sont préservés
• Comparaison des Résultats : Comparez les résultats de différentes exécutions
• Récupération de l'Historique : Accédez aux versions et résultats précédents des requêtes

Fonctionnalités Spécifiques aux Bases de Données

Bases de Données SQL Traditionnelles

• Support SQL Complet : Prise en charge complète de la syntaxe SQL en fonction du type de base de données
• Introspection du Schéma : Découverte automatique des tables, colonnes et types
• Changement de Connexion : Changez de connexion de base de données par requête
• Optimisation des Performances : Métriques d'exécution des requêtes et suggestions d'optimisation

Google Sheets

• Pas d'Interface SQL : Interface de sélection de feuille de calcul et de feuille
• Données en Temps Réel : Connexion directe aux données en direct de Google Sheets
• Détection de Schéma : Détection automatique des noms de colonnes à partir de la première ligne
• Authentification : Connexion sécurisée basée sur OAuth à Google Drive

Entrepôts de Données Cloud

• BigQuery : Prise en charge des requêtes analytiques complexes
• Redshift : Optimisé pour les opérations d'entrepôt de données à grande échelle
• Azure SQL : Fonctionnalités de sécurité et de performance de niveau entreprise

Meilleures Pratiques

Performance des Requêtes

• Utilisez des clauses LIMIT : Évitez de retourner accidentellement d'énormes ensembles de données
• Optimisez les conditions WHERE : Utilisez les index efficacement
• Validation des paramètres : Validez les paramètres pour prévenir l'injection SQL
• Gestion des connexions : Choisissez les connexions de base de données appropriées

Organisation du Code

• Noms descriptifs : Utilisez des noms de requête clairs et significatifs
• Commentaires : Documentez les requêtes complexes avec des commentaires SQL
• Documentation des paramètres : Expliquez les objectifs des paramètres en YAML
• Contrôle de version : Utilisez l'historique des requêtes pour suivre les modifications

Considérations de Sécurité

• Liaison de paramètres : Utilisez toujours des paramètres au lieu de la concaténation de chaînes
• Isolation des connexions : Utilisez des utilisateurs de base de données appropriés avec des autorisations limitées
• Accès aux données : Assurez-vous que les requêtes n'accèdent qu'aux données autorisées
• Journalisation d'audit : Surveillez l'exécution des requêtes et l'accès aux données

Dépannage

Problèmes Courants

• Erreurs de Connexion : Vérifiez les paramètres de connexion à la base de données et les informations d'identification
• Problèmes de Délai d'Attente : Optimisez les requêtes ou augmentez les limites de délai d'attente
• Erreurs de Permissions : Vérifiez les autorisations de l'utilisateur de la base de données
• Erreurs de Paramètres : Validez les types et les valeurs des paramètres

Obtenir de l'Aide

• Messages d'Erreur : Lisez attentivement les messages d'erreur pour des conseils spécifiques
• Historique des Requêtes : Consultez les exécutions réussies précédentes pour référence
• Journaux de la Base de Données : Examinez les journaux de la base de données pour des informations d'erreur détaillées
• Support : Contactez le support avec des messages d'erreur spécifiques et les détails de la requête

Pour plus d'informations sur les fonctionnalités connexes :

• Types de Bases de Données : Guides détaillés de connexion aux bases de données
• Paramètres : Documentation du système de paramètres
• Graphiques : Utilisation des résultats de requêtes dans les visualisations