Switch from api.prepare() to reader.execute()

Author: georgestagg

CLAUDE.md

@@ -152,28 +152,28 @@ DRAW line MAPPING month AS x, total AS y
 ### Quick Start
 
 ```rust
-use ggsql::{prepare, reader::DuckDBReader, writer::VegaLiteWriter};
+use ggsql::reader::{DuckDBReader, Reader};
+use ggsql::writer::VegaLiteWriter;
 
 // Create a reader
 let reader = DuckDBReader::from_connection_string("duckdb://memory")?;
 
-// Prepare the visualization
-let prepared = ggsql::prepare(
-    "SELECT x, y FROM data VISUALISE x, y DRAW point",
-    &reader
+// Execute the ggsql query
+let spec = reader.execute(
+    "SELECT x, y FROM data VISUALISE x, y DRAW point"
 )?;
 
 // Render to Vega-Lite JSON
 let writer = VegaLiteWriter::new();
-let json = prepared.render(&writer)?;
+let json = spec.render(&writer)?;
 ```
 
 ### Core Functions
 
 | Function                 | Purpose                                                |
 | ------------------------ | ------------------------------------------------------ |
-| `prepare(query, reader)` | Main entry point: parse, execute SQL, resolve mappings |
-| `render(writer)`         | Generate output (Vega-Lite JSON) from prepared data    |
+| `reader.execute(query)`  | Main entry point: parse, execute SQL, resolve mappings |
+| `spec.render(writer)`    | Generate output (Vega-Lite JSON) from Spec             |
 | `validate(query)`        | Validate syntax + semantics, inspect query structure   |
 
 ### Key Types
@@ -188,12 +188,12 @@ let json = prepared.render(&writer)?;
 - `errors()` - Validation errors
 - `warnings()` - Validation warnings
 
-**`Prepared`** - Result of `prepare()`, ready for rendering:
+**`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 preparation
+- `warnings()` - Validation warnings from execution
 - `data()` / `layer_data(i)` / `stat_data(i)` - Access DataFrames
 - `sql()` / `visual()` / `layer_sql(i)` / `stat_sql(i)` - Query introspection
 
@@ -869,7 +869,7 @@ When running in Positron IDE, the extension provides enhanced functionality:
 **Features**:
 
 - PyO3-based Rust bindings compiled to a native Python extension
-- Two-stage API mirroring the Rust API: `prepare()` → `render()`
+- Two-stage API mirroring the Rust API: `reader.execute()` → `render()`
 - DuckDB reader with DataFrame registration
 - Custom Python reader support: any object with `execute_sql(sql) -> DataFrame` method
 - Works with any narwhals-compatible DataFrame (polars, pandas, etc.)
@@ -897,20 +897,19 @@ reader = ggsql.DuckDBReader("duckdb://memory")
 df = pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
 reader.register("data", df)
 
-# Prepare visualization
-prepared = ggsql.prepare(
-    "SELECT * FROM data VISUALISE x, y DRAW point",
-    reader
+# Execute visualization
+spec = reader.execute(
+    "SELECT * FROM data VISUALISE x, y DRAW point"
 )
 
 # Inspect metadata
-print(f"Rows: {prepared.metadata()['rows']}")
-print(f"Columns: {prepared.metadata()['columns']}")
-print(f"SQL: {prepared.sql()}")
+print(f"Rows: {spec.metadata()['rows']}")
+print(f"Columns: {spec.metadata()['columns']}")
+print(f"SQL: {spec.sql()}")
 
 # Render to Vega-Lite JSON
 writer = ggsql.VegaLiteWriter()
-json_output = prepared.render(writer)
+json_output = spec.render(writer)
 ```
 
 **Convenience Function** (`render_altair`):
@@ -943,22 +942,23 @@ print(f"Errors: {validated.errors()}")
 
 **Classes**:
 
-| Class                      | Description                                  |
-| -------------------------- | -------------------------------------------- |
-| `DuckDBReader(connection)` | Database reader with DataFrame registration  |
-| `VegaLiteWriter()`         | Vega-Lite JSON output writer                 |
-| `Validated`                | Result of `validate()` with query inspection |
-| `Prepared`                 | Result of `prepare()`, ready for rendering   |
+| Class                      | Description                                      |
+| -------------------------- | ------------------------------------------------ |
+| `DuckDBReader(connection)` | Database reader with DataFrame registration      |
+| `VegaLiteWriter()`         | Vega-Lite JSON output writer                     |
+| `Validated`                | Result of `validate()` with query inspection     |
+| `Spec`                     | Result of `reader.execute()`, ready for rendering |
 
 **Functions**:
 
-| Function                 | Description                                       |
-| ------------------------ | ------------------------------------------------- |
-| `validate(query)`        | Syntax/semantic validation with query inspection  |
-| `prepare(query, reader)` | Full preparation (reader can be native or custom) |
-| `render_altair(df, viz)` | Convenience: render DataFrame to Altair chart     |
+| Function                   | Description                                       |
+| -------------------------- | ------------------------------------------------- |
+| `validate(query)`          | Syntax/semantic validation with query inspection  |
+| `reader.execute(query)`    | Execute ggsql query, return Spec                  |
+| `execute(query, reader)`   | Execute with custom reader (bridge path)          |
+| `render_altair(df, viz)`   | Convenience: render DataFrame to Altair chart     |
 
-**Prepared Object Methods**:
+**Spec Methods**:
 
 | Method           | Description                                  |
 | ---------------- | -------------------------------------------- |
@@ -988,9 +988,9 @@ class MyReader:
     def execute_sql(self, sql: str) -> pl.DataFrame:
         return pl.DataFrame({"x": [1, 2, 3], "y": [10, 20, 30]})
 
-# Use custom reader with prepare()
+# Use custom reader with ggsql.execute()
 reader = MyReader()
-prepared = ggsql.prepare(
+spec = ggsql.execute(
     "SELECT * FROM data VISUALISE x, y DRAW point",
     reader
 )

ggsql-jupyter/src/executor.rs

@@ -5,7 +5,6 @@
 
 use anyhow::Result;
 use ggsql::{
-    prepare,
     reader::{DuckDBReader, Reader},
     validate,
     writer::VegaLiteWriter,
@@ -69,17 +68,17 @@ impl QueryExecutor {
             return Ok(ExecutionResult::DataFrame(df));
         }
 
-        // 3. Prepare data using the new API
-        let prepared = prepare(code, &self.reader)?;
+        // 3. Execute ggsql query using reader
+        let spec = self.reader.execute(code)?;
 
         tracing::info!(
-            "Data prepared: {} rows, {} layers",
-            prepared.metadata().rows,
-            prepared.metadata().layer_count
+            "Query executed: {} rows, {} layers",
+            spec.metadata().rows,
+            spec.metadata().layer_count
         );
 
         // 4. Render to Vega-Lite
-        let vega_json = prepared.render(&self.writer)?;
+        let vega_json = spec.render(&self.writer)?;
 
         tracing::debug!("Generated Vega-Lite spec: {} chars", vega_json.len());
 

ggsql-python/README.md

@@ -84,30 +84,29 @@ df = pl.DataFrame({
 })
 reader.register("sales", df)
 
-# 3. Prepare the visualization
-prepared = ggsql.prepare(
+# 3. Execute the ggsql query
+spec = reader.execute(
     """
     SELECT * FROM sales
     VISUALISE date AS x, revenue AS y, region AS color
     DRAW line
     LABEL title => 'Sales by Region'
-    """,
-    reader
+    """
 )
 
 # 4. Inspect metadata
-print(f"Rows: {prepared.metadata()['rows']}")
-print(f"Columns: {prepared.metadata()['columns']}")
-print(f"Layers: {prepared.layer_count()}")
+print(f"Rows: {spec.metadata()['rows']}")
+print(f"Columns: {spec.metadata()['columns']}")
+print(f"Layers: {spec.layer_count()}")
 
 # 5. Inspect SQL/VISUALISE portions and data
-print(f"SQL: {prepared.sql()}")
-print(f"Visual: {prepared.visual()}")
-print(prepared.data())  # Returns polars DataFrame
+print(f"SQL: {spec.sql()}")
+print(f"Visual: {spec.visual()}")
+print(spec.data())  # Returns polars DataFrame
 
 # 6. Render to Vega-Lite JSON
 writer = ggsql.VegaLiteWriter()
-vegalite_json = prepared.render(writer)
+vegalite_json = spec.render(writer)
 print(vegalite_json)
 ```
 
@@ -136,7 +135,7 @@ Writer that generates Vega-Lite v6 JSON specifications.
 
 ```python
 writer = ggsql.VegaLiteWriter()
-json_output = prepared.render(writer)
+json_output = spec.render(writer)
 ```
 
 #### `Validated`
@@ -152,9 +151,9 @@ Result of `validate()` containing query analysis without SQL execution.
 - `errors() -> list[dict]` - Validation errors with messages and locations
 - `warnings() -> list[dict]` - Validation warnings
 
-#### `Prepared`
+#### `Spec`
 
-Result of `prepare()`, containing resolved visualization ready for rendering.
+Result of `reader.execute()`, containing resolved visualization ready for rendering.
 
 **Methods:**
 
@@ -168,7 +167,7 @@ Result of `prepare()`, containing resolved visualization ready for rendering.
 - `stat_data(index: int) -> polars.DataFrame | None` - Statistical transform data
 - `layer_sql(index: int) -> str | None` - Layer filter SQL
 - `stat_sql(index: int) -> str | None` - Stat transform SQL
-- `warnings() -> list[dict]` - Validation warnings from preparation
+- `warnings() -> list[dict]` - Validation warnings from execution
 
 ### Functions
 
@@ -185,13 +184,13 @@ else:
         print(f"Error: {error['message']}")
 ```
 
-#### `prepare(query: str, reader: DuckDBReader) -> Prepared`
+#### `reader.execute(query: str) -> Spec`
 
-Parse, validate, and execute a ggsql query.
+Execute a ggsql query and return the visualization specification.
 
 ```python
 reader = ggsql.DuckDBReader("duckdb://memory")
-prepared = ggsql.prepare("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point", reader)
+spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
 ```
 
 #### `render_altair(df, viz: str, **kwargs) -> altair.Chart`
@@ -253,14 +252,14 @@ class CSVReader:
         # A real implementation would parse SQL to determine which file to load
         return pl.read_csv(f"{self.data_dir}/data.csv")
 
-# Use custom reader with prepare()
+# Use custom reader with ggsql.execute()
 reader = CSVReader("/path/to/data")
-prepared = ggsql.prepare(
+spec = ggsql.execute(
     "SELECT * FROM data VISUALISE x, y DRAW point",
     reader
 )
 writer = ggsql.VegaLiteWriter()
-json_output = prepared.render(writer)
+json_output = spec.render(writer)
 ```
 
 **Optional methods** for custom readers:

ggsql-python/python/ggsql/__init__.py

@@ -11,20 +11,20 @@
     DuckDBReader,
     VegaLiteWriter,
     Validated,
-    Prepared,
+    Spec,
     validate,
-    prepare,
+    execute,
 )
 
 __all__ = [
     # Classes
     "DuckDBReader",
     "VegaLiteWriter",
     "Validated",
-    "Prepared",
+    "Spec",
     # Functions
     "validate",
-    "prepare",
+    "execute",
     "render_altair",
 ]
 __version__ = "0.1.0"
@@ -81,10 +81,10 @@ def render_altair(
     # Build full query: SELECT * FROM __data__ + VISUALISE clause
     query = f"SELECT * FROM __data__ {viz}"
 
-    # Prepare and render
-    prepared = prepare(query, reader)
+    # Execute and render
+    spec = reader.execute(query)
     writer = VegaLiteWriter()
-    vegalite_json = prepared.render(writer)
+    vegalite_json = spec.render(writer)
 
     # Parse to determine the correct Altair class
     spec = json.loads(vegalite_json)