execute()

Execute a ggsql query using a custom Python reader.

Usage

execute(
    query,
    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)