# Sources de données

> Interrogez CSV, Parquet, JSON et Excel avec DuckDB SQL : dossiers et motifs glob, bases attachées, et les données restent sur votre ordinateur.

Source: https://ducklocal.app/docs/fr/data-sources

DuckLocal transforme les fichiers en vues dans une connexion DuckDB en mémoire, ou
dans un fichier de base si vous en avez ouvert un. D'autres bases peuvent être
attachées à côté. Il n'y a rien à configurer. Voir le
[parcours d'analyse de données locales](https://ducklocal.app/use-cases/local-data-analysis/) pour un chemin concis des fichiers au SQL, aux graphiques et à l'export.

## Façons d'ouvrir des données {#ways-to-open-data}

Toutes passent par les mêmes règles de résolution :

1. Des chemins en ligne de commande — `ducklocal ./logs/ billing.parquet`
2. Le menu **Ouvrir** de la barre de titre : **Ouvrir des fichiers**, **Ouvrir un
   dossier** ou **Saisir un chemin ou un motif glob**, qui ouvre la boîte de
   dialogue **Ouvrir des données** pour un chemin saisi ou choisi dans le
   sélecteur natif
3. Le glisser-déposer de fichiers ou de dossiers n'importe où sur la fenêtre
4. Sur un Mac, les fichiers que Finder confie à DuckLocal — voir
   [Ouvrir depuis Finder](#open-from-finder)

Pour ajouter une base à côté de celle qui est ouverte plutôt que de la remplacer,
utilisez **Ouvrir → Attacher une base…** — voir [Bases attachées](#attached-databases).

Sous macOS, vous pouvez double-cliquer sur des fichiers Parquet et DuckDB dans
Finder pour les ouvrir, ou appuyer sur la barre d'espace pour prévisualiser les
premières lignes de fichiers Parquet, DuckDB, CSV, TSV et JSON Lines avec Quick
Look, sans lancer DuckLocal.

## Formats de fichiers pris en charge {#supported-file-formats}

Les extensions sont reconnues sans tenir compte de la casse.

| Extension | Comment c'est lu |
| --- | --- |
| `.csv`, `.tsv`, `.txt` | vue `read_csv_auto` |
| `.parquet` | vue `read_parquet` |
| `.json`, `.ndjson`, `.jsonl` | vue `read_json_auto` |
| `.xlsx`, `.xls`, `.xlsb`, `.ods` | importé comme une table par feuille |

Un fichier texte compressé en gzip, comme `.json.gz` ou `.csv.gz`, compte aussi
comme fichier de données, dans les blocs `schema`, `source` et lors de
l'attachement d'un fichier ; `logs.json.gz` devient une vue nommée `logs`. Avant 0.4.0,
`ducklocal schema` essayait un tel fichier comme une base ; sur une version plus
ancienne, lisez-le en SQL avec `read_json` ou `read_csv`.

Tout le reste n'est pas un fichier de données — voir [Fichiers de base](#database-files).

Un classeur est le seul format qui devient des **tables** et non des vues, et il
importe **toutes les feuilles** : la première feuille prend le radical du fichier
(le nom du fichier sans son extension) comme nom, les autres s'appellent
`{stem}_{sheet name}`. Une feuille vide est ignorée. Les types de colonnes sont
déduits des cellules — les entiers deviennent `BIGINT`, un mélange d'entiers et
de flottants `DOUBLE`, les dates `TIMESTAMP`, et tout contenu mixte ou non
reconnu `VARCHAR` ; les cellules vides sont importées comme `NULL`.

## Dossiers et motifs {#folders-and-patterns}

Un **dossier** est parcouru récursivement, et chaque fichier de données qu'il
contient devient une vue. Deux règles s'appliquent à ce parcours :

- Les entrées cachées (noms commençant par `.`) sont ignorées, et leur
  arborescence n'est pas parcourue.
- Les liens symboliques ne sont pas suivis. Suivre un lien qui remonte
  l'arborescence ne se terminerait jamais, et le dossier ciblé est normalement
  parcouru là où il se trouve réellement.

Les fichiers sont attachés dans l'ordre trié, si bien qu'un même dossier produit
toujours le même espace de travail.

Un **motif** peut contenir `*` (n'importe quelle suite de caractères) et `?`
(exactement un). La correspondance est évaluée pour chaque composant du chemin,
sur le système de fichiers, si bien qu'un motif peut couvrir plusieurs dossiers :

```bash
ducklocal './data/2026-0*/*.parquet'
```

Il n'y a pas de caractère d'échappement. `**` n'est pas spécial — il se comporte
comme un seul `*` et ne récurse pas. Un motif qui correspond à un dossier
l'ignore ; seuls les fichiers sont attachés. Les entrées cachées sont ignorées
ici aussi.

Les motifs sans guillemets sont développés par votre shell avant que DuckLocal
ne les voie. Ce n'est pas un problème. Ne mettez un motif entre guillemets que lorsque vous
voulez que DuckLocal le développe — par exemple quand le shell ne trouve aucune
correspondance et échouerait sinon.

## Plusieurs fichiers CSV à la fois {#many-csv-files-at-once}

Chaque fichier que DuckLocal attache devient sa propre vue avec son propre schéma
déduit, si bien que deux CSV qui divergent ne se cassent jamais l'un l'autre. Les
pièges apparaissent quand une seule lecture SQL couvre plusieurs fichiers :

```sql
SELECT * FROM read_csv('data/*.csv', union_by_name = true)
```

- **La détection des types peut diverger d'un fichier à l'autre.** Le lecteur
  déduit le type d'une colonne à partir d'un échantillon ; une colonne numérique
  partout mais qui contient une chaîne `'NULL'` parasite dans un fichier fait
  échouer toute la lecture avec une erreur de conversion, et un cast dans la
  liste `SELECT` arrive trop tard — la lecture elle-même échoue. Lisez plutôt
  chaque colonne en texte et castez en SQL :

  ```sql
  SELECT try_cast(amount AS DOUBLE) AS amount
  FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)
  ```

  `union_by_name = true` tolère aussi les fichiers dont les ensembles de colonnes
  diffèrent.
- **La chaîne `'NULL'` n'est pas `NULL`.** Un `'NULL'` littéral (ou `'N/A'`,
  `'null'`) dans un CSV est du texte ordinaire, donc `WHERE amount IS NOT NULL`
  ne le filtre pas. Utilisez `NULLIF(amount, 'NULL')`, ou `WHERE amount <> 'NULL'`.

Les deux correctifs se combinent : `try_cast(NULLIF(amount, 'NULL') AS DOUBLE)`.

## Fichiers de base {#database-files}

DuckLocal n'a qu'une **base principale** à la fois : en mémoire, ou un fichier
DuckDB que vous avez ouvert. Les fichiers de données deviennent des vues dans la
base principale. Vous pouvez aussi
[attacher d'autres bases à côté](#attached-databases).

Tout chemin qui **existe** et n'est pas un fichier de données est ouvert comme
base principale au lieu d'être attaché comme vue. L'extension n'a pas
d'importance : un chemin `.db`, `.duckdb` ou même `.md` est traité comme une base,
et DuckDB décide s'il peut réellement être ouvert.

Quelques conséquences méritent d'être connues :

- **Une nouvelle base ne peut être créée que depuis la boîte de dialogue Ouvrir
  des données.** Saisissez un chemin qui se termine par `.duckdb` et qui n'existe
  pas encore : DuckLocal crée la base, ainsi que les dossiers parents manquants.
  Partout ailleurs — ligne de commande, sélecteurs, glisser-déposer, Finder — un
  chemin inexistant est signalé comme `File not found`.
- **Ouvrir une base remplace la base principale.** Vos fichiers enregistrés et vos
  bases attachées sont attachés de nouveau dans la nouvelle connexion. Les
  identifiants S3 ne le sont pas ; reconfigurez S3.
- **Si le fichier ne peut pas être ouvert**, DuckLocal vous dit pourquoi
  ([ci-dessous](#when-a-database-will-not-open)). Au lancement, il bascule sur un
  espace de travail en mémoire plutôt que d'échouer au démarrage. Pendant qu'il
  tourne, l'espace de travail que vous aviez reste tel quel.
- **Un fichier déjà attaché** à côté de la base principale est d'abord détaché,
  puis ouvert comme base principale. Si cette ouverture échoue, l'attachement est
  rétabli. Ouvrir le fichier qui est déjà la base principale le réutilise.

Attacher des fichiers de données quand un fichier de base est ouvert **écrit ces
vues dans ce fichier de base** — elles y persistent, pas seulement dans la
session.

### Quand une base ne s'ouvre pas {#when-a-database-will-not-open}

Quand DuckDB refuse un fichier, DuckLocal lit lui-même les premiers octets du
fichier et, lorsqu'ils expliquent l'échec, place une raison et une solution
au-dessus du message de DuckDB. Le message de DuckDB reste en dessous pour
l'erreur exacte. L'explication est dans la langue de l'interface.

| Ce qu'est le fichier | Ce que DuckLocal vous dit |
| --- | --- |
| Un fichier DuckDB écrit par un **DuckDB plus récent** que celui intégré à DuckLocal | Les deux versions, et le SQL à exécuter dans le DuckDB plus récent qui copie le fichier dans un format que DuckLocal lit (ci-dessous) |
| Un fichier DuckDB de **v0.9 ou antérieur** | Exécutez `EXPORT DATABASE 'dir'` avec le DuckDB qui l'a écrit, puis `IMPORT DATABASE 'dir'` dans DuckLocal |
| Une base **SQLite** | Ce n'est pas un fichier DuckDB ; attachez-la plutôt — avec [Attacher une base…](#attached-databases), ou `INSTALL sqlite; ATTACH '…' (TYPE sqlite);` |
| Autre chose qui **n'est pas un fichier DuckDB** | Ouvrez plutôt des fichiers CSV, Parquet, JSON ou Excel comme fichiers de données |

Pour un fichier venant d'un DuckDB plus récent, le message renseigne le chemin du
fichier et la version de DuckDB de DuckLocal. Exécutez-le dans le DuckDB qui a
créé le fichier, puis ouvrez `compat.duckdb` :

```sql
ATTACH '/path/to/file.duckdb' AS src (READ_ONLY);
ATTACH 'compat.duckdb' AS dst (STORAGE_VERSION 'v2.0.0');
COPY FROM DATABASE src TO dst;
```

Les fichiers écrits avant DuckDB v1.2 n'enregistrent pas la version qui les a
créés. Toute autre défaillance — un fichier verrouillé par un autre programme, un
fichier que vous n'avez pas le droit de lire — n'affiche que le message de
DuckDB. Voir [Dépannage](troubleshooting.md#opening-a-database).

### Quel DuckDB peut lire une base {#storage-version}

Quand un fichier de base est ouvert, la barre d'état affiche son chemin. Survolez-le
pour voir le format de stockage du fichier — la plus ancienne version de DuckDB
capable de le lire, par exemple **Format de stockage : lisible par DuckDB v1.0.0+** — et,
lorsque le fichier l'enregistre, la version qui l'a créé (**Créé par DuckDB
v1.4.3**). Vérifiez-le avant de confier un fichier à quelqu'un qui utilise un
DuckDB plus ancien.

DuckLocal utilise DuckDB 2.0, mais un fichier de base qu'il crée est écrit dans
le format qu'écrivait DuckDB 1.x (**lisible par DuckDB v1.0.0+**), si bien que la
CLI duckdb, Python ou DBeaver sous DuckDB 1.x l'ouvrent encore. Un fichier écrit
par un autre programme au format propre de DuckDB 2.0 (**v2.0.0+**) s'ouvre aussi,
et conserve ce format : 1.x ne peut pas le lire.

## Bases attachées {#attached-databases}

Attachez un autre fichier DuckDB ou SQLite à côté de la base principale pour
interroger les deux ensemble — un instantané à côté des données du jour, par
exemple.

1. Ouvrez le menu **Ouvrir** de la barre de titre et choisissez **Attacher une base…**.
2. Saisissez le chemin, ou cliquez sur **Parcourir** pour choisir le fichier.
3. Laissez **Lecture seule** cochée, sauf si vous voulez modifier le fichier.
   Elle est cochée par défaut.
4. Cliquez sur **Attacher**.

La base reçoit un **alias** dérivé de son nom de fichier, et vous interrogez ses
tables en `alias.table` (ou `alias.schema.table`) :

```sql
-- snap-2026-10-01.duckdb attached as snap_2026_10_01
SELECT t.id, t.amount, s.amount AS amount_last_week
FROM orders t
JOIN snap_2026_10_01.orders s USING (id);
```

Comment l'alias est formé :

- Le radical du fichier, avec chaque caractère qui n'est pas une lettre ou un
  chiffre ASCII remplacé par `_`.
- Le préfixe `db_` quand il ne commence pas par une lettre :
  `2026-10 logs.duckdb` devient `db_2026_10_logs`.
- Un compteur quand le nom est déjà pris : `snap`, puis `snap_2`. `main` n'est
  jamais utilisé.
- Attacher de nouveau un fichier plus tard lui rend l'alias qu'il avait, si bien
  que le SQL écrit pour lui continue de fonctionner.

Détails :

- Les **fichiers SQLite** sont reconnus à leur contenu et attachés via
  l'extension `sqlite` de DuckDB.
- **Décocher Lecture seule** attache le fichier en écriture. Un chemin DuckDB
  qui n'existe pas est alors créé comme une nouvelle base vide ; en lecture
  seule, l'attachement échoue à la place.
- **Le même fichier n'est jamais attaché deux fois.** Attacher un fichier déjà
  ouvert — comme base principale ou comme attachement — affiche
  *Cette base est déjà ouverte, en tant que …*.

### Dans la barre latérale {#in-the-sidebar}

Chaque base apparaît dans l'arborescence du schéma, la principale comme les bases
attachées, y compris les bases vides. Une base affiche **read-only** ou **sqlite**
à côté de son nom le cas échéant, et son fichier en infobulle.

Faites un clic droit sur une base pour :

- **Utiliser comme base par défaut** — exécute `USE`, si bien que les noms de
  tables sans base se résolvent là. La barre d'état indique où ils se résolvent
  désormais.
- **Détacher la base** — la détache et l'oublie, si bien qu'elle ne revient pas la
  fois suivante. Si c'était la base par défaut, la session revient d'abord à la
  base principale. Le fichier lui-même n'est pas touché.

Le reste de ce menu est décrit dans
[Schéma et historique](schema-and-history.md).

### Conservées d'une connexion à l'autre {#kept-across-connections}

Les bases attachées sont stockées dans la base d'historique de DuckLocal, avec
leur alias et leur réglage en lecture seule, et attachées de nouveau dans chaque
nouvelle connexion : au prochain lancement, après l'ouverture d'une autre base, et
après **Nouvelle base en mémoire**.

- Une base dont le fichier est **introuvable** est ignorée en silence. Son
  enregistrement est conservé, si bien qu'elle revient dès que le fichier est là
  — DuckLocal ne crée jamais une base vide à sa place.
- Une base **déjà ouverte**, comme base principale ou autrement, n'est pas
  attachée une seconde fois.
- Si la nouvelle base principale possède déjà une base sous cet alias, DuckLocal
  affiche *Impossible d'attacher … : le nom … est déjà pris dans la base ouverte.*

## Ouvrir depuis Finder {#open-from-finder}

Sur un Mac, Finder peut confier des fichiers directement à DuckLocal :

| Fichier | Double-clic | Ouvrir avec, ou déposer sur l'icône du Dock |
| --- | --- | --- |
| `.parquet` | S'ouvre dans DuckLocal | Oui |
| `.duckdb`, `.ddb` | S'ouvre dans DuckLocal | Oui |
| `.dash` | S'ouvre dans DuckLocal | Oui |
| `.csv`, `.tsv`, `.json`, `.jsonl`, `.ndjson`, `.xlsx`, `.xls` | Reste avec l'app qui les ouvre déjà (Numbers, Excel, un éditeur de texte) | Oui |

DuckLocal ne s'enregistre comme application par défaut que pour les formats que
rien d'autre sur un Mac ne revendique. Si une autre app a déjà pris en charge les
fichiers Parquet ou DuckDB, choisissez DuckLocal dans **Ouvrir avec** — ou
utilisez **Obtenir des informations → Ouvrir avec → Tout modifier…** de Finder
pour en faire l'application par défaut.

Un fichier venant de Finder est traité exactement comme un glisser-déposer sur la
fenêtre : un fichier de données devient une vue dans l'espace de travail courant, un fichier
de base est ouvert comme base principale, et un fichier `.dash` s'ouvre dans un
onglet de [tableau de bord](dashboards.md). Si DuckLocal n'est pas lancé, il
démarre d'abord et ouvre le fichier une fois son propre démarrage terminé.

## Aperçus Quick Look {#quick-look}

Sur un Mac, sélectionnez un fichier de données dans Finder et appuyez sur
**Espace** pour voir ses colonnes et ses premières lignes sans rien ouvrir.
L'aperçu est livré dans DuckLocal.app ; il n'y a rien à installer séparément. Il
nécessite macOS 12 ou ultérieur, comme l'app.

| Fichier | Ce que l'aperçu montre |
| --- | --- |
| `.parquet` | Colonnes et types, les 50 premières lignes, et depuis le pied du fichier : nombre de lignes, groupes de lignes, compression et l'outil d'écriture |
| `.duckdb`, `.ddb` | Le nombre de tables, le format de stockage (**Lisible par DuckDB …**), et les cinq plus grandes tables, chacune avec son nombre de lignes estimé et ses 50 premières lignes |
| `.csv`, `.tsv` | Les colonnes avec leurs types déduits, et les 50 premières lignes — un tableau au lieu du texte brut |
| `.jsonl`, `.ndjson` | Les colonnes et les 50 premières lignes |

Les fichiers `.json` simples et les fichiers Excel sont laissés aux aperçus de
macOS.

Ce que l'aperçu fait et ne fait pas :

- Il n'écrit jamais. Une base est attachée en lecture seule.
- Il ne parcourt jamais un fichier entier : les lignes sont un `LIMIT`, et un
  nombre de lignes n'apparaît que là où le format en stocke un (le pied d'un
  Parquet, une estimation de base).
- Il ne télécharge rien : les extensions DuckDB ne sont ni installées ni chargées.
- Les cellules de plus de 200 caractères sont tronquées. Le texte de la page est
  en anglais.
- Un fichier qu'il ne peut pas lire obtient une page qui en explique la raison.

Si appuyer sur Espace n'affiche aucun aperçu DuckLocal :

1. Vérifiez que DuckLocal est dans **Applications**, et lancez-le une fois. macOS
   enregistre l'aperçu la première fois qu'il voit l'app.
2. Réinitialisez Quick Look dans Terminal : `qlmanage -r`. Réessayez ensuite.
3. Vérifiez que **DuckLocal Preview** est activé dans Quick Look, dans les
   réglages d'extensions des Réglages Système.

## Nommage {#naming}

La vue d'un fichier porte le nom de son radical, nettoyé en un identifiant
valide. Quand ce nom est déjà pris dans la connexion, DuckLocal ajoute un
compteur : `events`, puis `events_2`, `events_3`. Deux fichiers de même radical
dans des dossiers différents obtiennent donc des vues distinctes.

La détection des doublons se fait sur le texte du chemin tel qu'il est écrit,
donc `./a.csv` et `a.csv` sont traités comme deux fichiers différents.

## Limites {#limits}

- **256 fichiers de données par demande d'ouverture.** Le plafond couvre
  l'ensemble des chemins d'une même demande, et non chaque dossier séparément — il existe
  pour qu'un glisser-déposer accidentel d'un dossier personnel n'immobilise pas la
  connexion pendant des minutes. Quand le plafond est atteint, DuckLocal le
  signale et attache les 256 premiers fichiers.
- Les fichiers rattachés au démarrage depuis la session précédente ne sont pas
  soumis à ce plafond.

## Gérer les sources enregistrées {#managing-registered-sources}

Les fichiers enregistrés apparaissent dans le groupe **Fichiers locaux** de la
barre latérale, chacun avec son nom de vue, son nom de fichier et son nombre de
lignes. Sélectionner un fichier génère une instruction `SELECT` pour lui.

Le **×** sur une ligne de fichier le retire, après une boîte de dialogue de
confirmation. Le retrait supprime la vue et oublie l'enregistrement ; **le
fichier sous-jacent n'est pas touché.**

**Actualiser le schéma** recharge le catalogue et les fichiers enregistrés.

## Ce qui est mémorisé {#what-is-remembered}

La liste des fichiers enregistrés — leurs chemins, noms de vue et types — est
stockée dans la base d'historique de DuckLocal et rechargée au prochain
lancement, si bien que l'espace de travail que vous avez quitté est celui que
vous retrouvez. Les [bases attachées](#kept-across-connections) aussi. Le fichier
de base principal n'est *pas* mémorisé : chaque lancement démarre en mémoire,
sauf si vous nommez une base.

Voir [Paramètres et données de l'app](settings-and-data.md) pour les emplacements
sur disque.
