# ggsql

SQL extension for declarative data visualization


# Installation

``` bash
pip install ggsql
```


# API overview


## High-level API

Convenience entry points for common workflows.

- [render_altair](reference/render_altair.html#ggsql.render_altair): Render a DataFrame with a VISUALISE spec to an Altair chart
- [validate](reference/validate.html#ggsql.validate): Validate query syntax and semantics without executing SQL
- [execute](reference/execute.html#ggsql.execute): Execute a ggsql query using a custom Python reader


## Readers

Execute SQL and manage DataFrames that feed visualizations.

- [DuckDBReader](reference/DuckDBReader.html#ggsql.DuckDBReader): DuckDB database reader for executing SQL queries


## Writers

Turn a resolved Spec into rendered output.

- [VegaLiteWriter](reference/VegaLiteWriter.html#ggsql.VegaLiteWriter): Vega-Lite v6 JSON output writer


## Result types

Objects returned from [validate()](reference/validate.html#ggsql.validate) and `reader.execute()`.

- [Validated](reference/Validated.html#ggsql.Validated): Result of validate() - query inspection and validation without SQL execution
- [Spec](reference/Spec.html#ggsql.Spec): Result of reader.execute(), ready for rendering


## Validated Methods

Methods for the Validated class

- [Validated.errors](reference/Validated.errors.html#ggsql.Validated.errors)
- [Validated.has_visual](reference/Validated.has_visual.html#ggsql.Validated.has_visual)
- [Validated.sql](reference/Validated.sql.html#ggsql.Validated.sql)
- [Validated.valid](reference/Validated.valid.html#ggsql.Validated.valid)
- [Validated.visual](reference/Validated.visual.html#ggsql.Validated.visual)
- [Validated.warnings](reference/Validated.warnings.html#ggsql.Validated.warnings)


## Spec Methods

Methods for the Spec class

- [Spec.data](reference/Spec.data.html#ggsql.Spec.data)
- [Spec.layer_count](reference/Spec.layer_count.html#ggsql.Spec.layer_count)
- [Spec.layer_data](reference/Spec.layer_data.html#ggsql.Spec.layer_data)
- [Spec.layer_sql](reference/Spec.layer_sql.html#ggsql.Spec.layer_sql)
- [Spec.metadata](reference/Spec.metadata.html#ggsql.Spec.metadata)
- [Spec.sql](reference/Spec.sql.html#ggsql.Spec.sql)
- [Spec.stat_data](reference/Spec.stat_data.html#ggsql.Spec.stat_data)
- [Spec.stat_sql](reference/Spec.stat_sql.html#ggsql.Spec.stat_sql)
- [Spec.visual](reference/Spec.visual.html#ggsql.Spec.visual)
- [Spec.warnings](reference/Spec.warnings.html#ggsql.Spec.warnings)


# Resources

- [llms.txt](llms.txt) -- Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) -- Comprehensive documentation for LLMs
- [Source code](https://github.com/posit-dev/ggsql-python)


## Reuse


MIT