DuckDBReader

DuckDB database reader for executing SQL queries.

Usage

DuckDBReader()

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")

Methods

Name Description
__new__() Create and return a new object. See help(type) for accurate signature.
execute() Execute a ggsql query and return the visualization specification.
execute_sql() Execute a SQL query and return the result as a pyarrow Table.
register() Register a pyarrow Table as a queryable table.
unregister() Unregister a previously registered table.

__new__()

Create and return a new object. See help(type) for accurate signature.

Usage

__new__(*args, **kwargs)

execute()

Execute a ggsql query and return the visualization specification.

Usage

execute(query)

This is the main entry point for creating visualizations. It parses the query, executes the SQL portion, and returns a PySpec ready for rendering.

Parameters
query: str
The ggsql query (SQL + VISUALISE clause).
Returns
Spec
The resolved visualization specification ready for rendering.
Raises
ValueError
If the query syntax is invalid, has no VISUALISE clause, or SQL execution fails.
Examples
>>> reader = DuckDBReader("duckdb://memory")
>>> spec = reader.execute("SELECT 1 AS x, 2 AS y VISUALISE x, y DRAW point")
>>> writer = VegaLiteWriter()
>>> json_output = writer.render(spec)

execute_sql()

Execute a SQL query and return the result as a pyarrow Table.

Usage

execute_sql(sql)
Parameters
sql: str
The SQL query to execute.
Returns
pyarrow.Table
The query result as a pyarrow Table.
Raises
ValueError
If the SQL is invalid or execution fails.

register()

Register a pyarrow Table as a queryable table.

Usage

register(name, table, replace=False)

After registration, the table can be queried by name in SQL.

Parameters
name: str

The table name to register under.

table: pyarrow.Table
The Arrow table to register.
Raises
ValueError
If registration fails or the table name is invalid.

unregister()

Unregister a previously registered table.

Usage

unregister(name)
Parameters
name: str
The table name to unregister.
Raises
ValueError
If the table wasn’t registered via this reader or unregistration fails.