Aller au contenu

Dépannage ​

Trouvez le symptôme, lisez la cause, appliquez le correctif. Si votre problème n'est pas listé, ouvrez un ticket avec le détail de ce que vous avez fait et de ce qui s'est passé.

Installation et lancement ​

SymptômeCause et correctif
L'application ne s'ouvre pas sur un Mac IntelLa version macOS est compilée pour Apple silicon uniquement. Compilez depuis les sources sur Intel
Les raccourcis de cette documentation ne font rien sous Windows ou LinuxLisez Ctrl à la place de ⌘ : ⌘↵ correspond à Ctrl+Enter
ducklocal: command not foundL'image disque installe l'application, pas une commande. Liez le binaire dans votre PATH
Le terminal reste occupé tant que la fenêtre est ouverteLancer l'interface graphique depuis un terminal l'exécute au premier plan. Lancez-la plutôt depuis Applications, ou laissez ce terminal s'en occuper
L'historique, les paramètres ou les fichiers mémorisés cessent d'être enregistrésUn second DuckLocal est en cours d'exécution et garde le fichier de données de l'application. Quittez l'autre et relancez
DuckLocal s'est arrêté de façon inattendue la dernière foisIl a planté et enregistré un rapport dans le dossier des journaux. Cliquez sur Afficher le rapport et joignez-le à un ticket — voir où les données sont stockées
Échec de la recherche de mise à jourSurvolez-la pour connaître la raison : hors ligne, un proxy, ou un téléchargement dont la somme de contrôle ne correspond pas. Cliquez pour réessayer, ou téléchargez la version depuis GitHub — voir Recherche de mise à jour

Ouverture des données ​

SymptômeCause et correctif
File not found sur un chemin que vous avez indiquéLe chemin n'existe pas, ou est relatif à un autre dossier que vous ne le pensez. Utilisez un chemin absolu pour être sûr
Un dossier ne signale aucun fichier de donnéesRien en dessous ne correspond à .csv, .tsv, .txt, .parquet, .json, .ndjson, .jsonl, .xlsx, .xls, .xlsb ou .ods
Un dossier a produit moins de fichiers que prévuLes entrées masquées et les liens symboliques sont ignorés, et une demande d'ouverture attache au plus 256 fichiers. Ouvrez les sous-dossiers séparément
Un chemin s'est ouvert comme base de données alors qu'il ne fallait pasTout fichier existant qui n'est pas un fichier de données est traité comme une base DuckDB. S'il ne s'ouvre pas, DuckLocal en donne la raison ; au lancement, il se rabat sur la mémoire. Voir Ouvrir une base de données
Non attaché … : la base de données contient déjà une table ou une vue nommée …La base contient déjà une table ou une vue du même nom que le fichier mémorisé. DuckLocal ne la remplace jamais. Renommez ou supprimez l'une des deux, ou retirez le fichier de Fichiers locaux et rouvrez-le pour obtenir un nouveau nom
Impossible de restaurer le chemin relatif …Un fichier a été mémorisé par un chemin relatif, qui ne peut pas être résolu dans une nouvelle session. Retirez-le de Fichiers locaux et rouvrez-le
Une vue affiche sales_2 au lieu de salesUn autre fichier ou une autre table portait déjà ce nom, la nouvelle vue a donc reçu un suffixe
La vue d'un fichier est obsolèteLes vues lisent le fichier à chaque requête. Si la forme des colonnes d'un CSV a changé, utilisez Actualiser le schéma dans la barre latérale

Ouvrir une base de données ​

SymptômeCause et correctif
Le message dit que la base a été créée par un DuckDB plus récentLe fichier utilise un format de stockage plus récent que ce que le DuckDB intégré à DuckLocal sait lire. Exécutez les lignes ATTACH … COPY FROM DATABASE du message dans le DuckDB qui a créé le fichier, puis ouvrez la copie. Voir Quand une base de données ne s'ouvre pas
Le message dit que la base vient de DuckDB v0.9 ou antérieurExécutez EXPORT DATABASE 'dir' avec le DuckDB qui l'a écrite, puis IMPORT DATABASE 'dir' dans DuckLocal
Le message dit qu'il s'agit d'une base SQLiteAttachez-la avec Ouvrir → Attacher une base de données… au lieu de l'ouvrir
Le message dit que le fichier n'est pas une base DuckDBSon extension n'est pas une de celles que DuckLocal lit comme données, il a donc été essayé comme base. Donnez-lui une extension prise en charge, ou lisez-le en SQL, par exemple SELECT * FROM read_csv('export.dat')
DuckDB dit qu'il n'a pas pu poser un verrou sur le fichierUn autre programme — un autre DuckDB, un script, une seconde application — a la base ouverte en écriture, et DuckDB ne laisse qu'un seul processus écrire dans un fichier. Fermez-la dans cet autre programme, puis rouvrez le fichier
DuckDB signale un accès refuséVotre compte ne peut pas lire le fichier, ou pas y écrire : la base principale est ouverte en écriture. Corrigez les permissions du fichier, ou attachez-le avec Lecture seule cochée
Une ouverture de base a échoué et rien n'a changéC'est attendu tant que DuckLocal est en cours d'exécution : une ouverture ratée laisse l'espace de travail que vous aviez. Lisez la notification pour connaître la raison
L'infobulle de la barre d'état indique lisible par DuckDB v1.x+ et un collègue ne peut pas ouvrir le fichierSon DuckDB est plus ancien que cette version. Il doit mettre à jour, ou vous copiez le fichier avec un STORAGE_VERSION plus ancien — voir Quel DuckDB peut lire une base de données

Bases de données attachées ​

SymptômeCause et correctif
Une base attachée a disparu après un relancementSon fichier n'était pas au chemin mémorisé au lancement, elle a donc été ignorée. L'enregistrement est conservé ; remettez le fichier en place et elle reviendra à la prochaine connexion
Cette base de données est déjà ouverte, sous le nom …Le fichier est déjà la base principale, ou est attaché sous ce nom. Interrogez-le par ce nom
Impossible d'attacher … : le nom … est déjà pris dans la base ouverte.Quelque chose d'autre dans la connexion utilise déjà l'alias mémorisé — par exemple une base que vous avez attachée en SQL sous le même nom. Détachez celle-là avec DETACH, puis rouvrez la base ou relancez
L'écriture dans une base attachée échoueElle a été attachée en lecture seule, le comportement par défaut. Utilisez Détacher la base de données dans la barre latérale, puis attachez-la à nouveau avec Lecture seule décochée
L'attachement a créé une base videAvec Lecture seule décochée, un chemin DuckDB qui n'existe pas est créé. Détachez-la, supprimez le fichier vide et vérifiez le chemin
Un nom de table sans base trouve la mauvaise tableLes noms sans base se résolvent dans la base par défaut. Faites un clic droit sur une base et choisissez Utiliser comme base par défaut, ou écrivez alias.table

Finder et Quick Look ​

Ces fonctions sont réservées à macOS.

SymptômeCause et correctif
Un double-clic sur un fichier .parquet ou .duckdb ouvre une autre applicationCette application est déjà celle par défaut. Dans le Finder, Lire les informations → Ouvrir avec, choisissez DuckLocal, puis Tout modifier…
Un double-clic sur un fichier CSV ou Excel n'ouvre pas DuckLocalC'est voulu : DuckLocal ne prend pas ces formats en charge. Utilisez Ouvrir avec → DuckLocal, ou déposez le fichier sur l'icône du Dock
DuckLocal n'est pas proposé dans Ouvrir avec, ou Espace n'affiche aucun aperçu DuckLocalmacOS n'a pas encore enregistré l'application. Déplacez-la dans Applications et lancez-la une fois. Pour l'aperçu, exécutez ensuite qlmanage -r dans le Terminal, et vérifiez que Aperçu DuckLocal est activé dans Quick Look, dans les réglages d'extensions des Réglages Système
Un fichier .json ordinaire ou un fichier Excel n'affiche aucun aperçu DuckLocalC'est voulu : ils sont laissés aux aperçus de macOS. Les fichiers .jsonl et .ndjson sont prévisualisés
L'aperçu n'affiche que 50 lignesC'est voulu : un aperçu ne parcourt jamais le fichier entier. Ouvrez le fichier dans DuckLocal pour le reste
L'aperçu d'un fichier .duckdb affiche une erreurL'aperçu lit le fichier avec le DuckDB de DuckLocal, un fichier issu d'un DuckDB plus récent échoue donc là aussi. Voir Ouvrir une base de données

Exécution des requêtes ​

SymptômeCause et correctif
Exécuter ne fait rienUne requête est déjà en cours. Cliquez sur Arrêter à côté d'Exécuter, ou sur ⌘., pour l'interrompre
Une requête a échoué avec InterruptedQuelqu'un a appuyé sur Arrêter (ou ⌘.) pendant son exécution. Relancez-la
Une partie de mon SQL est soulignée d'un trait ondulé rougeLa dernière exécution a échoué à cet endroit. Lisez le message Échec de la requête ; la marque disparaît à l'exécution suivante
⌘↵ affiche l'éditeur au lieu d'exécuterSur l'écran de premier lancement, ⌘↵ signifie « donnez-moi un éditeur ». Appuyez à nouveau pour exécuter
Les résultats s'arrêtent tôt avec un avis de troncatureLe plafond de 100 000 lignes ou de 2 000 000 de cellules a été atteint. Restreignez la requête ; il n'y a pas de pagination
Les horodatages semblent décalésLa grille affiche les horodatages en UTC, pas en heure locale
Une valeur TIMETZ a perdu son décalage, ou une valeur BIT ou BIGNUM ressemble à des octetsCes types ne peuvent pas être distingués des valeurs ordinaires à l'arrivée dans DuckLocal. CAST(column AS VARCHAR) en SQL affiche la vraie valeur
Le tri ne fait pas venir les lignes au-delà de l'aperçuLe tri par en-tête ne réordonne que les lignes chargées. Utilisez ORDER BY en SQL pour ordonner le résultat complet avant troncature
Une requête a besoin d'une extension non installéeLes extensions manquantes ne sont plus téléchargées automatiquement. Installez-la explicitement dans l'onglet Extensions, puis chargez-la ou relancez la requête
Une requête qui fonctionnait avant 0.3.0 dit qu'une extension n'est pas installée, ou qu'une fonction n'existe pasDuckLocal 0.3.0 exécute DuckDB 2.0, qui conserve les extensions installées par version. Installez-les à nouveau depuis l'onglet Extensions — voir Extensions
Un alias de colonne nu comme minutes provoque une erreur d'analyseurC'est un mot-clé SQL. Écrivez AS minutes, ou mettez-le entre guillemets : SELECT count(*) AS "minutes" FROM events
Cliquer sur une table ou une entrée d'historique a effacé mon SQLCes clics remplacent tout le contenu de l'éditeur. Utilisez un nouvel onglet de requête pour vos essais
Un export a remplacé un fichier sans prévenirL'export écrit au chemin indiqué sans demander. Choisissez un nouveau nom

S3 ​

SymptômeCause et correctif
Les identifiants S3 ont été oubliésIls ne durent que le temps de la session, c'est voulu, et ouvrir ou changer de base de données les efface. Reconfigurez S3
La configuration de S3 échoue hors ligneLe premier usage lance INSTALL httpfs, qui télécharge l'extension. Connectez-vous une fois, elle est ensuite en cache
Les identifiants temporaires (STS) sont refusésAucun jeton de session n'est envoyé. Utilisez des clés de longue durée — voir S3 et httpfs
Un bucket semble plus petit qu'il ne l'estLe listage s'arrête à 1 000 entrées par niveau. Interrogez plutôt avec un motif comme 's3://bucket/prefix/*.parquet'

Tableaux de bord ​

SymptômeCause et correctif
Un graphique de tableau de bord dit qu'une requête doit être en lecture seuleUne requête du .dash a tenté d'écrire (DDL, DML, COPY, ATTACH, …). Les tableaux de bord n'exécutent que des instructions en lecture seule ; déplacez la préparation dans l'éditeur SQL
Un agent n'a pas vu mes commentairesLes commentaires ne sont envoyés nulle part : l'agent doit les lire. Demandez-lui d'exécuter ducklocal comments FILE, ou de « traiter les commentaires de FILE » s'il a la compétence officielle
La réponse ou la modification d'un agent ne s'affiche pasLa fenêtre suit à la fois la spécification et FILE.comments.json en moins d'une seconde. Une spécification qui ne valide plus laisse le dernier tableau de bord fonctionnel affiché, avec la raison au-dessus ; ouvrez Voir la spécification pour voir le fichier
Un PIVOT dans un tableau de bord est refuséUn PIVOT imbriqué dans un SELECT ou un WITH doit nommer ses valeurs. Listez-les : PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue), ou commencez la requête par le PIVOT

Apparence ​

SymptômeCause et correctif
Le thème revient au clair à chaque lancementLe thème n'est pas enregistré entre les lancements ; la langue, elle, l'est
Le texte ou les icônes sont trop petits ou trop grandsUtilisez le bouton Aa de la barre de titre, ou ⌘+ / ⌘− / ⌘0. Voir Taille de l'interface
L'interface est dans la mauvaise langueUtilisez le bouton EN / 中 de la barre de titre ; le choix est mémorisé

Repartir de zéro ​

Pour effacer l'historique, les fichiers mémorisés, les onglets ouverts et les paramètres, quittez DuckLocal et supprimez son dossier de données d'application :

bash
rm -rf ~/Library/Application\ Support/DuckLocal

Vos fichiers de données ne sont jamais touchés — seuls les enregistrements propres à DuckLocal sont supprimés. Voir Paramètres et données de l'application pour savoir ce qui y est stocké.

Publié sous licence Apache-2.0.