Add ibis SQL example

Author: georgestagg

CLAUDE.md

@@ -147,7 +147,7 @@ DRAW line MAPPING month AS x, total AS y
 
 ---
 
-## Public API (`src/api.rs`)
+## Public API
 
 ### Quick Start
 
@@ -190,7 +190,6 @@ let json = writer.render(&spec)?;
 
 **`Spec`** - Result of `reader.execute()`, ready for rendering:
 
-- `render(writer)` - Generate output (Vega-Lite JSON)
 - `plot()` - Resolved plot specification
 - `metadata()` - Rows, columns, layer count
 - `warnings()` - Validation warnings from execution

ggsql-python/README.md

@@ -158,7 +158,6 @@ Result of `reader.execute()`, containing resolved visualization ready for render
 
 **Methods:**
 
-- `render(writer: VegaLiteWriter) -> str` - Generate Vega-Lite JSON
 - `metadata() -> dict` - Get `{"rows": int, "columns": list[str], "layer_count": int}`
 - `sql() -> str` - The executed SQL query
 - `visual() -> str` - The VISUALISE clause
@@ -292,6 +291,53 @@ class AdvancedReader:
 
 Native readers like `DuckDBReader` use an optimized fast path, while custom Python readers are automatically bridged via IPC serialization.
 
+### Ibis Reader Example
+
+[Ibis](https://ibis-project.org/) provides a unified Python API for SQL operations across multiple backends. Here's how to create an ibis-based custom reader:
+
+```python
+import ggsql
+import polars as pl
+import ibis
+
+class IbisReader:
+    """Custom reader using ibis as the SQL backend."""
+
+    def __init__(self, backend="duckdb"):
+        if backend == "duckdb":
+            self.con = ibis.duckdb.connect()
+        elif backend == "sqlite":
+            self.con = ibis.sqlite.connect()
+        # Add other backends as needed
+
+    def execute_sql(self, sql: str) -> pl.DataFrame:
+        return self.con.con.execute(sql).pl()
+
+    def supports_register(self) -> bool:
+        return True
+
+    def register(self, name: str, df: pl.DataFrame) -> None:
+        self.con.create_table(name, df.to_arrow(), overwrite=True)
+
+    def unregister(self, name: str) -> None:
+        self.con.drop_table(name)
+
+# Usage
+reader = IbisReader()
+df = pl.DataFrame({
+    "date": ["2024-01-01", "2024-01-02", "2024-01-03"],
+    "revenue": [100, 150, 120],
+})
+reader.register("sales", df)
+
+spec = ggsql.execute(
+    "SELECT * FROM sales VISUALISE date AS x, revenue AS y DRAW line",
+    reader
+)
+writer = ggsql.VegaLiteWriter()
+print(writer.render(spec))
+```
+
 ## Development
 
 ### Keeping in sync with the monorepo

ggsql-python/tests/test_ggsql.py

@@ -16,6 +16,14 @@
 
 import ggsql
 
+# Optional dependency for ibis test
+try:
+    import ibis
+
+    HAS_IBIS = hasattr(ibis, "duckdb")
+except ImportError:
+    HAS_IBIS = False
+
 
 class TestValidate:
     """Tests for validate() function."""
@@ -496,3 +504,37 @@ def execute_sql(self, sql: str) -> pl.DataFrame:
         assert len(reader.execute_calls) > 0
         # All calls should be valid SQL strings
         assert all(isinstance(sql, str) for sql in reader.execute_calls)
+
+    @pytest.mark.skipif(not HAS_IBIS, reason="ibis not installed")
+    def test_custom_reader_ibis(self):
+        """Test custom reader using ibis as backend."""
+
+        class IbisReader:
+            def __init__(self):
+                self.con = ibis.duckdb.connect()
+
+            def execute_sql(self, sql: str) -> pl.DataFrame:
+                return self.con.con.execute(sql).pl()
+
+            def supports_register(self) -> bool:
+                return True
+
+            def register(self, name: str, df: pl.DataFrame) -> None:
+                self.con.create_table(name, df.to_arrow(), overwrite=True)
+
+            def unregister(self, name: str) -> None:
+                self.con.drop_table(name)
+
+        reader = IbisReader()
+        df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
+        reader.register("mydata", df)
+
+        spec = ggsql.execute(
+            "SELECT * FROM mydata VISUALISE x, y DRAW point",
+            reader,
+        )
+
+        assert spec.metadata()["rows"] == 3
+        writer = ggsql.VegaLiteWriter()
+        json_output = writer.render(spec)
+        assert "point" in json_output

src/doc/API.md

@@ -477,9 +477,6 @@ class Validated:
 
 ```python
 class Spec:
-    def render(self, writer: VegaLiteWriter) -> str:
-        """Render to output format."""
-
     def metadata(self) -> dict:
         """Get metadata as dict with keys: rows, columns, layer_count."""