docs: Add docs on how to use Narwhals to generate SQL (#2570)

---------

Co-authored-by: Francesco Bruzzesi <[email protected]>

Author: MarcoGorelli

.github/workflows/mkdocs.yml

@@ -29,6 +29,6 @@ jobs:
           restore-keys: |
             mkdocs-material-
       - name: Install dependencies
-        run: uv pip install -e ".[dask,duckdb,sqlframe]" --group docs --system
+        run: uv pip install -e . --group docs --system
       - name: Deploy docs
         run: mkdocs gh-deploy --force

docs/concepts/order_dependence.md

@@ -25,8 +25,8 @@ no issue.
 import narwhals as nw
 import pandas as pd
 
-df_pd = pd.DataFrame({"a": [1, 3, 4], "i": [0, 1, 2]})
-df = nw.from_native(df_pd)
+data = {"a": [1, 3, 4], "i": [0, 1, 2]}
+df = nw.from_native(pd.DataFrame(data))
 print(df.with_columns(a_cum_sum=nw.col("a").cum_sum()))
 ```
 
@@ -39,13 +39,11 @@ you specify `order_by`. For example:
   or a `LazyFrame`.
 
 ```python exec="1" result="python" session="order_dependence" source="above"
-from sqlframe.duckdb import DuckDBSession
+import polars as pl
 
-session = DuckDBSession()
-sqlframe_df = session.createDataFrame(df_pd)
-lf = nw.from_native(sqlframe_df)
+lf = nw.from_native(pl.LazyFrame(data))
 result = lf.with_columns(a_cum_sum=nw.col("a").cum_sum().over(order_by="i"))
-print(result.collect("pandas"))
+print(result.collect())
 ```
 
 When writing an order-dependent function, if you want it to be executable by `LazyFrame`

docs/generating_sql.md

@@ -0,0 +1,77 @@
+# Generating SQL
+
+Suppose you want to write Polars syntax and translate it to SQL.
+For example, what's the SQL equivalent to:
+
+```python exec="1" source="above" session="generating-sql"
+import narwhals as nw
+from narwhals.typing import IntoFrameT
+
+
+def avg_monthly_price(df_native: IntoFrameT) -> IntoFrameT:
+    return (
+        nw.from_native(df_native)
+        .group_by(nw.col("date").dt.truncate("1mo"))
+        .agg(nw.col("price").mean())
+        .sort("date")
+        .to_native()
+    )
+```
+
+?
+
+There are several ways to find out.
+
+## Via SQLFrame (most lightweight solution)
+
+The most lightweight solution which does not require any heavy dependencies, nor
+any actual table or dataframe, is with SQLFrame.
+
+```python exec="1" source="above" session="generating-sql" result="sql"
+from sqlframe.standalone import StandaloneSession
+
+session = StandaloneSession.builder.getOrCreate()
+session.catalog.add_table("prices", column_mapping={"date": "date", "price": "float"})
+df = nw.from_native(session.read.table("prices"))
+
+print(avg_monthly_price(df).sql(dialect="duckdb"))
+```
+
+Or, to print the SQL code in a different dialect (say, databricks):
+
+```python exec="1" source="above" session="generating-sql" result="sql"
+print(avg_monthly_price(df).sql(dialect="databricks"))
+```
+
+## Via DuckDB
+
+You can also generate SQL directly from DuckDB.
+
+```python exec="1" source="above" session="generating-sql" result="sql"
+import duckdb
+
+conn = duckdb.connect()
+conn.sql("""CREATE TABLE prices (date DATE, price DOUBLE);""")
+
+df = nw.from_native(conn.table("prices"))
+print(avg_monthly_price(df).sql_query())
+```
+
+To make it look a bit prettier, we can pass it to [SQLGlot](https://github.com/tobymao/sqlglot):
+
+```python exec="1" source="above" session="generating-sql" result="sql"
+import sqlglot
+
+print(sqlglot.transpile(avg_monthly_price(df).sql_query(), pretty=True)[0])
+```
+
+## Via Ibis
+
+We can also use Ibis to generate SQL:
+
+```python exec="1" source="above" session="generating-sql" result="sql"
+import ibis
+
+t = ibis.table({"date": "date", "price": "double"}, name="prices")
+print(ibis.to_sql(avg_monthly_price(t)))
+```

mkdocs.yml

@@ -11,6 +11,7 @@ nav:
     - basics/series.md
     - basics/complete_example.md
     - basics/dataframe_conversion.md
+  - Narwhals and SQL: generating_sql.md
   - Concepts:
     - concepts/order_dependence.md
     - concepts/pandas_index.md

pyproject.toml

@@ -78,6 +78,7 @@ docs = [
   "black",  # required by mkdocstrings_handlers
   "jinja2",
   "duckdb",
+  "narwhals[ibis]",
   "markdown-exec[ansi]",
   "mkdocs",
   "mkdocs-autorefs",