Aller au contenu

Sources de données ​

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 pour un chemin concis des fichiers au SQL, aux graphiques et à l'export.

Façons d'ouvrir des données ​

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

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.

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 ​

Les extensions sont reconnues sans tenir compte de la casse.

ExtensionComment c'est lu
.csv, .tsv, .txtvue read_csv_auto
.parquetvue read_parquet
.json, .ndjson, .jsonlvue read_json_auto
.xlsx, .xls, .xlsb, .odsimporté 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.

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 ​

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 ​

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 ​

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é.

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). 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 ​

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 fichierCe que DuckLocal vous dit
Un fichier DuckDB écrit par un DuckDB plus récent que celui intégré à DuckLocalLes 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érieurExécutez EXPORT DATABASE 'dir' avec le DuckDB qui l'a écrit, puis IMPORT DATABASE 'dir' dans DuckLocal
Une base SQLiteCe n'est pas un fichier DuckDB ; attachez-la plutôt — avec Attacher une base…, ou INSTALL sqlite; ATTACH '…' (TYPE sqlite);
Autre chose qui n'est pas un fichier DuckDBOuvrez 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.

Quel DuckDB peut lire une base ​

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 ​

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 ​

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.

Conservées d'une connexion à l'autre ​

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 ​

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

FichierDouble-clicOuvrir avec, ou déposer sur l'icône du Dock
.parquetS'ouvre dans DuckLocalOui
.duckdb, .ddbS'ouvre dans DuckLocalOui
.dashS'ouvre dans DuckLocalOui
.csv, .tsv, .json, .jsonl, .ndjson, .xlsx, .xlsReste 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. 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 ​

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.

FichierCe que l'aperçu montre
.parquetColonnes 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, .ddbLe 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, .tsvLes colonnes avec leurs types déduits, et les 50 premières lignes — un tableau au lieu du texte brut
.jsonl, .ndjsonLes 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 ​

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 ​

  • 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 ​

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é ​

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 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 pour les emplacements sur disque.

Publié sous licence Apache-2.0.