----------------------------------------------------------------------
This is the API documentation for the ggsql library.
----------------------------------------------------------------------


## High-level API

Convenience entry points for common workflows.


render_altair(df: 'IntoFrame', viz: 'str', *, validate: 'bool' = False, height: 'int | None' = None, width: 'int | None' = None, **kwargs: 'Any') -> 'AltairChart'

Render a DataFrame with a VISUALISE spec to an Altair chart.

Parameters
----------
df
    Data to visualize. Accepts polars, pandas, or any narwhals-compatible
    DataFrame. LazyFrames are collected automatically.
viz
    VISUALISE spec string (e.g., "VISUALISE x, y DRAW point")
validate
    Whether to validate the spec against the Vega-Lite schema.
height
    Chart height in pixels. When ``None`` (the default), the height
    produced by ggsql is used as-is.
width
    Chart width in pixels. When ``None`` (the default), the width
    produced by ggsql is used as-is.
**kwargs
    Additional keyword arguments passed to ``altair.Chart.from_json()``.

Returns
-------
AltairChart
    An Altair chart object (Chart, LayerChart, FacetChart, etc.).

validate(query)

Validate query syntax and semantics without executing SQL.

Parameters
----------
query : str
    The ggsql query to validate.

Returns
-------
Validated
    Validation result with query inspection methods.

Raises
------
ValueError
    If validation fails unexpectedly (not for syntax errors, which are captured).

execute(query, reader)

Execute a ggsql query using a custom Python reader.

This is a convenience function for custom readers. For native readers,
prefer using `reader.execute()` directly.

Parameters
----------
query : str
    The ggsql query to execute.
reader : Reader | object
    The database reader to execute SQL against. Can be a native Reader
    for optimal performance, or any Python object with an
    `execute_sql(sql: str) -> pyarrow.Table` method.

Returns
-------
Spec
    The resolved visualization specification ready for rendering.

Raises
------
ValueError
    If parsing, validation, or SQL execution fails.

Examples
--------
>>> # Using native reader (prefer reader.execute() instead)
>>> reader = DuckDBReader("duckdb://memory")
>>> spec = execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point", reader)
>>> writer = VegaLiteWriter()
>>> json_output = writer.render(spec)

>>> # Using custom Python reader
>>> class MyReader:
...     def execute_sql(self, sql: str) -> pa.Table:
...         return pa.table({"x": [1, 2, 3], "y": [10, 20, 30]})
>>> reader = MyReader()
>>> spec = execute("SELECT * FROM data VISUALISE x, y DRAW point", reader)


## Readers

Execute SQL and manage DataFrames that feed visualizations.


DuckDBReader(connection)

DuckDB database reader for executing SQL queries.

Creates an in-memory or file-based DuckDB connection that can execute
SQL queries and register DataFrames as queryable tables.

Examples
--------
>>> reader = DuckDBReader("duckdb://memory")
>>> table = reader.execute_sql("SELECT 1 as x, 2 as y")

>>> reader = DuckDBReader("duckdb://memory")
>>> reader.register("data", pa.table({"x": [1, 2, 3]}))
>>> table = reader.execute_sql("SELECT * FROM data WHERE x > 1")


## Writers

Turn a resolved Spec into rendered output.


VegaLiteWriter() -> 'None'

Vega-Lite v6 JSON output writer.

Methods
-------
render(spec)
    Render a Spec to a Vega-Lite JSON string.
render_chart(spec, **kwargs)
    Render a Spec to an Altair chart object.


## Result types

Objects returned from `validate()` and `reader.execute()`.


Validated()

Result of validate() - query inspection and validation without SQL execution.

Contains information about query structure and any validation errors/warnings.
The tree() method from Rust is not exposed as it's not useful in Python.

Spec()

Result of reader.execute(), ready for rendering.

Contains the resolved plot specification, data, and metadata.
Use writer.render(spec) to generate output.

Examples
--------
>>> spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
>>> print(f"Rows: {spec.metadata()['rows']}")
>>> writer = VegaLiteWriter()
>>> json_output = writer.render(spec)


## Validated Methods

Methods for the Validated class


errors(self, /)

Validation errors (fatal issues).

Returns
-------
list[dict]
    List of error dictionaries with 'message' and optional 'location' keys.

has_visual(self, /)

Whether the query contains a VISUALISE clause.

Returns
-------
bool
    True if the query has a VISUALISE clause.

sql(self, /)

The SQL portion (before VISUALISE).

Returns
-------
str
    The SQL part of the query.

valid(self, /)

Whether the query is valid (no errors).

Returns
-------
bool
    True if the query is syntactically and semantically valid.

visual(self, /)

The VISUALISE portion (raw text).

Returns
-------
str
    The VISUALISE part of the query.

warnings(self, /)

Validation warnings (non-fatal issues).

Returns
-------
list[dict]
    List of warning dictionaries with 'message' and optional 'location' keys.


## Spec Methods

Methods for the Spec class


data(self, /)

Get global data (main query result).

Returns
-------
pyarrow.Table | None
    The main query result as a pyarrow Table, or None if not available.

layer_count(self, /)

Number of layers.

Returns
-------
int
    The number of DRAW clauses in the visualization.

layer_data(self, /, index)

Get layer-specific data (from FILTER or FROM clause).

Parameters
----------
index : int
    The layer index (0-based).

Returns
-------
pyarrow.Table | None
    The layer-specific data as a pyarrow Table, or None if the layer uses global data.

layer_sql(self, /, index)

Layer filter/source query, or None if using global data.

Parameters
----------
index : int
    The layer index (0-based).

Returns
-------
str | None
    The filter SQL query, or None if the layer uses global data directly.

metadata(self, /)

Get visualization metadata.

Returns
-------
dict
    Dictionary with 'rows', 'columns', and 'layer_count' keys.

sql(self, /)

The main SQL query that was executed.

Returns
-------
str
    The SQL query string.

stat_data(self, /, index)

Get stat transform data (e.g., histogram bins, density estimates).

Parameters
----------
index : int
    The layer index (0-based).

Returns
-------
pyarrow.Table | None
    The stat transform data as a pyarrow Table, or None if no stat transform.

stat_sql(self, /, index)

Stat transform query, or None if no stat transform.

Parameters
----------
index : int
    The layer index (0-based).

Returns
-------
str | None
    The stat transform SQL query, or None if no stat transform.

visual(self, /)

The VISUALISE portion (raw text).

Returns
-------
str
    The VISUALISE clause text.

warnings(self, /)

Validation warnings from preparation.

Returns
-------
list[dict]
    List of warning dictionaries with 'message' and optional 'location' keys.