# Datenquellen

> CSV-, Parquet-, JSON- und Excel-Dateien lokal mit DuckDB SQL abfragen. Ordner und Globs öffnen, Datenbanken anhängen und die Daten auf Ihrem Rechner behalten.

Source: https://ducklocal.app/docs/de/data-sources

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](https://ducklocal.app/use-cases/local-data-analysis/).

## 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](#open-from-finder)

Um eine Datenbank neben der geöffneten hinzuzufügen statt sie zu ersetzen, verwenden Sie
**Öffnen → Datenbank anhängen…** — siehe [Angehängte Datenbanken](#attached-databases).

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 {#supported-file-formats}

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](#database-files).

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 {#folders-and-patterns}

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 {#many-csv-files-at-once}

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 {#database-files}

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](#attached-databases).

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](#when-a-database-will-not-open)). 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 {#when-a-database-will-not-open}

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…](#attached-databases) 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](troubleshooting.md#opening-a-database).

### Welche DuckDB eine Datenbank lesen kann {#storage-version}

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 {#attached-databases}

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 {#in-the-sidebar}

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](schema-and-history.md) beschrieben.

### Über Verbindungen hinweg erhalten {#kept-across-connections}

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 {#open-from-finder}

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](dashboards.md)-Tab. Läuft
DuckLocal nicht, startet es zuerst und öffnet die Datei, sobald sein eigener Start
abgeschlossen ist.

## Vorschauen mit Quick Look {#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:

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](#kept-across-connections). 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](settings-and-data.md).
