Anatomy of Duck DB for Python Developers

Varun Joshi — Sun, 17 May 2026 01:32:16 +0000

Introduction - SQL without a Server

Pandas is widely used for data analysis and almost every data analyst or even data engineers utilize it for faster analysis with table like data structure called DataFrames.The drawback is that it suffers once the data goes beyond few GB's and spinning up a Postgres or a Redshift is an overkill for quick analysis.Duck DB fills this gap with Zero-setup columnar SQL.

Getting Started - zero config, instant power

DuckDb is an open source OLAP database management system designed for analytics and for running within the same process as the application.
It is lightweight, can work directly with data files in csv, parquet etc without needing a server.

Installation and first query

pip install duckdb - No ports to open, No configuration and No daemon

In-Memory and Persistent Database - Two Operating Modes

In-Memory

When DuckDB connection is created without specifying a file, a database lives entirely in RAM.

import duckdb
con = duckdb.connect()          # or duckdb.connect(':memory:')

All data is stored in RAM and no files are written to disk
Extremely fast reads/writes since there is zero I/O overhead.
Data is completely lost when connection closes.
No file locking or concurrency concerns

Persistent Mode

When the user provides a location DuckDB can write the results to disk in .duckDb format.

con = duckdb.connect('my_database.duckdb')

Tables,Schemas and indexes are persisted.
Uses a columnar storage format with compression and buffered I/O
Only one write connection at a time but multiple read connection are allowed.
Supports WAL(Write Ahead Logging) for crash recovery

Powerful Pattern

DuckDb allows you to mix both modes where user can start with in-memory and attach a persistent database or use copy/export to snapshot in-memory result to disk.

con = duckdb.connect()

#Query a CSV, transform it, save the result to a persistent file
con.execute("""
    COPY(SELECT region, SUM(sales) AS total FROM read_csv('data.csv')
         GROUP BY region
     )
    TO 'results.parquet' (FORMAT PARQUET)
""")

Users gets the speed of In-Memory processing which accelerates the pipeline processing with an option to persist.

Reading files directly --CSV,PARQUET,JSON,Arrow,

Query CSV without loading into memory

Select * from read_csv('data_csv', auto_detect=true);

-Auto detects delimiter, compression and data types
-Handles malformed rows gracefully
-Can read multiple CSVs at once read_csv('data/*.csv')

Parquet

Select * from read_parquet('data.parquet');
--even from S3 directly
Select * from read_parquet('s3://bucket/data/*.parquet');

Exploits column pruning as it only reads columns you need
Leverages row group skipping using Parquet's build in min/max stats
Native support for nested types(structs,list,maps)

JSON/NDJSON

SELECT * FROM read_json('events.ndjson', auto_detect=true);

-AUTO INFERS schema from data
-NDJSON(Newline delimited) streams efficiently line by line
-Can unnest deeply nested JSON fields using DuckDB's json_extract, UNNEST, or -> operators

Apache Arrow

import pyarrow as pa
arrow_table = pa.Table.from_pandas(df)
duckdb.query(""SELECT * from arrow_table""")

-Zero copy integration: DuckDB reads from Arrow memory without serialization
-Ideal for pipelines where data never needs to touch disk

SQL Beyond Select

DuckDB is not just a query engine, it supports rich SQL that covers data transformation, creation, and some genuinely unique syntax extensions to available in most databases.

Full Suite of WINDOW Functions

Select
    customer,
    ordered_at,
    amount,

    -- Running total
    SUM(amount) OVER (PARTITION BY customer ORDER BY ordered_at) AS running_tot,

    -- Lag/lead comparisons
    LAG(amount) OVER (PARTITION BY customer ORDER BY ordered_at) AS prev_amt,

    -- Percentile rank
    PERCENT_RANK() OVER (ORDER BY amount) AS pct_rank,

    -- Named window reuse
    FIRST_VALUE(amount) OVER w AS first_order
FROM orders
WINDOW w AS (PARTITION BY customer ORDER BY ordered_at);

DuckDB also allows the use of qualify clause which filters on window result without a subquery.

Select * From orders
QUALIFY ROW_NUMBER() OVER (PARTITION BY customer ORDER BY amount DESC) = 1;

PIVOT and UNPIVOT

Most databases make you write case when manually for PIVOTS.
DuckDB does it natively.

--PIVOT- rows to columns
PIVOT orders on region USING SUM(amount) GROUP BY year;

--UNPIVOT- Column to rows
UNPIVOT sales_wide ON(q1,q2,q3,q4) INTO NAME quarter VALUE revenue;

MULTI DATABASE SQL

--Attach another DuckDB file
ATTACH 'archive.duckdb' AS archive;

-- Cross-database join
SELECT a.*, b.region
FROM main.orders a
JOIN archive.customers b ON a.customer_id = b.id;

--Attach another database
ATTACH 'postgres://user:pass@host/db' AS pg (TYPE POSTGRES);
SELECT * FROM pg.public.users LIMIT 10;

DUCKDB+Pandas+Polars --Choosing your stack

DuckDB does not replace pandas or Polars it solves a problem which is niche.The sweet spot of the industry is to use DuckDB for SQL-shaped operations and pandas/polars for row level python logic.

Where Duck DB shines

Feature Engineering for ML: Window functions or group by's for feature computation are often faster and more readable in DuckDB then pandas before handing it over to Sklearn or pytorch
Unit testing DBT models locally:DuckDB lets you run complete dbt project locally without a cloud warehouse providing fast feedback loop for data engineers.
Light weight ETL Pipelines: One can read raw parquet from S3, transform with SQL, write cleaned output back without any spark cluster or airflow jobs.

Conclusion

DuckDB lets you think in SQL for analytical tasks without worrying about infrastructure setup. Anyone using python can utilize duckdb for analysis of larger files where regular pandas will give headache.
Given the advantages, it is important to know whare DuckDB should not be used which in case of concurrent writes,OLTP workloads and long running multi user services.

Reference-
https://duckdb.org/docs/current/data/overview