Reference
High-level API
Convenience entry points for common workflows.
- render_altair()
-
Render a DataFrame with a VISUALISE spec to an Altair chart.
- validate()
-
Validate query syntax and semantics without executing SQL.
- execute()
-
Execute a ggsql query using a custom Python reader.
Readers
Execute SQL and manage DataFrames that feed visualizations.
- DuckDBReader
-
DuckDB database reader for executing SQL queries.
Writers
Turn a resolved Spec into rendered output.
- VegaLiteWriter
-
Vega-Lite v6 JSON output writer.
Result types
Objects returned from validate() and reader.execute().
Validated Methods
Methods for the Validated class
- Validated.errors()
-
Validation errors (fatal issues).
- Validated.has_visual()
-
Whether the query contains a VISUALISE clause.
- Validated.sql()
-
The SQL portion (before VISUALISE).
- Validated.valid()
-
Whether the query is valid (no errors).
- Validated.visual()
-
The VISUALISE portion (raw text).
- Validated.warnings()
-
Validation warnings (non-fatal issues).
Spec Methods
Methods for the Spec class
- Spec.data()
-
Get global data (main query result).
- Spec.layer_count()
-
Number of layers.
- Spec.layer_data()
-
Get layer-specific data (from FILTER or FROM clause).
- Spec.layer_sql()
-
Layer filter/source query, or None if using global data.
- Spec.metadata()
-
Get visualization metadata.
- Spec.sql()
-
The main SQL query that was executed.
- Spec.stat_data()
-
Get stat transform data (e.g., histogram bins, density estimates).
- Spec.stat_sql()
-
Stat transform query, or None if no stat transform.
- Spec.visual()
-
The VISUALISE portion (raw text).
- Spec.warnings()
-
Validation warnings from preparation.