From 92b1c73f73b4763772c865ad45561a0e78a795b9 Mon Sep 17 00:00:00 2001 From: Thomas Lin Pedersen Date: Thu, 12 Mar 2026 14:51:49 +0100 Subject: [PATCH 1/2] Add faq --- doc/_quarto.yml | 2 + doc/faq.qmd | 116 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/styles.scss | 15 +++++++ 3 files changed, 133 insertions(+) create mode 100644 doc/faq.qmd diff --git a/doc/_quarto.yml b/doc/_quarto.yml index 27ec54dc..9688d0a3 100644 --- a/doc/_quarto.yml +++ b/doc/_quarto.yml @@ -48,6 +48,8 @@ website: - text: "`LABEL`" href: syntax/clause/label.qmd - examples.qmd + - href: faq.qmd + text: FAQ tools: - icon: github menu: diff --git a/doc/faq.qmd b/doc/faq.qmd new file mode 100644 index 00000000..9a47e2f0 --- /dev/null +++ b/doc/faq.qmd @@ -0,0 +1,116 @@ +--- +title: Frequently Asked Questions +--- + +## Getting Started + +::: {.callout-note collapse="true"} +## What is ggsql? + +ggsql is a SQL extension for declarative data visualization based on Grammar of Graphics principles. It allows you to combine SQL data queries with visualization specifications in a single, composable syntax. + +```ggsql +SELECT date, revenue, region FROM sales +VISUALISE date AS x, revenue AS y, region AS color +DRAW line +``` +::: + +::: {.callout-note collapse="true"} +## How do I install ggsql? + +See the installation instruction in the [Getting started](installation.qmd) tutorial. +::: + +::: {.callout-note collapse="true"} +## Can I use ggsql with my existing database? + +ggsql is built in a modular way so we can gradually add new backends to it. Currently, ggsql works with DuckDB and SQLite, but we are planning on expanding that soon! +::: + +::: {.callout-note collapse="true"} +## Is ggsql just a new frontend for Vegalite + +We have designed ggsql to be modular, both when it comes to the database input and the final rendering. For the first phase of the development we have chosen to use Vegalite as a renderer as it has allowed us to iterate quickly, but we do not envision Vegalite to remain the only, nor default writer in the future. +::: + +## Syntax & Usage + +::: {.callout-note collapse="true"} +## What's the difference between VISUALISE and VISUALIZE? + +Both spellings are supported - use whichever you prefer. The grammar accepts both British (`VISUALISE`) and American (`VISUALIZE`) spellings. +::: + +::: {.callout-note collapse="true"} +## How do I create a multi-layer chart? + +Add multiple `DRAW` clauses to your query. Each `DRAW` creates a new layer: + +```ggsql +SELECT x, y FROM data +VISUALISE x, y +DRAW line MAPPING x AS x, y AS y +DRAW point MAPPING x AS x, y AS y +``` +::: + +::: {.callout-note collapse="true"} +## How do I set axis labels and a title? + +Use the `LABEL` clause: + +```ggsql +SELECT date, revenue FROM sales +VISUALISE date AS x, revenue AS y +DRAW line +LABEL title => 'Sales Over Time', x => 'Date', y => 'Revenue (USD)' +``` +::: + +::: {.callout-note collapse="true"} +## Can I use SQL queries inside the VISUALISE clause + +Some parts of the syntax are passed on directly to the database, such as the `FILTER` and `ORDER BY` clauses in `DRAW`. + +```ggsql +SELECT date, revenue FROM sales +VISUALISE date AS x, revenue AS y +DRAW line +DRAW point + FILTER revenue = max(revenue) +``` +::: + +::: {.callout-note collapse="true"} +## What if I'm working with huge datasets + +ggsql integrates very deeply with the database backends and handle all statistical transformations as SQL queries. This means that if you need to make a histogram of 1 billion observations, you'll only ever fetch the values of each histogram bin, not the full dataset. +::: + +::: {.callout-note collapse="true"} +## Can I make interactive plots + +ggsql does not yet support interactive functionality like tool tips and zooming. This is a point of focus for us and we will rather get the syntax and implementation right than rush to it. +::: + +## Troubleshooting + +::: {.callout-note collapse="true"} +## My dates aren't formatting correctly on the x-axis + +Add `SCALE x VIA date` to tell ggsql to treat the x-axis as temporal data: + +```ggsql +SELECT date, value FROM data +VISUALISE date AS x, value AS y +DRAW line +SCALE x VIA date +``` +::: + +::: {.callout-note collapse="true"} +## How do I report a bug or request a feature? + +Please open an issue on our [GitHub repository](https://github.com/posit-dev/ggsql/issues). +::: diff --git a/doc/styles.scss b/doc/styles.scss index 8848bfbb..fc0ae9d2 100644 --- a/doc/styles.scss +++ b/doc/styles.scss @@ -357,3 +357,18 @@ code { } } } + +// FAQ callouts with brand teal colors +.callout.callout-style-default.callout-note { + border-color: var(--brand-paleteal, #DEF1EB); + border-left-color: var(--brand-teal, #0A9396); + + .callout-icon { + // Transform icon to brand-teal (#0A9396) + filter: brightness(0) saturate(100%) invert(33%) sepia(92%) saturate(458%) hue-rotate(152deg) brightness(93%) contrast(89%); + } + + .callout-header { + background-color: var(--brand-paleteal, #DEF1EB); + } +} From 6ad69a3d46fdbeeddbf91960b0164da512db1729 Mon Sep 17 00:00:00 2001 From: Thomas Lin Pedersen Date: Thu, 12 Mar 2026 15:51:59 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: George Stagg Co-authored-by: Thomas Lin Pedersen --- doc/faq.qmd | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/faq.qmd b/doc/faq.qmd index 9a47e2f0..79e25486 100644 --- a/doc/faq.qmd +++ b/doc/faq.qmd @@ -37,7 +37,7 @@ We have designed ggsql to be modular, both when it comes to the database input a ## Syntax & Usage ::: {.callout-note collapse="true"} -## What's the difference between VISUALISE and VISUALIZE? +## What's the difference between `VISUALISE` and `VISUALIZE`? Both spellings are supported - use whichever you prefer. The grammar accepts both British (`VISUALISE`) and American (`VISUALIZE`) spellings. ::: @@ -69,7 +69,7 @@ LABEL title => 'Sales Over Time', x => 'Date', y => 'Revenue (USD)' ::: ::: {.callout-note collapse="true"} -## Can I use SQL queries inside the VISUALISE clause +## Can I use SQL queries inside the `VISUALISE` clause Some parts of the syntax are passed on directly to the database, such as the `FILTER` and `ORDER BY` clauses in `DRAW`. @@ -80,12 +80,14 @@ DRAW line DRAW point FILTER revenue = max(revenue) ``` + +Further, any query before the `VISUALISE` clause is passed directly to the database so anything supported by your backend can go in there. ::: ::: {.callout-note collapse="true"} ## What if I'm working with huge datasets -ggsql integrates very deeply with the database backends and handle all statistical transformations as SQL queries. This means that if you need to make a histogram of 1 billion observations, you'll only ever fetch the values of each histogram bin, not the full dataset. +ggsql integrates very deeply with the database backends and handles all statistical transformations as SQL queries. This means that if you need to make a histogram of 1 billion observations, you'll only ever fetch the values of each histogram bin, not the full dataset. ::: ::: {.callout-note collapse="true"}