Risoluzione dei problemi
Trova il sintomo, leggi la causa e applica la soluzione. Se il tuo problema non è elencato, apri una issue con i dettagli su cosa hai fatto e cosa è successo.
Installazione e avvio
| Sintomo | Causa e soluzione |
|---|---|
| L'app non si apre su un Mac Intel | La release per macOS è compilata solo per Apple silicon. Compila dai sorgenti su Intel |
| Le scorciatoie di questa documentazione non fanno nulla su Windows o Linux | Leggi Ctrl al posto di ⌘: ⌘↵ lì è Ctrl+Invio |
ducklocal: command not found | L'immagine disco installa l'app, non un comando. Collega il binario al tuo PATH |
| Il terminale resta occupato mentre la finestra è aperta | Aprire la GUI da un terminale la esegue in primo piano. Avviala invece da Applicazioni, oppure lascia quel terminale occupato dalla GUI |
| La cronologia, le impostazioni o i file ricordati smettono di essere salvati | Un secondo DuckLocal è in esecuzione e tiene il file dei dati dell'app. Chiudi l'altro e riavvia |
| DuckLocal è terminato in modo imprevisto l'ultima volta | È andato in crash e ha salvato un rapporto nella cartella dei log. Fai clic su Mostra rapporto e allega il rapporto a una issue — vedi dove sono memorizzate le cose |
| Controllo aggiornamenti non riuscito | Passa il mouse sopra per vedere il motivo: offline, un proxy, o un download che non corrispondeva al suo checksum. Fai clic per riprovare, oppure scarica la release da GitHub — vedi Controllo degli aggiornamenti |
Apertura dei dati
| Sintomo | Causa e soluzione |
|---|---|
File not found su un percorso che hai indicato | Il percorso non esiste, oppure è relativo a una directory diversa da quella che pensi. Usa un percorso assoluto per essere sicuro |
| Una cartella non segnala file di dati | Nulla al suo interno corrispondeva a .csv, .tsv, .txt, .parquet, .json, .ndjson, .jsonl, .xlsx, .xls, .xlsb o .ods |
| Una cartella ha prodotto meno file del previsto | Le voci nascoste e i symlink vengono saltati, e una richiesta di apertura collega al massimo 256 file. Apri le sottocartelle separatamente |
| Un percorso è stato aperto come database inaspettatamente | Qualsiasi file esistente che non è un file di dati viene trattato come database DuckDB. Se non si apre, DuckLocal dice perché; all'avvio ricade sulla memoria. Vedi Aprire un database |
| Non collegato …: il database ha già una tabella o una vista chiamata … | Il database contiene già una tabella o una vista con lo stesso nome del file ricordato. DuckLocal non la sostituisce mai. Rinomina o elimina una delle due, oppure rimuovi il file da File locali e riaprilo per ottenere un nuovo nome |
| Impossibile ripristinare il percorso relativo … | Un file era ricordato tramite un percorso relativo, che non si può risolvere in una nuova sessione. Rimuovilo da File locali e riaprilo |
Una vista mostra sales_2 invece di sales | Un altro file o una tabella aveva già quel nome, quindi la nuova ha ricevuto un suffisso |
| La vista di un file è obsoleta | Le viste leggono il file a ogni query. Se le colonne di un CSV hanno cambiato forma, usa Aggiorna schema nella barra laterale |
Aprire un database
| Sintomo | Causa e soluzione |
|---|---|
| Il messaggio dice che il database è stato creato da un DuckDB più recente | Il file usa un formato di archiviazione più recente di quello che il DuckDB integrato in DuckLocal sa leggere. Esegui le righe ATTACH … COPY FROM DATABASE del messaggio nel DuckDB che ha creato il file, poi apri la copia. Vedi Quando un database non si apre |
| Il messaggio dice che il database viene da DuckDB v0.9 o precedente | Esegui EXPORT DATABASE 'dir' con il DuckDB che l'ha scritto, poi IMPORT DATABASE 'dir' in DuckLocal |
| Il messaggio dice che è un database SQLite | Collegalo con Apri → Collega database… invece di aprirlo |
| Il messaggio dice che il file non è un database DuckDB | La sua estensione non è una di quelle che DuckLocal legge come dati, quindi è stato provato come database. Dagli un'estensione supportata, oppure leggilo in SQL, per esempio SELECT * FROM read_csv('export.dat') |
| DuckDB dice che non è riuscito a impostare un lock sul file | Un altro programma — un altro DuckDB, uno script, una seconda app — ha il database aperto in scrittura, e DuckDB lascia che un solo processo scriva un file. Chiudilo lì, poi apri di nuovo il file |
| DuckDB dice permesso negato | Il tuo account non può leggere il file, o non può scriverlo: il database principale viene aperto in scrittura. Sistema i permessi del file, oppure collegalo con Sola lettura selezionato |
| L'apertura di un database è fallita e nulla è cambiato | È previsto mentre DuckLocal è in esecuzione: un'apertura fallita lascia lo spazio di lavoro che avevi. Leggi la notifica per il motivo |
| Il tooltip della barra di stato dice leggibile da DuckDB v1.x+ e un collega non riesce ad aprire il file | Il suo DuckDB è più vecchio di quella versione. Deve aggiornare, oppure copi tu il file con uno STORAGE_VERSION più vecchio — vedi Quale DuckDB può leggere un database |
Database collegati
| Sintomo | Causa e soluzione |
|---|---|
| Un database collegato manca dopo un riavvio | Il suo file non era al percorso ricordato all'avvio, quindi è stato saltato. La registrazione resta; rimetti il file a posto e torna con la prossima connessione |
| Questo database è già aperto, come … | Il file è già il database principale, oppure è collegato con quel nome. Interrogalo con quel nome |
| Impossibile collegare …: il nome … è già usato nel database aperto. | Qualcos'altro nella connessione usa già l'alias ricordato — per esempio un database che hai collegato in SQL con lo stesso nome. Fai DETACH di quello, poi riapri il database o riavvia |
| La scrittura su un database collegato fallisce | È stato collegato in sola lettura, il valore predefinito. Scollega database dalla barra laterale, poi collegalo di nuovo con Sola lettura deselezionato |
| Il collegamento ha creato un database vuoto | Con Sola lettura deselezionato, un percorso DuckDB che non esiste viene creato. Scollegalo, elimina il file vuoto e controlla il percorso |
| Un nome di tabella senza database trova la tabella sbagliata | I nomi senza database si risolvono nel database predefinito. Fai clic destro su un database e scegli Usa come database predefinito, oppure scrivi alias.table |
Finder e Quick Look
Questi valgono solo per macOS.
| Sintomo | Causa e soluzione |
|---|---|
Il doppio clic su un file .parquet o .duckdb apre un'altra app | Quell'app è già la predefinita. Nel Finder, Ottieni informazioni → Apri con, scegli DuckLocal, poi Cambia tutto… |
| Il doppio clic su un file CSV o Excel non apre DuckLocal | Per scelta: DuckLocal non se ne assume la gestione. Usa Apri con → DuckLocal, oppure trascina il file sull'icona del Dock |
| DuckLocal non è offerto in Apri con, oppure Spazio non mostra l'anteprima di DuckLocal | macOS non ha ancora registrato l'app. Spostala in Applicazioni e avviala una volta. Per l'anteprima, poi esegui qlmanage -r nel Terminale e controlla che Anteprima DuckLocal sia attiva sotto Quick Look nelle impostazioni delle estensioni di Impostazioni di Sistema |
Un file .json semplice o un file Excel non mostra l'anteprima di DuckLocal | Per scelta: quelli sono lasciati alle anteprime di macOS. I file .jsonl e .ndjson hanno l'anteprima |
| L'anteprima mostra solo 50 righe | Per scelta: un'anteprima non scansiona mai il file intero. Apri il file in DuckLocal per il resto |
L'anteprima di un file .duckdb mostra un errore | L'anteprima legge il file con il DuckDB di DuckLocal, quindi un file di un DuckDB più recente fallisce anche lì. Vedi Aprire un database |
Esecuzione delle query
| Sintomo | Causa e soluzione |
|---|---|
| Esegui non fa nulla | Una query è già in esecuzione. Premi Interrompi accanto a Esegui, o ⌘., per interromperla |
Una query è fallita con Interrupted | Qualcuno ha premuto Interrompi (o ⌘.) mentre era in esecuzione. Eseguila di nuovo |
| Parte del mio SQL ha una sottolineatura ondulata rossa | L'ultima esecuzione è fallita lì. Leggi il messaggio Query non riuscita; il segno si cancella all'esecuzione successiva |
| ⌘↵ mostra l'editor invece di eseguire | Nella schermata del primo avvio, ⌘↵ significa "dammi un editor". Premilo di nuovo per eseguire |
| I risultati si fermano prima con un avviso di troncamento | È stato raggiunto il limite di 100.000 righe o di 2.000.000 di celle. Restringi la query; non c'è paginazione |
| I timestamp sembrano spostati | La griglia mostra i timestamp in UTC, non nell'ora locale |
Un valore TIMETZ ha perso il suo offset, o un valore BIT o BIGNUM sembra fatto di byte | Quei tipi non si distinguono dai valori normali nel loro percorso verso DuckLocal. CAST(column AS VARCHAR) in SQL mostra il valore reale |
| L'ordinamento non porta righe oltre l'anteprima | L'ordinamento dell'intestazione riordina solo le righe caricate. Usa ORDER BY in SQL per ordinare il risultato completo prima del troncamento |
| Una query richiede un'estensione non installata | Le estensioni mancanti non vengono più scaricate automaticamente. Installala esplicitamente nella scheda Estensioni, poi caricala o riesegui la query |
| Una query che funzionava prima della 0.3.0 dice che un'estensione non è installata, o che una funzione non esiste | DuckLocal 0.3.0 esegue DuckDB 2.0, che conserva le estensioni installate per release. Installale di nuovo dalla scheda Estensioni — vedi Estensioni |
Un alias di colonna nudo come minutes causa un errore di parser | È una parola chiave SQL. Scrivi AS minutes, oppure mettilo tra virgolette: SELECT count(*) AS "minutes" FROM events |
| Facendo clic su una tabella o su una voce della cronologia ho cancellato il mio SQL | Quei clic sostituiscono l'intero buffer dell'editor. Usa una nuova scheda query per gli appunti |
| Un'esportazione ha sostituito un file senza avvisare | L'esportazione scrive nel percorso che indichi senza chiedere. Scegli un nuovo nome |
S3
| Sintomo | Causa e soluzione |
|---|---|
| Le credenziali S3 sono state dimenticate | Per scelta valgono solo per la sessione, e aprire o cambiare un database le cancella. Configura di nuovo S3 |
| Configurare S3 fallisce offline | Il primo uso esegue INSTALL httpfs, che scarica l'estensione. Connettiti una volta, poi è in cache |
| Le credenziali temporanee (STS) vengono rifiutate | Non viene inviato alcun token di sessione. Usa chiavi di lunga durata — vedi S3 e httpfs |
| Un bucket sembra più piccolo di quello che è | L'elenco si ferma a 1.000 voci per livello. Interroga invece con un glob come 's3://bucket/prefix/*.parquet' |
Dashboard
| Sintomo | Causa e soluzione |
|---|---|
| Il grafico di una dashboard dice che una query deve essere in sola lettura | Una query .dash ha provato a scrivere (DDL, DML, COPY, ATTACH, …). Le dashboard eseguono solo istruzioni in sola lettura; sposta la preparazione nell'editor SQL |
| Un agente non ha visto i miei commenti | I commenti non vengono inviati da nessuna parte: è l'agente a doverli leggere. Chiedigli di eseguire ducklocal comments FILE, oppure di "risolvere i commenti su FILE" se ha la skill ufficiale |
| La risposta o la modifica di un agente non compare | La finestra segue sia lo spec sia FILE.comments.json entro un secondo. Uno spec che non è più valido mantiene in vista l'ultima dashboard funzionante, con il motivo sopra; apri Mostra spec per vedere il file |
Un PIVOT in una dashboard viene rifiutato | Un PIVOT annidato dentro un SELECT o un WITH deve indicare i suoi valori. Elencali: PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue), oppure inizia la query con il PIVOT |
Aspetto
| Sintomo | Causa e soluzione |
|---|---|
| Il tema torna a quello chiaro a ogni avvio | Il tema non viene salvato tra un avvio e l'altro; la lingua sì |
| Il testo o le icone sono troppo piccoli o troppo grandi | Usa il pulsante Aa nella barra del titolo, oppure ⌘+ / ⌘− / ⌘0. Vedi Dimensione dell'interfaccia |
| L'interfaccia è nella lingua sbagliata | Usa il pulsante EN / 中 nella barra del titolo; la scelta viene ricordata |
Ricominciare da zero
Per cancellare la cronologia, i file ricordati, le schede aperte e le impostazioni, chiudi DuckLocal e rimuovi la sua directory di dati dell'app:
bash
rm -rf ~/Library/Application\ Support/DuckLocalI tuoi file di dati non vengono mai toccati — vengono rimossi solo i registri di DuckLocal. Vedi Impostazioni e dati dell'app per cosa è memorizzato lì.
