Zum Inhalt springen

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:

  1. Pfade auf der Kommandozeile — ducklocal ./logs/ billing.parquet
  2. 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
  3. Dateien oder Ordner irgendwo im Fenster ablegen
  4. 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.

ErweiterungWie sie gelesen wird
.csv, .tsv, .txtView über read_csv_auto
.parquetView über read_parquet
.json, .ndjson, .jsonlView über read_json_auto
.xlsx, .xls, .xlsb, .odsals 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:

bash
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:

sql
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 der SELECT-Liste kommt zu spät — schon das Lesen schlägt fehl. Lesen Sie jede Spalte als Text und casten Sie stattdessen in 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 toleriert auch Dateien, deren Spaltensätze sich unterscheiden.

  • Der String 'NULL' ist nicht NULL. Ein literales 'NULL' (oder 'N/A', 'null') in einer CSV ist gewöhnlicher Text, daher filtert WHERE amount IS NOT NULL es nicht heraus. Verwenden Sie NULLIF(amount, 'NULL') oder WHERE 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 .duckdb endet 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 als File not found gemeldet.
  • 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 istWas DuckLocal Ihnen sagt
Eine DuckDB-Datei, die von einer neueren DuckDB geschrieben wurde als der in DuckLocal eingebauten VersionBeide 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 älterFühren Sie EXPORT DATABASE 'dir' mit der DuckDB aus, die sie geschrieben hat, dann IMPORT DATABASE 'dir' in DuckLocal
Eine SQLite-DatenbankDas 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:

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;

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.

  1. Öffnen Sie das Menü Öffnen in der Titelleiste und wählen Sie Datenbank anhängen….
  2. Tippen Sie den Pfad ein oder klicken Sie auf Durchsuchen, um die Datei auszuwählen.
  3. Lassen Sie Schreibgeschützt angehakt, solange Sie die Datei nicht ändern wollen. Es ist standardmäßig angehakt.
  4. 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:

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);

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: Aus 2026-10 logs.duckdb wird db_2026_10_logs.
  • Ein Zähler, wenn der Name belegt ist: snap, dann snap_2. main wird 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 sqlite angehä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 USE aus, 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:

DateiDoppelklickÖffnen mit oder auf das Dock-Symbol ziehen
.parquetÖffnet in DuckLocalJa
.duckdb, .ddbÖffnet in DuckLocalJa
.dashÖffnet in DuckLocalJa
.csv, .tsv, .json, .jsonl, .ndjson, .xlsx, .xlsBleibt 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.

DateiWas die Vorschau zeigt
.parquetSpalten und Typen, die ersten 50 Zeilen und aus dem Footer der Datei: Zeilenzahl, Row Groups, Kompression und den Writer
.duckdb, .ddbDie 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, .tsvSpalten mit ihren erkannten Typen und die ersten 50 Zeilen — eine Tabelle statt Rohtext
.jsonl, .ndjsonSpalten 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:

  1. 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.
  2. Setzen Sie Quick Look im Terminal zurück: qlmanage -r. Versuchen Sie es dann erneut.
  3. 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.

Veröffentlicht unter der Apache-2.0-Lizenz.