Datenquellen
DuckLocal macht aus Dateien Views in einer In-Memory-DuckDB-Verbindung oder in einer Datenbankdatei, wenn Sie eine geöffnet haben. Andere Datenbanken können daneben liegen. Es gibt nichts zu konfigurieren. Wie Sie knapp von Dateien zu SQL, Diagrammen und Export kommen, zeigt der Workflow für lokale Datenanalyse.
Daten öffnen
All das folgt denselben Auflösungsregeln:
- Pfade auf der Kommandozeile —
ducklocal ./logs/ billing.parquet - Das Menü Öffnen in der Titelleiste: Dateien öffnen, Ordner öffnen oder Pfad oder Glob eingeben, das den Dialog Daten öffnen für einen eingetippten Pfad oder einen aus dem nativen Auswahldialog öffnet
- Dateien oder Ordner irgendwo im Fenster ablegen
- Auf einem Mac Dateien, die Finder an DuckLocal übergibt — siehe Aus Finder öffnen
Um eine Datenbank neben der geöffneten hinzuzufügen statt sie zu ersetzen, verwenden Sie Öffnen → Datenbank anhängen… — siehe Angehängte Datenbanken.
Unter macOS können Sie Parquet- und DuckDB-Dateien im Finder doppelklicken, um sie zu öffnen, oder die Leertaste drücken, um die ersten Zeilen von Parquet-, DuckDB-, CSV-, TSV- und JSON-Lines-Dateien mit Quick Look in der Vorschau zu sehen, ohne DuckLocal zu starten.
Unterstützte Dateiformate
Erweiterungen werden ohne Unterscheidung von Groß- und Kleinschreibung abgeglichen.
| Erweiterung | Wie sie gelesen wird |
|---|---|
.csv, .tsv, .txt | View über read_csv_auto |
.parquet | View über read_parquet |
.json, .ndjson, .jsonl | View über read_json_auto |
.xlsx, .xls, .xlsb, .ods | als Tabelle pro Blatt importiert |
Gzip-komprimierter Text wie .json.gz und .csv.gz gilt ebenfalls als Datendatei — in schema, in source-Blöcken und beim Anhängen einer Datei; logs.json.gz wird zu einer View namens logs. Vor 0.4.0 hat ducklocal schema versucht, eine solche Datei als Datenbank zu öffnen; lesen Sie sie in einer älteren Version mit read_json oder read_csv in SQL.
Alles andere ist keine Datendatei — siehe Datenbankdateien.
Eine Arbeitsmappe ist das einzige Format, das zu Tabellen statt Views wird, und sie importiert jedes Blatt: Das erste Blatt erhält den Dateistamm (den Dateinamen ohne Erweiterung) als Namen, die übrigen heißen {stem}_{sheet name}. Ein leeres Blatt wird übersprungen. Spaltentypen werden aus den Zellen abgeleitet — Ganzzahlen werden BIGINT, eine Mischung aus Ganzzahl und Gleitkomma DOUBLE, Datumsangaben TIMESTAMP, und alles Gemischte oder Unbekannte VARCHAR; leere Zellen werden als NULL importiert.
Ordner und Muster
Ein Verzeichnis wird rekursiv durchlaufen, und jede Datendatei darin wird zu einer View. Für den Durchlauf gelten zwei Regeln:
- Versteckte Einträge (Namen, die mit
.beginnen) werden übersprungen, und ihre Unterbäume werden nicht betreten. - Symlinks werden nicht verfolgt. Ein Link zurück nach oben im Baum würde nie enden, und das verlinkte Verzeichnis wird normalerweise dort durchlaufen, wo es tatsächlich liegt.
Dateien werden in sortierter Reihenfolge angehängt, sodass derselbe Ordner immer denselben Arbeitsbereich ergibt.
Ein Muster darf * (eine beliebige Folge von Zeichen) und ? (genau ein Zeichen) enthalten. Der Abgleich erfolgt pro Pfadkomponente gegen das Dateisystem, sodass ein Muster Verzeichnisse überspannen kann:
ducklocal './data/2026-0*/*.parquet'Es gibt kein Escape-Zeichen. ** ist nichts Besonderes — es verhält sich wie ein einzelnes * und rekursiert nicht. Ein Muster, das auf ein Verzeichnis passt, überspringt es; nur Dateien werden angehängt. Auch hier werden versteckte Einträge übersprungen.
Nicht in Anführungszeichen gesetzte Muster werden von Ihrer Shell erweitert, bevor DuckLocal sie sieht. Das ist in Ordnung. Setzen Sie ein Muster nur dann in Anführungszeichen, wenn DuckLocal es erweitern soll — etwa wenn die Shell keine Übereinstimmung findet und sonst mit einem Fehler abbricht.
Viele CSV-Dateien auf einmal
Jede von DuckLocal angehängte Datei wird zu einer eigenen View mit ihrem eigenen erkannten Schema, sodass zwei nicht zusammenpassende CSVs einander nie stören. Die Fallstricke zeigen sich, wenn ein SQL-Lesevorgang viele Dateien umfasst:
SELECT * FROM read_csv('data/*.csv', union_by_name = true)Die Typerkennung kann zwischen Dateien uneinig sein. Der Reader leitet den Typ einer Spalte aus einer Stichprobe ab; eine Spalte, die überall numerisch ist, aber in einer Datei einen verirrten String
'NULL'enthält, lässt den gesamten Lesevorgang mit einem Konvertierungsfehler scheitern, und ein Cast in derSELECT-Liste kommt zu spät — schon das Lesen schlägt fehl. Lesen Sie jede Spalte als Text und casten Sie stattdessen in SQL:sqlSELECT try_cast(amount AS DOUBLE) AS amount FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)union_by_name = truetoleriert auch Dateien, deren Spaltensätze sich unterscheiden.Der String
'NULL'ist nichtNULL. Ein literales'NULL'(oder'N/A','null') in einer CSV ist gewöhnlicher Text, daher filtertWHERE amount IS NOT NULLes nicht heraus. Verwenden SieNULLIF(amount, 'NULL')oderWHERE amount <> 'NULL'.
Beide Korrekturen lassen sich kombinieren: try_cast(NULLIF(amount, 'NULL') AS DOUBLE).
Datenbankdateien
DuckLocal hat jeweils eine Hauptdatenbank: im Arbeitsspeicher oder eine von Ihnen geöffnete DuckDB-Datei. Datendateien werden zu Views in der Hauptdatenbank. Sie können auch weitere Datenbanken daneben anhängen.
Jeder Pfad, der existiert und keine Datendatei ist, wird als Hauptdatenbank geöffnet, statt als View angehängt zu werden. Die Erweiterung spielt keine Rolle: Ein .db-, .duckdb- oder sogar .md-Pfad wird als Datenbank behandelt, und DuckDB entscheidet, ob sie sich tatsächlich öffnen lässt.
Einige Konsequenzen sind wichtig:
- Eine neue Datenbank entsteht nur im Dialog „Daten öffnen“. Tippen Sie einen Pfad ein, der auf
.duckdbendet und noch nicht existiert, erstellt DuckLocal die Datenbank samt fehlender übergeordneter Ordner. Überall sonst — auf der Kommandozeile, in den Auswahldialogen, beim Ablegen, im Finder — wird ein nicht existierender Pfad alsFile not foundgemeldet. - Das Öffnen einer Datenbank ersetzt die Hauptdatenbank. Ihre registrierten Dateien und angehängten Datenbanken werden in die neue Verbindung erneut angehängt. S3-Zugangsdaten nicht; konfigurieren Sie S3 erneut.
- Wenn die Datei sich nicht öffnen lässt, nennt DuckLocal den Grund (unten). Beim Start fällt es auf einen In-Memory-Arbeitsbereich zurück, statt zu scheitern. Im laufenden Betrieb bleibt der bisherige Arbeitsbereich unverändert.
- Eine bereits angehängte Datei neben der Hauptdatenbank wird zuerst getrennt und dann als Hauptdatenbank geöffnet. Schlägt das Öffnen fehl, kommt die Anhängung zurück. Das Öffnen der Datei, die bereits die Hauptdatenbank ist, verwendet sie weiter.
Das Anhängen von Datendateien bei geöffneter Datenbankdatei schreibt diese Views in die Datenbankdatei — sie bleiben dort bestehen, nicht nur in der Sitzung.
Wenn sich eine Datenbank nicht öffnen lässt
Wenn DuckDB eine Datei ablehnt, liest DuckLocal selbst die ersten Bytes der Datei und setzt, wo sie den Fehler erklären, einen Grund und einen Ausweg über DuckDBs eigene Meldung. DuckDBs Meldung bleibt darunter für den genauen Fehler. Die Erklärung erscheint in der Sprache der Oberfläche.
| Was die Datei ist | Was DuckLocal Ihnen sagt |
|---|---|
| Eine DuckDB-Datei, die von einer neueren DuckDB geschrieben wurde als der in DuckLocal eingebauten Version | Beide Versionen und SQL, das Sie in der neueren DuckDB ausführen, um die Datei in ein Format zu kopieren, das DuckLocal liest (unten) |
| Eine DuckDB-Datei aus v0.9 oder älter | Führen Sie EXPORT DATABASE 'dir' mit der DuckDB aus, die sie geschrieben hat, dann IMPORT DATABASE 'dir' in DuckLocal |
| Eine SQLite-Datenbank | Das ist keine DuckDB-Datei; hängen Sie sie stattdessen an — mit Datenbank anhängen… oder INSTALL sqlite; ATTACH '…' (TYPE sqlite); |
| Etwas anderes, das keine DuckDB-Datei ist | Öffnen Sie stattdessen CSV-, Parquet-, JSON- oder Excel-Dateien als Datendateien |
Bei einer Datei aus einer neueren DuckDB setzt die Meldung den Pfad der Datei und die DuckDB-Version von DuckLocal ein. Führen Sie sie in der DuckDB aus, die die Datei erstellt hat, und öffnen Sie dann compat.duckdb:
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;Dateien, die vor DuckDB v1.2 geschrieben wurden, zeichnen nicht auf, welches Release sie erstellt hat. Jeder andere Fehler — eine Datei, die ein anderes Programm gesperrt hat, eine, die Sie nicht lesen dürfen — zeigt nur DuckDBs Meldung. Siehe Fehlerbehebung.
Welche DuckDB eine Datenbank lesen kann
Wenn eine Datenbankdatei geöffnet ist, zeigt die Statusleiste ihren Pfad. Fahren Sie mit der Maus darüber, um das Speicherformat der Datei zu sehen — die älteste DuckDB, die sie liest, etwa Speicherformat: lesbar mit DuckDB v1.0.0+ — und, wenn die Datei es aufzeichnet, das Release, das sie erstellt hat (Erstellt mit DuckDB v1.4.3). Prüfen Sie das, bevor Sie eine Datei an jemanden mit einer älteren DuckDB weitergeben.
DuckLocal verwendet DuckDB 2.0, aber eine von ihm erstellte Datenbankdatei wird im Format von DuckDB 1.x geschrieben (lesbar mit DuckDB v1.0.0+), sodass die duckdb CLI, Python oder DBeaver unter DuckDB 1.x sie weiterhin öffnen. Eine Datei, die ein anderes Programm im eigenen Format von DuckDB 2.0 geschrieben hat (v2.0.0+), lässt sich ebenfalls öffnen und behält dieses Format: 1.x kann sie nicht lesen.
Angehängte Datenbanken
Hängen Sie eine weitere DuckDB- oder SQLite-Datei neben der Hauptdatenbank an, um über beide hinweg abzufragen — etwa einen Snapshot neben den heutigen Daten.
- Öffnen Sie das Menü Öffnen in der Titelleiste und wählen Sie Datenbank anhängen….
- Tippen Sie den Pfad ein oder klicken Sie auf Durchsuchen, um die Datei auszuwählen.
- Lassen Sie Schreibgeschützt angehakt, solange Sie die Datei nicht ändern wollen. Es ist standardmäßig angehakt.
- Klicken Sie auf Anhängen.
Die Datenbank erhält einen Alias aus ihrem Dateinamen, und Sie fragen ihre Tabellen als alias.table (oder alias.schema.table) ab:
-- 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);So entsteht der Alias:
- Der Dateistamm, wobei jedes Zeichen, das kein ASCII-Buchstabe und keine Ziffer ist, durch
_ersetzt wird. db_davor, wenn er nicht mit einem Buchstaben beginnt: Aus2026-10 logs.duckdbwirddb_2026_10_logs.- Ein Zähler, wenn der Name belegt ist:
snap, dannsnap_2.mainwird nie verwendet. - Wird eine Datei später erneut angehängt, bekommt sie ihren früheren Alias zurück, sodass darauf geschriebenes SQL weiter funktioniert.
Details:
- SQLite-Dateien werden an ihrem Inhalt erkannt und über DuckDBs Erweiterung
sqliteangehängt. - Schreibgeschützt abwählen hängt die Datei zum Schreiben an. Ein nicht existierender DuckDB-Pfad wird dann als neue, leere Datenbank erstellt; schreibgeschützt schlägt das Anhängen stattdessen fehl.
- Dieselbe Datei wird nie zweimal angehängt. Beim Anhängen einer bereits geöffneten Datei — als Hauptdatenbank oder als Anhängung — erscheint Diese Datenbank ist bereits geöffnet, als ….
In der Seitenleiste
Jede Datenbank erscheint im Schema-Baum, die Hauptdatenbank wie angehängte gleichermaßen, auch leere. Eine Datenbank zeigt neben ihrem Namen read-only oder sqlite, wo das zutrifft, und ihre Datei als Tooltip.
Rechtsklick auf eine Datenbank bietet:
- Als Standarddatenbank verwenden — führt
USEaus, sodass Tabellennamen ohne Datenbank dort aufgelöst werden. Die Statusleiste zeigt, wo sie jetzt aufgelöst werden. - Datenbank trennen — trennt sie und vergisst sie, sodass sie beim nächsten Mal nicht zurückkommt. War sie die Standarddatenbank, wechselt die Sitzung zuerst zur Hauptdatenbank zurück. Die Datei selbst bleibt unberührt.
Der Rest dieses Menüs ist in Schema-Browser und Verlauf beschrieben.
Über Verbindungen hinweg erhalten
Angehängte Datenbanken werden in DuckLocals eigener Verlaufsdatenbank mit ihrem Alias und ihrer Schreibgeschützt-Einstellung gespeichert und in jede neue Verbindung erneut angehängt: beim nächsten Start, nachdem Sie eine andere Datenbank geöffnet haben, und nach Neue In-Memory-Datenbank.
- Eine Datenbank, deren Datei fehlt, wird still übersprungen. Ihre Registrierung bleibt erhalten, sodass sie zurückkommt, sobald die Datei wieder da ist — DuckLocal legt nie eine leere Datenbank an ihrer Stelle an.
- Eine Datenbank, die bereits geöffnet ist — als Hauptdatenbank oder anders —, wird nicht ein zweites Mal angehängt.
- Hat die neue Hauptdatenbank bereits eine Datenbank unter diesem Alias, meldet DuckLocal Konnte … nicht anhängen: Der Name … ist in der geöffneten Datenbank vergeben.
Aus Finder öffnen
Auf einem Mac kann Finder Dateien direkt an DuckLocal übergeben:
| Datei | Doppelklick | Öffnen mit oder auf das Dock-Symbol ziehen |
|---|---|---|
.parquet | Öffnet in DuckLocal | Ja |
.duckdb, .ddb | Öffnet in DuckLocal | Ja |
.dash | Öffnet in DuckLocal | Ja |
.csv, .tsv, .json, .jsonl, .ndjson, .xlsx, .xls | Bleibt bei der App, die sie bereits öffnet (Numbers, Excel, ein Texteditor) | Ja |
DuckLocal registriert sich nur für Formate als Standard, die sonst nichts auf einem Mac beansprucht. Hat eine andere App Parquet- oder DuckDB-Dateien bereits übernommen, wählen Sie DuckLocal unter Öffnen mit — oder nutzen Sie im Finder Informationen → Öffnen mit → Alle ändern…, um es zum Standard zu machen.
Eine Datei aus dem Finder wird genauso behandelt wie ein Ablegen im Fenster: Eine Datendatei wird zu einer View im aktuellen Arbeitsbereich, eine Datenbankdatei wird als Hauptdatenbank geöffnet, und eine .dash-Datei öffnet sich als Dashboard-Tab. Läuft DuckLocal nicht, startet es zuerst und öffnet die Datei, sobald sein eigener Start abgeschlossen ist.
Vorschauen mit Quick Look
Wählen Sie auf einem Mac eine Datendatei im Finder aus und drücken Sie die Leertaste, um ihre Spalten und ersten Zeilen zu sehen, ohne etwas zu öffnen. Die Vorschau ist in DuckLocal.app enthalten; es gibt nichts separat zu installieren. Sie benötigt macOS 12 oder neuer, wie die App.
| Datei | Was die Vorschau zeigt |
|---|---|
.parquet | Spalten und Typen, die ersten 50 Zeilen und aus dem Footer der Datei: Zeilenzahl, Row Groups, Kompression und den Writer |
.duckdb, .ddb | Die Anzahl der Tabellen, das Speicherformat (Lesbar mit DuckDB …) und die fünf größten Tabellen, jede mit geschätzter Zeilenzahl und den ersten 50 Zeilen |
.csv, .tsv | Spalten mit ihren erkannten Typen und die ersten 50 Zeilen — eine Tabelle statt Rohtext |
.jsonl, .ndjson | Spalten und die ersten 50 Zeilen |
Reine .json- und Excel-Dateien bleiben den eigenen Vorschauen von macOS überlassen.
Was die Vorschau tut und nicht tut:
- Sie schreibt nie. Eine Datenbank wird schreibgeschützt angehängt.
- Sie liest nie eine ganze Datei: Zeilen sind ein
LIMIT, und eine Zeilenzahl erscheint nur, wo das Format eine speichert (Parquets Footer, die Schätzung einer Datenbank). - Sie lädt nichts herunter: DuckDB-Erweiterungen werden weder installiert noch geladen.
- Zellen mit mehr als 200 Zeichen werden abgeschnitten. Der Text der Seite ist auf Englisch.
- Eine Datei, die sie nicht lesen kann, bekommt eine Seite, die den Grund nennt.
Wenn die Leertaste keine DuckLocal-Vorschau zeigt:
- Stellen Sie sicher, dass DuckLocal in Programme liegt, und starten Sie es einmal. macOS registriert die Vorschau, wenn es die App zum ersten Mal sieht.
- Setzen Sie Quick Look im Terminal zurück:
qlmanage -r. Versuchen Sie es dann erneut. - Prüfen Sie, dass DuckLocal Preview unter Quick Look in den Erweiterungseinstellungen der Systemeinstellungen aktiviert ist.
Benennung
Die View einer Datei wird nach ihrem Dateistamm benannt, bereinigt zu einem gültigen Bezeichner. Ist der Name in der Verbindung bereits vergeben, hängt DuckLocal einen Zähler an: events, dann events_2, events_3. Zwei Dateien mit demselben Stamm in verschiedenen Verzeichnissen erhalten daher unterschiedliche Views.
Die Duplikaterkennung richtet sich nach dem Pfadtext wie geschrieben, daher gelten ./a.csv und a.csv als zwei verschiedene Dateien.
Grenzen
- 256 Datendateien pro Öffnungsanfrage. Die Obergrenze gilt für alle Pfade einer Anfrage zusammen, nicht pro Ordner — sie existiert, damit ein versehentlich abgelegtes Home-Verzeichnis die Verbindung nicht minutenlang blockiert. Wird die Grenze erreicht, sagt DuckLocal das und hängt die ersten 256 Dateien an.
- Dateien, die beim Start aus der vorherigen Sitzung erneut angehängt werden, unterliegen dieser Grenze nicht.
Registrierte Quellen verwalten
Registrierte Dateien erscheinen in der Gruppe Lokale Dateien der Seitenleiste, jeweils mit View-Name, Dateiname und Zeilenzahl. Wenn Sie eine Datei auswählen, wird eine SELECT-Anweisung dafür erzeugt.
Das × in einer Dateizeile entfernt sie, nach einem Bestätigungsdialog. Das Entfernen verwirft die View und vergisst die Registrierung; die zugrunde liegende Datei bleibt unberührt.
Schema aktualisieren lädt den Katalog und die registrierten Dateien neu.
Was gespeichert bleibt
Die Liste der registrierten Dateien — ihre Pfade, View-Namen und Arten — wird in DuckLocals eigener Verlaufsdatenbank gespeichert und beim nächsten Start erneut angehängt, sodass Sie den Arbeitsbereich zurückbekommen, den Sie verlassen haben. Ebenso angehängte Datenbanken. Die Hauptdatenbankdatei wird nicht gespeichert: Jeder Start beginnt im Arbeitsspeicher, solange Sie keine Datenbank angeben.
Die Speicherorte auf der Festplatte finden Sie unter Einstellungen und App-Daten.
