duckdb / duckdb/duckdb-web

Proposal: Add an "Integration with Narwhals" page under the Python guides

Open Beginner friendly
#6,958 0 comments 2 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
301
Forks
595
Avg merge
1d 14h
Merged PRs (30d)
62

Description

Hi there 👋🏼

The Python integration guides for Ibis and Polars are two of the most useful pages in the docs for people arriving from the dataframe world. I would like to propose a sibling page, "Integration with Narwhals," written in the same spirit.

## Context

Narwhals supports DuckDB as a first-class lazy backend. You wrap a `duckdb.DuckDBPyRelation` with `nw.from_native`, work against a Polars-style API, and get a DuckDB relation back with `to_native`.

It also occupies a genuinely different niche from the existing two pages, so it documents something new rather than duplicating them:

* Ibis is an end-user dataframe frontend that compiles to SQL, with DuckDB as its default engine.
* The Polars page is about zero-copy data exchange in both directions over Arrow.
* Narwhals is the compatibility layer that tool and library authors use so their projects accept DuckDB relations (and pandas, Polars, PyArrow, and others) without depending on any of them. Altair, for example, routes through Narwhals.

## The reader and DuckDB benefit

For a library author, a few lines of Narwhals turn DuckDB into a supported input for charting, ML, and dashboard tools with no per-backend branching. That quietly expands the set of places where DuckDB relations are accepted across PyData, which is a win for DuckDB adoption that does not require any work on the DuckDB side.

## Suggested shape, mirroring the existing guides

1. Short framing: what Narwhals is, and the important caveat that it targets tool builders rather than end users.
2. Installation: `pip install -U duckdb narwhals`.
3. DuckDB into Narwhals: `nw.from_native` on a relation, lazy semantics, a couple of operations (`filter`, `with_columns`, `group_by` plus `agg`).
4. Back to native: `to_native` returns a DuckDB relation; `collect` materializes (to Polars, pandas, or PyArrow).
5. A short note that support is lazy-only, and that some operations are version dependent in DuckDB.
6. Learn more: links to the Narwhals docs and its API Completeness page.

---

If this is welcome, I am happy to open a PR against `duckdb-web` with a first draft following the structure and tone of the Ibis guide.

Thanks for considering it.

Contributor guide

Open the contributing guide

Research direction

Start by comparing the existing Ibis and Polars Python integration guides to match their structure and tone. Add an “Integration with Narwhals” page covering installation, wrapping and unwrapping DuckDB relations, lazy operations, limitations, and links to Narwhals documentation. Done means the guide explains the proposed examples and caveats clearly for library authors.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.