From 4c1ee0da3b743e9a8133f1e82488cd430052ef9e Mon Sep 17 00:00:00 2001
From: Niels Pardon <par@zurich.ibm.com>
Date: Wed, 29 Jul 2026 14:56:39 +0200
Subject: [PATCH] docs: introduce the DataFrame API in the README

Add a "Building plans with the DataFrame API" section leading with the
ergonomic `substrait.dataframe` API, and reframe the existing raw
`substrait.proto`/`substrait.builders` examples as the low-level API.

Extracted from #214 so it can land while the full user guide is finalized;
the guide-link paragraph is intentionally omitted until those docs exist.
---
 README.md | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9587aa0d..524d6885 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,38 @@ This project is not an execution engine for Substrait Plans.
 ## Status
 This is an experimental package that is still under development.
 
-# Example
+# Building plans with the DataFrame API
+
+The `substrait.dataframe` module is an ergonomic, fluent API for authoring
+Substrait plans — a Polars/PySpark-style DataFrame with operator-overloaded
+expressions, on top of the lower-level builders. It is the recommended way to
+build plans by hand:
+
+```python
+import substrait.dataframe as sub
+
+plan = (
+    sub.read_named_table("people", {"id": sub.i64, "age": sub.i64, "name": sub.string})
+    .filter(sub.col("age") > 25)
+    .with_columns(adult=sub.col("age") >= 18)
+    .select("id", "name", "adult")
+    .to_plan()
+)
+```
+
+`plan` is a `substrait.proto.Plan` ready to hand to a consumer such as DuckDB or
+DataFusion. Install the `extensions` extra so function overloads resolve against
+the standard Substrait extensions:
+
+```sh
+pip install "substrait[extensions]"
+```
+
+# Example (low-level API)
+
+The examples below construct plans with the raw `substrait.proto` and
+`substrait.builders` layers. For most hand-authored plans, prefer the
+[DataFrame API](#building-plans-with-the-dataframe-api) above.
 
 ## Produce a Substrait Plan
 The ``substrait.proto`` module provides access to the classes