# Navigateur de schéma et historique

> Parcourez bases, tables et colonnes, générez des requêtes SELECT, gérez les extensions DuckDB et réutilisez les requêtes passées.

Source: https://ducklocal.app/docs/fr/schema-and-history

La barre latérale a trois onglets : **Schéma**, **Historique** et **Extensions**
(**表结构**, **查询历史** et **扩展** en chinois). Le bouton à gauche de la
barre de titre, ou **⌘B**, masque la barre latérale et la fait revenir ; le bouton
reste au même endroit dans les deux cas. L'état masqué de la barre latérale est
mémorisé.

## L'arborescence du schéma

De haut en bas, l'arborescence affiche **Fichiers locaux**, **Tableaux de bord**, **Métriques** et **S3** comme de petits titres de section en gris, puis vos bases de données en lignes grasses :

- **Fichiers locaux** — les fichiers de données que vous avez enregistrés, chacun
  nommé d'après sa vue, avec son nombre de lignes. Ses enfants sont les colonnes
  de la vue.
  - Le nom du fichier n'apparaît à côté du nom de la vue que lorsque les deux
    diffèrent (`sales_2` pour `sales.csv`).
  - Le dossier apparaît lorsque deux fichiers partagent un nom de vue.
  - Survolez une ligne pour voir le chemin complet.
- **Tableaux de bord** — les tableaux de bord `.dash` ouverts récemment, triés
  par nom, afin qu'une ligne ne bouge pas lorsque vous cliquez dessus.
  - Cliquez sur l'un d'eux pour le rouvrir dans un onglet, comme vous le feriez
    pour un fichier.
  - Deux tableaux de bord du même nom affichent leur dossier à côté. Un même
    fichier atteint par deux écritures de son chemin (`E:\Proj` et `E:\proj`, ou
    un chemin relatif et un chemin absolu) compte pour une seule entrée et
    n'ouvre qu'un seul onglet.
  - Le × au survol le retire de la liste, sans toucher à ses fichiers ni à un
    onglet ouvert.
  - Une entrée dont le chemin n'existe plus est retirée de la liste.
- **Métriques** — présent quand un `model.ossie.yaml` se trouve à côté de l'un
  de ces tableaux de bord. Une ligne par métrique ; un clic la compile dans
  l'éditeur de requêtes et l'exécute. Voir
  [Métriques sémantiques](metrics.md#sidebar). Plus récent que 0.4.1.
- **S3** — présent une fois [S3 configuré](s3.md). Chargé à la demande.
- Chaque base de données, puis ses schémas, puis les tables et les vues, puis les
  colonnes. La base de données ouverte par la fenêtre vient en premier ; les
  bases de données [attachées à côté](data-sources.md#attached-databases) la
  suivent, marquées `read-only` lorsqu'elles sont attachées de cette façon.

Les tables affichent un nombre de lignes estimé ; les vues non. Les entrées de colonne affichent les types de données DuckDB. La base de données système et les schémas `information_schema`, `pg_catalog` et `system` sont masqués.

Le champ de recherche au-dessus de l'arborescence (**Rechercher tables et colonnes**) ne garde que les lignes dont le nom contient ce que vous saisissez, sans tenir compte de la casse, ainsi que les lignes situées au-dessus. Une table dont le nom correspond conserve toutes ses colonnes ; une table conservée à cause d'une colonne correspondante s'ouvre pour l'afficher. Videz le champ pour retrouver toute l'arborescence.

### Bases de données {#databases}

La base de données ouverte vient en premier, puis chaque
[base de données attachée](data-sources.md#attached-databases) forme son propre
groupe, avec le nombre de tables à côté de son nom.

- Une base de données attachée s'affiche même lorsqu'elle est vide. La base de
  données ouverte est omise tant qu'elle n'a pas de tables, ce qui correspond au
  démarrage d'une session en mémoire.
- Une indication discrète à côté du nom signale **read-only**, ainsi que le type
  de fichier lorsqu'il ne s'agit pas de DuckDB (**sqlite**).
- Survolez le nom pour voir le chemin du fichier de la base de données.

Faites un clic droit sur une base de données pour en faire la base par défaut ou pour la détacher — voir [Menu contextuel](#right-click-menu).

Le bouton d'actualisation à côté des onglets (**Actualiser le schéma**) recharge le catalogue et la liste des fichiers enregistrés.

## Générer un SELECT

Tous les clics ci-dessous **remplacent tout le contenu** de l'onglet actif — ils
n'insèrent rien au niveau du curseur. Il en va de même lorsque vous cliquez sur
une entrée de l'historique. Enregistrez ce qui compte pour vous avant de cliquer
un peu partout.

Ces actions remplissent l'éditeur actif lorsqu'on clique :

| Clic | SQL généré |
| --- | --- |
| Le bouton de lecture d'une table | `SELECT * FROM db.schema.table LIMIT 100;` |
| La case à cocher d'une colonne, ou son nom | `SELECT col FROM db.schema.table LIMIT 100;` |
| D'autres colonnes de la même table | `SELECT a, b FROM db.schema.table LIMIT 100;` |
| Un objet S3 qui est un fichier de données | `SELECT * FROM 's3://bucket/key' LIMIT 100;` |

Chaque colonne, d'une table, d'une vue ou d'un fichier local, possède une case à
cocher. Cocher des colonnes, ou cliquer sur leur nom, ce qui les coche, construit
le `SELECT` à partir des colonnes cochées, dans l'ordre des colonnes de la table
et non dans l'ordre où vous les avez cochées. Décocher la dernière donne
`SELECT *`. Les cases cochées appartiennent à une seule table : cocher une
colonne d'une autre table repart de zéro là-bas.

Le SQL généré tient sur trois lignes (`SELECT …`, `FROM …`, `LIMIT 100;`). Les
noms de table sont écrits aussi courtement que la base de données et le schéma
par défaut actuels le permettent : `orders` pour une table du schéma par défaut,
`main.orders` pour un autre schéma de la même base de données, et
`database.schema.table` sinon. Après **Utiliser comme base par défaut** sur
`snap`, l'aperçu d'une de ses tables affiche `FROM orders`. Tant que la première
requête n'a pas été exécutée, les noms sont qualifiés en entier.

Un nom n'est mis entre guillemets doubles que s'il contient des caractères autres que des lettres, des chiffres et des traits de soulignement.

## Menu contextuel {#right-click-menu}

Chaque commande proposée par les boutons au survol d'une ligne figure aussi dans son menu contextuel, ce qui vous permet de la trouver sans survoler :

| Ligne | Menu |
| --- | --- |
| Table ou vue | Générer une requête SELECT, Aperçu des colonnes, Copier le nom, Copier les infos de la table |
| Colonne | Générer une requête SELECT, Copier le nom, Changer le type de données… (colonnes de table uniquement) |
| Base de données attachée | Utiliser comme base par défaut, Détacher la base de données |
| Liste des buckets S3 | Actualiser les buckets |
| Tableau de bord récent | Retirer de la liste |
| Fichier local | Générer une requête SELECT, Aperçu des colonnes, Copier le nom, Copier les infos de la table, Retirer des fichiers locaux |

**Copier le nom** copie le nom brut — le nom de la table, de la colonne ou de la
vue seul, sans qualification par sa base de données et son schéma, et sans
guillemets.

**Copier les infos de la table** copie toute la table en Markdown, prête à coller dans une conversation, un ticket ou l'invite d'un agent IA — le nom qu'utilise une requête, sa nature, sa taille, et chaque colonne avec son type :

```md
memory.main.orders (table, ~224 rows, 3 columns)

| column | type |
|---|---|
| date | DATE |
| channel | VARCHAR |
| revenue | DOUBLE |
```

**Aperçu des colonnes** remplace le texte de l'éditeur actif par `FROM <table>;`,
l'exécute et ouvre le panneau de résultats sur son onglet **Aperçu**, qui résume
chaque colonne de la table entière : valeurs nulles, valeurs distinctes, plage et
un petit graphique de ses valeurs. Voir [Aperçu des colonnes](results-and-charts.md#overview).

**Utiliser comme base par défaut** exécute `USE` sur cette base de données, de
sorte que les noms de table sans base de données s'y résolvent, et les requêtes
générées raccourcissent (voir ci-dessus). L'action n'est pas proposée sur la base
de données déjà par défaut.

**Détacher la base de données** détache une base de données attachée et l'oublie,
de sorte qu'elle ne sera pas rattachée la fois suivante. S'il s'agissait de la
base par défaut, la session bascule d'abord vers une autre base de données. Le
fichier n'est pas touché. La base de données ouverte elle-même ne peut pas être
détachée : son menu ne comporte donc pas cet élément. Pour en savoir plus, voir
[Bases de données attachées](data-sources.md#attached-databases).

## Modifier le type d'une colonne

Une ligne de colonne propose une action de type (indisponible sur les colonnes de
vue ; les colonnes CSV et Parquet attachées ne peuvent donc pas changer de type).
Elle ouvre une boîte de dialogue en texte libre, pré-remplie avec le type actuel,
et exécute :

```sql
ALTER TABLE db.schema.table ALTER COLUMN col SET DATA TYPE <what you typed>
```

Ici, le nom de la table est toujours qualifié en entier, et le nom de la colonne
n'est mis entre guillemets que lorsque c'est nécessaire.

Il n'y a ni sélecteur ni liste de validation — toute chaîne de type DuckDB
fonctionne, y compris les types paramétrés comme `DECIMAL(10,2)`. Un type
invalide revient sous forme de notification d'erreur. En cas de succès, le
catalogue est rechargé.

Renommer et supprimer des colonnes, ainsi que modifier les commentaires de colonne, ne sont pas disponibles.

## Retirer un fichier enregistré

Le **×** d'une ligne de fichier demande une confirmation, puis supprime la vue et
oublie l'enregistrement. **Le fichier sur le disque n'est pas touché.**

Pour retirer plusieurs enregistrements d'un coup, sélectionnez leurs lignes sous **Fichiers locaux** :

- **⌘-clic** sur macOS ou **Ctrl-clic** sur Windows/Linux ajoute ou retire un fichier de la sélection.
- **Maj-clic** sélectionne une plage consécutive.
- Cliquez sur **×** d'un fichier sélectionné, ou utilisez son action de retrait dans le menu contextuel, pour confirmer la suppression des enregistrements sélectionnés. Le menu indique combien de fichiers seront retirés.

Cela supprime les vues et les enregistrements, en laissant les fichiers d'origine sur le disque. Sélectionner des fichiers de cette façon ne sélectionne ni tables de base de données ni filtres de tableau de bord.

## Extensions {#extensions}

L'onglet **Extensions** liste toutes les extensions DuckDB connues du moteur :
d'abord celles chargées, puis celles installées, puis les autres, chaque groupe
étant trié par nom.

Chaque ligne affiche :

- le nom de l'extension et une étiquette d'état : **Chargée**, **Installée** ou
  **Non installée** ;
- la description en une ligne fournie par DuckDB ;
- sa version et sa provenance : **intégrée**, ou le dépôt depuis lequel elle a été
  installée (`core`, `community`, ou une URL).

Ce que signifient les états :

| État | Signification |
| --- | --- |
| Chargée | Active dans la connexion actuelle : ses fonctions, lecteurs et types fonctionnent dès maintenant dans les requêtes |
| Installée | Téléchargée sur cette machine, mais non chargée dans cette connexion |
| Non installée | Connue de DuckDB, mais pas encore présente sur cette machine |

Les extensions **intégrées** sont compilées dans DuckLocal — `parquet` et `json`
entre autres, toutes deux chargées dès le départ. Elles ne sont jamais installées
ni mises à jour.

Les extensions communautaires s'installent de la même façon. Depuis la 0.4.1,
l'onglet atteint le dépôt communautaire de DuckDB en plus du dépôt principal, si
bien qu'une extension comme `mssql` (SQL Server) peut être installée et chargée
sans quitter l'application ; l'étiquette de dépôt de la ligne indique
`community`.

Une ligne propose les actions qui la concernent :

| Bouton | Affiché quand | Exécute |
| --- | --- | --- |
| **Installer** | Non installée | `INSTALL name` |
| **Charger** | Installée, non chargée | `LOAD name` |
| **Mettre à jour** | Installée depuis un dépôt | `UPDATE EXTENSIONS (name)` |

- **Installer** et **Mettre à jour** téléchargent depuis le dépôt d'extensions de
  DuckDB et nécessitent donc le réseau. **Charger** lit le fichier installé et ne
  le nécessite pas.
- Installer ne charge pas. Cliquez ensuite sur **Charger**, ou exécutez `LOAD name`.
- Une extension installée reste installée : c'est un fichier sur le disque, dans
  le dossier d'extensions propre à DuckDB. Le chargement ne dure que pour la
  connexion actuelle.
- Ce dossier est propre à chaque version de DuckDB (`~/.duckdb/extensions/v2.0.0/…`).
  Lorsqu'une mise à jour fait passer DuckLocal à une nouvelle version de DuckDB,
  comme la 0.3.0 avec DuckDB 2.0, les extensions que vous aviez apparaissent comme
  **Non installées** jusqu'à ce que vous les installiez à nouveau.
- Une seule action s'exécute à la fois ; les autres boutons sont désactivés
  entre-temps. Une notification indique *Installé …*, *Chargé …* ou *Mis à
  jour …*, ou la raison de l'échec.
- Après un chargement ou une mise à jour, l'arborescence du schéma est rechargée,
  car une extension peut apporter des tables et des fonctions.

La liste est lue depuis `duckdb_extensions()` à chaque ouverture de l'onglet,
après chaque action, lorsque la connexion change pendant que l'onglet est ouvert,
et lorsque vous cliquez sur le bouton d'actualisation à côté des onglets
(**Actualiser les extensions**). Elle affiche donc aussi une extension chargée
autrement — par un `LOAD` saisi dans un onglet de requête, ou par DuckDB de
lui-même.

Depuis la v0.2.1, ni la fenêtre ni la CLI ne télécharge automatiquement une extension manquante lorsqu'une requête en a besoin. Installez-la explicitement dans **Extensions** ou avec `INSTALL name`. Les extensions déjà installées sur cette machine peuvent toujours se charger automatiquement.

### Ouvrir l'interface DuckDB {#duckdb-ui}

L'[interface DuckDB](https://duckdb.org/2025/03/12/duckdb-ui) — le notebook dans le
navigateur de DuckDB, conçu par MotherDuck — est une extension comme une autre :
elle fonctionne donc aussi dans DuckLocal :

1. Dans l'onglet **Extensions**, cliquez sur **Installer** sur la ligne `ui`, puis sur **Charger**.
2. Dans un onglet de requête, exécutez :

   ```sql
   CALL start_ui();
   ```

   Votre navigateur ouvre l'interface à `http://localhost:4213`. Pour démarrer le
   serveur sans ouvrir de navigateur, exécutez plutôt `CALL start_ui_server();`.

![L'onglet Extensions avec l'extension ui chargée](../assets/duckdb-ui.png)

L'interface s'exécute sur l'instance DuckDB depuis laquelle elle a été démarrée,
ici celle de DuckLocal. Quelques points à connaître :

- **Elle a besoin du réseau.** Installer `ui` la télécharge, comme toute extension.
  Et à chaque démarrage, le serveur local de l'extension récupère les fichiers de
  l'interface depuis `https://ui.duckdb.org`. Vos requêtes et vos données restent
  exécutées localement.
- **Elle vit aussi longtemps que DuckLocal.** Quitter DuckLocal ferme son instance
  DuckDB, et le serveur avec elle. `CALL stop_ui_server();` l'arrête plus tôt.
- **Les notebooks sont enregistrés par l'extension, pas par DuckLocal,** dans
  `~/.duckdb/extension_data/ui/`. L'historique des requêtes de DuckLocal n'inclut
  pas ce que vous exécutez dans l'interface.
- **Elle ne peut pas s'exécuter directement sur une base de données en lecture
  seule.** Attachez plutôt cette base de données depuis un notebook avec
  `ATTACH '…' (READ_ONLY)`.

[DuckDB UI vs DuckLocal](https://ducklocal.app/blog/duckdb-ui-vs-ducklocal/)
compare les deux et explique quand utiliser l'une ou l'autre.

## Historique des requêtes {#query-history}

Chaque exécution est enregistrée — réussies comme échouées — avec un horodatage
en heure locale, une durée en millisecondes, un nombre de lignes (ou de lignes
affectées pour un DML) et le texte de l'erreur en cas d'échec. Les entrées
échouées apparaissent en rouge avec une étiquette *Échec*.

La liste affiche les **200** entrées les plus récentes. Cliquer sur une ligne
recharge l'éditeur actif avec ce SQL et lui donne le focus, en remplaçant ce qui
s'y trouvait.

Il n'y a ni politique de rétention ni purge : la table d'historique croît sans
limite et l'interface se contente d'afficher les 200 entrées les plus récentes. Il
n'y a pas non plus de recherche, de filtre, d'export, ni de moyen de supprimer une
entrée depuis l'interface.

L'historique est stocké dans le fichier de base de données propre à DuckLocal, et
non dans la base de données que vous avez ouverte : il survit donc au changement
de base de données et à la perte de votre espace de travail. Voir
[Paramètres et données de l'application](settings-and-data.md) pour savoir où il
se trouve.
