# Éditeur SQL

> L'éditeur SQL DuckDB de DuckLocal : onglets de requête, formatage, erreurs en ligne, autocomplétion selon le schéma, plans Explain, profilage par opérateur et raccourcis.

Source: https://ducklocal.app/docs/fr/sql-editor

Chaque onglet de requête a son propre tampon d'éditeur. L'éditeur met en
évidence le vrai SQL via tree-sitter, indente avec 2 espaces et affiche les
numéros de ligne.

## Onglets {#tabs}

| Contrôle | Ce que ça fait |
| --- | --- |
| `+` ou **⌘T** | Ajoute un nouvel onglet de requête et y place le focus |
| Cliquer sur un onglet | Bascule dessus |
| **Ctrl+Tab** / **Ctrl+Shift+Tab** | L'onglet suivant / précédent |
| **⌘1** … **⌘8**, **⌘9** | Le premier au huitième onglet ; ⌘9 est le dernier onglet |
| Glisser un onglet | Le déplace le long de la bande |
| `×`, **⌘W** ou un clic du milieu | Ferme un onglet. Le dernier onglet ne peut pas être fermé : son `×` est masqué et ⌘W ne fait rien. Un tableau de bord avec des modifications non enregistrées demande d'abord confirmation |
| Clic droit sur un onglet | **Fermer l'onglet**, **Fermer les autres onglets**, **Fermer les onglets à droite**. Les tableaux de bord avec des modifications non enregistrées restent ouverts, et un message indique combien |
| Double-clic sur un onglet | Modifie son titre sur place. Entrée ou un clic ailleurs conserve le nouveau titre, Échap conserve l'ancien ; un titre vide revient à `Query N` |

Les onglets ouverts reviennent au prochain lancement, dans leur ordre : les
onglets de requête avec leurs titres et le SQL de leurs éditeurs, qu'il ait été
exécuté ou non, et les onglets de tableau de bord. Les résultats, non — relancez
la requête. Un onglet de requête créé de zéro commence par
`SELECT 'Hello, DuckLocal' AS greeting;`.

## La barre d'outils {#the-toolbar}

Au-dessus de l'éditeur, depuis la gauche :

| Bouton | Ce que ça fait |
| --- | --- |
| **Exécuter** | Exécute le SQL de l'éditeur — voir [Exécuter du SQL](#running-sql) |
| **Arrêter** | Affiché dès qu'une exécution dure depuis un moment ; l'interrompt |
| **Formater** | Reformate le SQL — voir [Formater](#format) |
| **Explain** | Affiche le plan que DuckDB utiliserait, sans exécuter l'instruction |
| **Profilage** | Exécute la requête et affiche ce que chaque opérateur a coûté |

**Explain** et **Profilage** sont décrits dans
[Explain et profilage](#explain-and-profile).

## Exécuter du SQL {#running-sql}

Appuyez sur **⌘↵** (Cmd+Enter) avec l'éditeur au focus, ou utilisez le bouton
**Exécuter**.

Pendant qu'une requête s'exécute, appuyer de nouveau sur Exécuter ne fait rien
(Explain et Profilage non plus), et un bouton **Arrêter** apparaît à côté
d'Exécuter dès que la requête s'exécute depuis un moment. Arrêter, ou **⌘.**,
interrompt la requête ; elle se termine par
l'erreur `Interrupted` de DuckDB, enregistrée dans l'historique comme tout échec.
Il n'y a pas de délai d'expiration : sans Arrêter, une requête s'exécute aussi
longtemps que DuckDB en a besoin, et les autres travaux sur la base attendent
derrière elle.

Les résultats sont diffusés en flux depuis DuckDB, donc un balayage s'arrête dès
que la [limite de lignes](results-and-charts.md#row-limits) de la grille est
atteinte au lieu de lire le reste du fichier. Une requête qui doit voir chaque
ligne avant sa première — `ORDER BY`, `GROUP BY`, une agrégation, une fonction de
fenêtrage — calcule tout de même en entier.

Chaque onglet a ses propres résultats. Un résultat qui arrive après que vous avez
changé d'onglet arrive dans l'onglet qui l'a lancé.

Le traitement d'une instruction dépend de son mot-clé de tête. `SELECT`, `WITH`,
`SHOW`, `DESCRIBE`, `EXPLAIN`, `PRAGMA`, `SUMMARIZE`, `VALUES`, `FROM`,
`TABLE`, `PIVOT` et `CALL` produisent un jeu de résultats. Tout le reste —
instructions DDL (définition de données) et DML (modification de données) —
affiche `Done: N rows affected, took …` au lieu d'une grille. Les commentaires
`--` de tête sont ignorés au moment de décider ; les commentaires de bloc ne le
sont pas.

### Scripts {#scripts}

L'éditeur peut contenir plusieurs instructions. **Exécuter** les exécute toutes,
dans l'ordre, comme le shell DuckDB lit un fichier, et **s'arrête au premier
échec** — exécuter un `SELECT` après un `ATTACH` raté n'ajouterait qu'une
seconde erreur trompeuse. Une bande au-dessus des résultats liste les
instructions, chacune marquée de son nombre de lignes, *terminée*, *échouée* ou
*non exécutée* ; cliquez sur l'une pour voir son résultat. Une erreur souligne
l'instruction qui a échoué, pas tout le script.

Quelques commandes à point du shell fonctionnent aussi, chacune sur sa propre
ligne :

| Commande | Affiche |
| --- | --- |
| `.tables ?PATTERN?` | Les tables et les vues, éventuellement filtrées par un motif `ILIKE` comme `stat%` |
| `.schema ?PATTERN?` | Les instructions `CREATE` des tables et des vues, éventuellement filtrées |
| `.databases` | Les bases attachées |
| `.help` | Cette liste |

Toute autre commande à point (`.mode`, `.read`, …) donne une erreur qui nomme
celles qui fonctionnent.

## Erreurs {#errors}

Une instruction qui échoue affiche une alerte intitulée *Query failed* avec le
message de DuckDB mot pour mot. Le message vient du moteur et est toujours en
anglais, quelle que soit la langue de l'interface. Rien n'est écrit dans la
grille, et la tentative est tout de même enregistrée dans
l'[historique](schema-and-history.md) avec une marque d'échec.

Quand le message désigne une position — c'est le cas des erreurs d'analyseur et de
liaison, avec une ligne `LINE n:` et un caret — l'éditeur souligne cet endroit
d'une ligne ondulée rouge : le jeton que le caret marque, ou l'étendue que couvre
une suite de carets. La marque suit vos modifications et disparaît à l'exécution
suivante. Les erreurs d'exécution n'ont pas de position et ne reçoivent pas de
marque.

## Formater {#format}

**Formater** passe le tampon dans `sqlformat` avec une indentation de 2 espaces et
des mots-clés en majuscules, puis remplace tout le tampon. Il ne fait rien sur un
tampon vide.

## Explain et profilage {#explain-and-profile}

Les deux boutons travaillent sur tout le texte de l'éditeur, et tous deux
attendent **exactement une instruction**. Avec deux instructions ou plus — ou avec
une commande à point — ils refusent avec *Explain et Profilage prennent une seule
instruction : mettez celle que vous voulez examiner dans un onglet à part.*
Un `;` final et des commentaires finaux sont acceptés.

Pendant que l'une des actions Exécuter, Explain ou Profilage est en cours, les
deux autres ne font rien. Ni Explain ni Profilage ne sont enregistrés dans
l'[historique](schema-and-history.md#query-history). Leur sortie remplace la
grille dans l'onglet **Résultats**, en basculant dessus si un autre onglet était
ouvert ; un échec affiche l'alerte *Query failed*, comme une exécution ratée.

### Explain {#explain}

**Explain** exécute `EXPLAIN <your statement>` et affiche le plan de DuckDB en
texte monospace simple, avec le temps que cela a pris. Il ne fait que planifier :
l'instruction n'est pas exécutée, donc expliquer un `INSERT`, un `UPDATE` ou un
`DELETE` est sans risque.

### Profilage {#profile}

**Profilage** exécute l'instruction sous `EXPLAIN (ANALYZE, FORMAT JSON)` et
affiche le plan exécuté sous forme d'arbre : le temps propre de chaque
opérateur et sa part du total, les lignes qu'il a produites face à l'estimation de
l'optimiseur (signalées quand l'écart dépasse 10×), et ce qu'il a filtré, joint
ou projeté. L'opérateur qui a coûté le plus est nommé en haut et dessiné en rouge.
Comment le lire :
[Sortie d'Explain et profilage](results-and-charts.md#explain-and-profile).

**Le profilage exécute vraiment l'instruction** — c'est ainsi que ses opérateurs
sont chronométrés. Il n'accepte donc qu'une seule requête en lecture seule :

- **Accepté :** `SELECT`, `WITH … SELECT`, `FROM …`, `VALUES`, `TABLE`, `SHOW`,
  `DESCRIBE`, `SUMMARIZE`.
- **Refusé :** tout ce qui écrit (`INSERT`, `UPDATE`, `DELETE`,
  `CREATE`, …), `CALL`, `PRAGMA`, `COPY`, `EXPLAIN` lui-même, une écriture cachée
  derrière un `WITH` (`WITH s AS (…) INSERT …`), et un `PIVOT` sans liste
  `IN (…)` explicite.

Une instruction refusée reçoit *Seules les instructions qui lisent peuvent être
profilées (SELECT, WITH, FROM…) : le profilage exécute l'instruction.* C'est
l'analyseur de DuckDB lui-même qui en décide avant toute exécution, pas le premier
mot-clé.

Un profilage prend aussi longtemps que la requête, plus le coût de sa mesure.
**Arrêter** (ou **⌘.**) l'interrompt comme une exécution.

## Autocomplétion {#autocompletion}

Le menu de complétion tient compte du catalogue. Les candidats sont classés :

1. Les tables et les colonnes du schéma (jusqu'à 35 entrées)
2. Les noms de fonctions DuckDB
3. Les mots-clés SQL

Au plus 50 éléments sont proposés. La correspondance se fait sur un **préfixe**,
sans tenir compte de la casse, de l'identifiant immédiatement à gauche du curseur,
donc `sel` complète en `SELECT` mais `elect` ne complète rien. Une fonction insère
son nom et une parenthèse ouvrante ; les identifiants qui contiennent des espaces
ou des caractères spéciaux sont insérés entre guillemets doubles.

Les listes de mots-clés et de fonctions sont un sous-ensemble choisi — toutes les
fonctions DuckDB n'apparaîtront pas.

## Raccourcis clavier {#keyboard-shortcuts}

Sous Windows et Linux, lisez **Ctrl** partout où figure **⌘**.

Les raccourcis propres à DuckLocal, tous listés dans la barre de menus :

| Raccourci | Action |
| --- | --- |
| ⌘↵ | Exécuter la requête |
| ⌘. | Arrêter la requête en cours |
| ⌘T | Nouvel onglet de requête |
| ⌘W | Fermer l'onglet |
| Ctrl+Tab / Ctrl+Shift+Tab | Onglet suivant / précédent (Ctrl aussi sur un Mac) |
| ⌘1 … ⌘9 | Aller à l'onglet à cette position ; ⌘9 est le dernier |
| ⌘O | Ouvrir des données |
| ⌘S | Enregistrer la source d'un tableau de bord, dans sa vue source |
| ⌘B | Masquer ou afficher la barre latérale |
| ⌘+ / ⌘− / ⌘0 | Agrandir / réduire / revenir à la taille par défaut de l'interface — voir [Taille de l'interface](settings-and-data.md#interface-size) |
| ⌘Q | Quitter |

Ceux de l'éditeur, qui se comportent comme dans n'importe quel champ de texte :

| Raccourci | Action |
| --- | --- |
| ⌘F / ⇧⌘F | Rechercher / remplacer dans l'éditeur |
| ⌘Z / ⇧⌘Z | Annuler / rétablir |
| ⌘A | Tout sélectionner |
| ⌘C / ⌘X / ⌘V | Copier / couper / coller |
| ⌥⌘↑ / ⌥⌘↓ | Ajouter un curseur au-dessus / en dessous |
| ⌘← / ⌘→ / ⌥← / ⌥→ | Se déplacer par ligne / par mot |
| ⌘↑ / ⌘↓ | Aller au début / à la fin du document |
| ⌘⌫ / ⌥⌫ | Supprimer jusqu'au début de la ligne / le mot précédent |

## Menus {#menus}

La barre de menus contient chaque commande de fenêtre avec son raccourci :

| Menu | Commandes |
| --- | --- |
| DuckLocal | Ligne de commande et IA, Rechercher les mises à jour…, Rechercher les mises à jour au lancement, Afficher le guide, Ouvrir le dossier des journaux, Quitter DuckLocal |
| Fichier | Nouvelle requête, Ouvrir des données, Enregistrer, Fermer l'onglet, Onglet suivant, Onglet précédent |
| Édition | Annuler, Rétablir, Couper, Copier, Coller, Tout sélectionner |
| Requête | Exécuter, Arrêter |
| Présentation | Afficher ou masquer la barre latérale, Interface plus grande, Interface plus petite, Taille par défaut, Fond de carte en ligne (OpenStreetMap) |

Windows et Linux n'ont pas de barre de menus ; là, **Afficher le guide** et
**Ouvrir le dossier des journaux** se trouvent dans le menu contextuel de la
version, à l'extrémité droite de la barre d'état.

**Fond de carte en ligne (OpenStreetMap)** est un élément à cocher ; voir
[Graphiques](results-and-charts.md#charts). Les lignes de la barre latérale de
schéma ont aussi un menu contextuel ; voir
[Schéma et historique](schema-and-history.md#right-click-menu). Il n'y a pas de
palette de commandes.
