# ggsql

The ggsql R package provides rust bindings to the
[ggsql](https://ggsql.org) visualization tool so that you can hook up
readers and writers to it, execute queries, and visualize the result. It
also contain a knitr engine for supporting `ggsql` blocks, with
facilities for bidirectional data flow between R, Python, and ggsql
blocks. This means that you can prepare some data in one block using
dplyr or pandas, and then visualize it with ggsql in a different block
without having to do anything to pass the data around.

## Installation

ggsql can be installed from CRAN with:

``` r

# install.packages("pak")
pak::pak("ggsql")
```

To get the development version, change `"ggsql"` to `"posit-dev/ggsql"`.

## Example

While one of the core appeals of the ggsql R package is the knitr engine
it provides, you can also use it directly in R to execute visual
queries:

``` r

library(ggsql)

# Create an in-memory DuckDB reader
reader <- duckdb_reader()

# Register a dataset in it
ggsql_register(reader, mtcars, "amazing_data")

# Visualize it with a query
ggsql_execute(reader, "
VISUALIZE mpg AS x, disp AS y FROM amazing_data
DRAW point
")
```

![An example plot created with ggsql through the R bindings. The plot
shows a scatterplot of the mtcars dataset with mpg on the x axis and
disp on the y axis](reference/figures/README-unnamed-chunk-2-1.svg)

We could achieve the same in a ggsql code block by referencing an R
dataset directly using the `r:` prefix

``` ggsql
VISUALIZE mpg AS x, disp AS y FROM r:mtcars
DRAW point
LABEL
  title => 'That data came from R 🤯'
```

![An example plot created with ggsql referencing data from the R
session. The plot shows a scatterplot of the mtcars dataset with mpg on
the x axis and disp on the y
axis](reference/figures/README-unnamed-chunk-3-1.svg)

The only thing you need to remember is to load ggsql into R in your
Rmarkdown/Quarto document so the knitr engine is registered.

# Package index

## All functions

- [`custom_reader()`](https://r.ggsql.org/reference/custom_reader.md) :
  Create a reader backed by R callbacks
- [`duckdb_reader()`](https://r.ggsql.org/reference/duckdb_reader.md) :
  Create a DuckDB reader
- [`ggsqlOutput()`](https://r.ggsql.org/reference/ggsqlOutput.md)
  [`renderGgsql()`](https://r.ggsql.org/reference/ggsqlOutput.md) :
  Shiny bindings for ggsql
- [`ggsql_execute()`](https://r.ggsql.org/reference/ggsql_execute.md)
  [`ggsql_execute_sql()`](https://r.ggsql.org/reference/ggsql_execute.md)
  : Execute a ggsql query
- [`ggsql_register()`](https://r.ggsql.org/reference/ggsql_register.md)
  [`ggsql_unregister()`](https://r.ggsql.org/reference/ggsql_register.md)
  [`ggsql_table()`](https://r.ggsql.org/reference/ggsql_register.md)
  [`ggsql_table_names()`](https://r.ggsql.org/reference/ggsql_register.md)
  : Register and unregisters a data frame as a queryable table
- [`ggsql_render()`](https://r.ggsql.org/reference/ggsql_render.md) :
  Render a spec with a writer
- [`ggsql_save()`](https://r.ggsql.org/reference/ggsql_save.md) : Save a
  ggsql spec to a file
- [`ggsql_session_reader()`](https://r.ggsql.org/reference/ggsql_session_reader.md)
  : Set the ggsql reader for the current Shiny session
- [`ggsql_validate()`](https://r.ggsql.org/reference/ggsql_validate.md)
  [`ggsql_has_visual()`](https://r.ggsql.org/reference/ggsql_validate.md)
  [`ggsql_is_valid()`](https://r.ggsql.org/reference/ggsql_validate.md)
  : Validate a ggsql query
- [`ggsql_widget()`](https://r.ggsql.org/reference/ggsql_widget.md) :
  Create a ggsql htmlwidget
- [`odbc_reader()`](https://r.ggsql.org/reference/odbc_reader.md) :
  Create an ODBC reader
- [`snowflake_reader()`](https://r.ggsql.org/reference/snowflake_reader.md)
  : Create a Snowflake reader
- [`ggsql_metadata()`](https://r.ggsql.org/reference/spec_utility.md)
  [`ggsql_sql()`](https://r.ggsql.org/reference/spec_utility.md)
  [`ggsql_visual()`](https://r.ggsql.org/reference/spec_utility.md)
  [`ggsql_layer_count()`](https://r.ggsql.org/reference/spec_utility.md)
  [`ggsql_layer_data()`](https://r.ggsql.org/reference/spec_utility.md)
  [`ggsql_stat_data()`](https://r.ggsql.org/reference/spec_utility.md)
  [`ggsql_layer_sql()`](https://r.ggsql.org/reference/spec_utility.md)
  [`ggsql_stat_sql()`](https://r.ggsql.org/reference/spec_utility.md)
  [`ggsql_warnings()`](https://r.ggsql.org/reference/spec_utility.md) :
  Utility functions for visualization specifications
- [`vegalite_writer()`](https://r.ggsql.org/reference/vegalite_writer.md)
  : Create a Vega-Lite writer

# Articles

### All vignettes

- [The ggsql knitr engine](https://r.ggsql.org/articles/engine.md):

  An introduction to using the ggsql knitr engine in Rmarkdown and
  Quarto

- [Getting started](https://r.ggsql.org/articles/ggsql.md):

  A short introduction to interacting with ggsql from R