DuckDB Tutorial: Analytisches SQL direkt im Browser

Wenn du schon mal Aggregationen über eine CSV mit 5 Millionen Zeilen in SQLite laufen lassen hast und auf den drehenden Cursor gestarrt hast, kennst du das Problem. DuckDB löst genau das — und dieses DuckDB Tutorial bringt dich in unter 15 Minuten zu echtem analytischem SQL, ohne Server.

TL;DR

• DuckDB ist eine eingebettete analytische Datenbank — kein Server, kein Daemon, kein Config-File. Du installierst sie mit pip install duckdb und schreibst sofort SQL.
• Columnar + vektorisiert — Aggregationen über breite Tabellen sind dramatisch schneller als bei zeilenbasierten Engines wie SQLite oder Postgres.
• Direkter Dateizugriff — read_parquet() und read_csv_auto() lesen Files direkt von Disk, HTTPS oder S3, ohne Import-Schritt.
• DuckDB WASM — die komplette Engine läuft im Browser-Tab, ohne Backend. Deine Daten verlassen die Seite nicht.
• Nicht geeignet für Multi-Writer, transaktionale Apps oder Petabyte-Workloads. Dafür gibt es Postgres bzw. Snowflake/BigQuery.

Was DuckDB anders macht

DuckDB ist eine In-Process analytische Datenbank. Kein Server-Prozess. Keine Config-Datei. Kein Daemon, den du verwalten musst. Du bettest sie direkt in Python ein, nutzt sie über die Kommandozeile oder lässt sie im Browser via WebAssembly laufen — und sie führt OLAP-Queries über eine vektorisierte, spaltenorientierte Engine aus, die Leute regelmäßig damit überrascht, wie schnell sie auf lokalen Daten ist.

Der duckdb getting started Einstieg ist bewusst minimal: ein pip install duckdb und du schreibst analytisches SQL. Die eigentliche Stärke liegt aber im SQL-Dialekt selbst — read_parquet, read_csv_auto, PIVOT, Window Functions und ein wachsendes Set an analytischen Extensions. Das ist nicht SQLite mit einem neuen Marketing-Label. Das Ausführungsmodell ist fundamental anders.

DuckDB Architektur: Embedded, kein Server

Wenn du die Architektur von DuckDB verstehst, kennst du gleichzeitig die Stärken und die Grenzen. Alles läuft in deinem Prozess — es gibt keine separate Server-Komponente.

graph TD
    A["Your Application\nPython / Node.js / CLI"]:::blue --> B["DuckDB Engine\nIn-Process, Columnar"]:::green
    B --> C["In-Memory Storage\nor .duckdb File"]:::amber
    B --> D["Parquet Files\nDirect Read / Pushdown"]:::rose
    B --> E["CSV / JSON Files\nAuto Schema Detection"]:::rose
    B --> F["DuckDB WASM\nBrowser Runtime — No Backend"]:::purple

    classDef blue fill:#D6DCF5,stroke:#7B83B0,stroke-width:1.5px,color:#2B3674,font-weight:bold
    classDef green fill:#D8E4BF,stroke:#9AAF78,stroke-width:1.5px,color:#2B3674,font-weight:bold
    classDef amber fill:#F0E2C8,stroke:#C4A97A,stroke-width:1.5px,color:#2B3674,font-weight:bold
    classDef rose fill:#F5D5D5,stroke:#C49A9A,stroke-width:1.5px,color:#2B3674,font-weight:bold
    classDef purple fill:#E2D6F5,stroke:#9A83B0,stroke-width:1.5px,color:#2B3674,font-weight:bold

① In-Process-Ausführung — DuckDB läuft innerhalb deiner Anwendung. Keine Netzwerk-Roundtrips, kein Connection-Pooling, kein Port, den du öffnen musst. Es startet in Millisekunden.

② Columnar Engine — Queries scannen nur die Spalten, die sie brauchen, mit SIMD-Instruktionen und vektorisiertem Batching. Aggregationen über breite Tabellen sind dramatisch schneller als bei zeilenbasierten Datenbanken.

③ Direkter Dateizugriff — DuckDB liest Parquet, CSV und JSON direkt von Disk, von remote HTTPS oder S3-kompatiblem Storage, ohne sie vorher in eine Datenbank zu importieren.

④ DuckDB WASM — Das WebAssembly-Build kompiliert die komplette DuckDB-Engine für die Ausführung im Browser. Kein Backend, kein Daten-Upload — die Queries laufen client-seitig im Browser-Tab.

🔵 Application Layer  |  🟢 DuckDB Core  |  🟡 Local Storage  |  🔴 File Sources  |  🟣 Browser Runtime

DuckDB vs SQLite vs PostgreSQL

Die häufigste Verwirrung ist, wo DuckDB im Vergleich zu existierenden Datenbanken hingehört. Hier der Vergleich, der für analytisches SQL wirklich zählt:

Stand: 14. Mai 2026.

Der Unterschied in der Design-Philosophie: DuckDB optimiert auf Read-Throughput über breite Tabellen. SQLite optimiert auf kleine, häufige Writes in eingebetteten Apps. PostgreSQL optimiert auf Korrektheit und parallelen Zugriff in Server-Anwendungen. Sie sind keine Konkurrenten — sie lösen unterschiedliche Probleme.

Tutorial: DuckDB in der Praxis

Schritt 1: DuckDB installieren

pip install duckdb

Keine System-Dependencies. Kein Docker. Keine Environment-Variablen. Das ist die komplette Installation.

Für die CLI:

# macOS
brew install duckdb

# Oder das Binary von duckdb.org/docs/installation laden

Schritt 2: Eine CSV-Datei mit read_csv_auto abfragen

DuckDBs read_csv_auto liest eine CSV-Datei und erkennt die Spaltentypen automatisch. Du schreibst SQL direkt gegen die Datei — kein Import-Schritt, kein vorgeschaltetes CREATE TABLE.

-- DuckDB SQL: query a CSV file without importing it
SELECT
    region,
    COUNT(*)                    AS order_count,
    SUM(revenue)                AS total_revenue,
    ROUND(AVG(revenue), 2)      AS avg_order_value
FROM read_csv_auto('sales_data.csv')
WHERE order_date >= '2024-01-01'
GROUP BY region
ORDER BY total_revenue DESC;

Aus Python, mit einem pandas DataFrame als Rückgabe:

import duckdb

conn = duckdb.connect()  # in-memory; pass a file path to persist

result = conn.execute("""
    SELECT
        region,
        COUNT(*)               AS order_count,
        SUM(revenue)           AS total_revenue,
        ROUND(AVG(revenue), 2) AS avg_order_value
    FROM read_csv_auto('sales_data.csv')
    WHERE order_date >= '2024-01-01'
    GROUP BY region
    ORDER BY total_revenue DESC
""").fetchdf()

print(result)

Ein praktischer Hinweis: read_csv_auto ist exzellent für Exploration. In produktiven Pipelines solltest du Typen explizit angeben — read_csv('file.csv', columns={'id': 'INTEGER', 'revenue': 'DOUBLE'}) — um Schema-Drift-Probleme zu vermeiden.

Schritt 3: Parquet-Dateien mit read_parquet abfragen

Parquet ist das Standard-Format des modernen Data Stacks — columnar, komprimiert, effizient für Analytics. DuckDBs read_parquet kann lokale Dateien, HTTPS-Endpunkte oder S3-kompatibles Storage direkt abfragen.

-- DuckDB SQL: aggregate a remote Parquet file with column pushdown
SELECT
    year,
    category,
    SUM(amount)             AS total_amount,
    COUNT(DISTINCT user_id) AS unique_users
FROM read_parquet('s3://my-data-bucket/transactions/2024/*.parquet')
WHERE year = 2024
  AND category IN ('electronics', 'apparel')
GROUP BY year, category
ORDER BY total_amount DESC;

DuckDB nutzt die Parquet-Metadaten, um Column-Selection und Row-Group-Filter pushdownmäßig auf die Datei anzuwenden. Bei einer 10-GB-Parquet-Datei, in der du 3 Spalten aggregierst, liest die Engine eventuell nur 15 % der eigentlichen Bytes. Das ist der Grund, warum analytical sql duckdb auf großen Dateien überraschend gut performt, die in SQLite schmerzhaft langsam wären.

Du kannst auch über mehrere Dateien globben: read_parquet('data/2024-*.parquet') liest alle passenden Dateien als eine einzige virtuelle Tabelle.

Schritt 4: Ergebnisse mit PIVOT umformen

PIVOT macht aus Zeilenwerten Spalten — essenziell für Reporting und Zeitreihen-Vergleiche. DuckDB unterstützt das nativ; in den meisten anderen Datenbanken würdest du manuelle CASE WHEN-Ausdrücke schreiben.

-- DuckDB SQL: PIVOT monthly revenue by region
PIVOT (
    SELECT
        region,
        strftime(order_date, '%Y-%m') AS month,
        SUM(revenue)                   AS revenue
    FROM read_csv_auto('sales_data.csv')
    GROUP BY region, month
)
ON month
USING SUM(revenue)
ORDER BY region;

Output: eine Zeile pro Region, eine Spalte pro Monat (2024-01, 2024-02, …). Genau die Struktur, die du an ein BI-Tool oder eine Tabellenkalkulation übergibst — und du hast SQL nie verlassen.

Häufige Fehler und Fallen

DuckDB für parallele Writes nutzen. DuckDB ist Single-Writer. Nur ein Prozess kann eine .duckdb-Datei gleichzeitig zum Schreiben öffnen. Wenn deine Anwendung mehrere Writer hat oder du einen transaktionalen Service baust, nimm PostgreSQL.

Sich in der Produktion auf read_csv_auto verlassen. Die Auto-Detection funktioniert in 90 % der Explorationsfälle. Die übrigen 10 % bringen schwer zu debuggende Type-Coercion-Probleme in Pipelines. Spezifiziere für den produktiven Einsatz explizite Schemas.

DuckDB als Data-Warehouse-Ersatz behandeln. Für Datensätze bis ca. 50–100 GB auf einer einzelnen Maschine ist DuckDB exzellent. Für Petabyte-skalige Multi-User-Analytics willst du weiterhin ein verteiltes Warehouse. Sie ergänzen sich — DuckDB WASM für interaktive Exploration, Snowflake oder Databricks für die schweren geteilten Workloads.

Memory-Limits ignorieren. DuckDB spillt automatisch auf Disk, wenn der Speicher voll ist, aber die Query-Performance leidet deutlich. Kenn die Größe deines Datensatzes. Bei sehr großen Datensätzen filtere aggressiv, bevor du aggregierst.

Wann DuckDB NICHT die richtige Wahl ist

DuckDB hat klare Grenzen. Nimm etwas anderes, wenn:

• Multi-User transaktionale Anwendungen — parallele Writes, Foreign-Key-Enforcement, Row-Level-Security → PostgreSQL
• Petabyte-skalige geteilte Analytics — verteilte Query-Ausführung, Caching, Workload-Management → Snowflake, BigQuery, Databricks
• Mobile- oder IoT-Embedded-Datenbanken — SQLite hat besseren Multi-Process-Support und einen kleineren Footprint für schreibintensive Embedded-Anwendungsfälle
• Lang laufende geteilte Server-Prozesse — DuckDBs Single-Writer-Modell funktioniert in Multi-Process-Server-Architekturen schlecht
• Komplexe OLTP-Schemas — Trigger, ausgedehnte FK-Constraints, Stored Procedures → PostgreSQL oder MySQL

Die ehrliche Version: DuckDB ist ein Spezialist, der eine spezifische Aufgabe exzellent löst. Diese Aufgabe ist analytisches SQL auf lokalen oder dateibasierten Daten. Wenn dein Job dazu passt, ist es vermutlich das beste verfügbare Werkzeug. Wenn nicht, ist es das falsche Werkzeug.

DuckDB WASM: Der Browser-Angle

Die überraschendste Entwicklung im DuckDB-Ökosystem ist das WebAssembly-Build — duckdb wasm. Es kompiliert die komplette DuckDB-Engine so, dass sie in einem Browser-Tab läuft, ohne dass ein Backend-Server involviert ist. Du bekommst denselben SQL-Dialekt, dieselben Datei-Lese-Fähigkeiten und dieselben Performance-Charakteristiken — client-seitig.

Harbinger Explorer nutzt DuckDB WASM als zentrale Query-Engine. Wenn du eine CSV verbindest, eine Datei hochlädst oder eine API-Quelle abfragst, läuft das exakte SQL aus diesem Tutorial direkt in deinem Browser. Kein Server verarbeitet deine Daten — sie verlassen deinen Tab nie. Du kannst es selbst mit einer 7-Tage-Gratis-Testphase ausprobieren.

Nächste Schritte

Du hast den Kern-Workflow von DuckDB durchlaufen: Dateien mit read_csv_auto und read_parquet lesen, analytische Aggregationen ausführen und Ergebnisse mit PIVOT umformen. Ein paar Richtungen, in die du jetzt weitergehen kannst:

• Wenn du Daten ganz ohne SQL abfragen willst, schau dir Natural Language SQL: Frag deine Daten in normaler Sprache an.
• Um deine Datenquellen zu organisieren, wenn dein Katalog wächst, lies Was ist ein Data Catalog?

Die DuckDB-Dokumentation auf duckdb.org deckt die komplette SQL-Referenz ab — die httpfs-Extension für S3/HTTPS-Zugriff und die json-Extension sind als Nächstes lesenswert.

FAQ

Was ist DuckDB in einem Satz? Eine eingebettete, spaltenorientierte SQL-Datenbank für Analytics — wie SQLite, nur für OLAP statt OLTP, und mit nativer Unterstützung für Parquet, CSV und WebAssembly.

Ersetzt DuckDB Snowflake oder BigQuery? Nein. Für Single-User Analytics bis ca. 50–100 GB auf einer Maschine ist DuckDB exzellent und oft schneller. Für Petabyte-skalige Multi-User-Workloads brauchst du weiterhin ein verteiltes Warehouse. Sie ergänzen sich.

Kann ich DuckDB als Backend für eine Webanwendung nutzen? Nur für Read-Heavy-Workloads. DuckDB ist Single-Writer — wenn mehrere Prozesse parallel schreiben müssen, nimm PostgreSQL. Als Read-Engine hinter einem Analytics-Dashboard funktioniert es gut.

Wie sicher ist DuckDB WASM für sensible Daten? Sehr sicher — die Daten verlassen den Browser-Tab nicht. Die WASM-Engine läuft in der Sandbox des Browsers, ohne Backend-Roundtrip. Wenn du DSGVO-relevante Daten lokal explorieren willst, ist das eines der besten Modelle.

Was ist der Unterschied zwischen read_csv und read_csv_auto? read_csv_auto erkennt Spaltentypen automatisch — gut für Exploration. read_csv erwartet explizite Typdefinitionen — die richtige Wahl in produktiven Pipelines, in denen sich Schemas ändern können.

Kann ich DuckDB mit pandas zusammen nutzen? Ja, sehr eng. Du kannst pandas DataFrames direkt mit SQL abfragen (SELECT * FROM df) und Query-Ergebnisse mit .fetchdf() als DataFrame zurückbekommen. Der Wechsel zwischen beiden hat fast keinen Overhead.

Weiterlesen

• Natural Language SQL: Frag deine Daten in normaler Sprache
• Was ist ein Data Catalog? Tools, Trade-offs und wann du einen brauchst
• Self-Service Analytics: Ein praktischer Guide für Data-Teams

Stand: 14. Mai 2026.