diff --git a/doc/.gitignore b/doc/.gitignore
index 06fb2886..820772f6 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,4 +1,5 @@
/.quarto/
**/*.quarto_ipynb
+**/*.quarto_ipynb_*
_site
wasm
diff --git a/doc/_quarto.yml b/doc/_quarto.yml
index 5e464b54..c36f9543 100644
--- a/doc/_quarto.yml
+++ b/doc/_quarto.yml
@@ -30,7 +30,8 @@ website:
keyboard-shortcut: []
navbar:
left:
- - get_started.qmd
+ - text: Get started
+ href: get_started/installation.qmd
- text: Syntax
menu:
- text: Overview
@@ -65,54 +66,66 @@ website:
- text: Report a Bug
href: https://github.com/ggsql-dev/ggsql/issues
sidebar:
- id: syntax
- title: Syntax
- style: "floating"
- search: true
- logo: false
- contents:
- - text: Overview
- href: syntax/index.qmd
- - section: "Main clauses"
- contents:
- - text: "`VISUALISE`"
- href: syntax/clause/visualise.qmd
- - text: "`DRAW`"
- href: syntax/clause/draw.qmd
- - text: "`PLACE`"
- href: syntax/clause/place.qmd
- - text: "`SCALE`"
- href: syntax/clause/scale.qmd
- - text: "`FACET`"
- href: syntax/clause/facet.qmd
- - text: "`PROJECT`"
- href: syntax/clause/project.qmd
- - text: "`LABEL`"
- href: syntax/clause/label.qmd
- - section: Layers
- contents:
- - section: Types
- contents:
- - auto: syntax/layer/type/*
- - section: Position adjustment
- contents:
- - auto: syntax/layer/position/*
- - section: Scales
- contents:
- - section: Types
- contents:
- - auto: syntax/scale/type/*
- - section: Aesthetics
- contents:
- - auto: syntax/scale/aesthetic/*
- - section: Coordinate systems
- contents:
- - auto: syntax/coord/*
-
+ - id: syntax
+ title: Syntax
+ style: "floating"
+ search: true
+ logo: false
+ contents:
+ - text: Overview
+ href: syntax/index.qmd
+ - section: "Main clauses"
+ contents:
+ - text: "`VISUALISE`"
+ href: syntax/clause/visualise.qmd
+ - text: "`DRAW`"
+ href: syntax/clause/draw.qmd
+ - text: "`PLACE`"
+ href: syntax/clause/place.qmd
+ - text: "`SCALE`"
+ href: syntax/clause/scale.qmd
+ - text: "`FACET`"
+ href: syntax/clause/facet.qmd
+ - text: "`PROJECT`"
+ href: syntax/clause/project.qmd
+ - text: "`LABEL`"
+ href: syntax/clause/label.qmd
+ - section: Layers
+ contents:
+ - section: Types
+ contents:
+ - auto: syntax/layer/type/*
+ - section: Position adjustment
+ contents:
+ - auto: syntax/layer/position/*
+ - section: Scales
+ contents:
+ - section: Types
+ contents:
+ - auto: syntax/scale/type/*
+ - section: Aesthetics
+ contents:
+ - auto: syntax/scale/aesthetic/*
+ - section: Coordinate systems
+ contents:
+ - auto: syntax/coord/*
+ - id: get_started
+ title: Get started
+ style: "floating"
+ search: false
+ logo: false
+ contents:
+ - text: Installation
+ href: get_started/installation.qmd
+ - text: The first plot
+ href: get_started/first_plot.qmd
+ - text: Grammar of graphics
+ href: get_started/grammar.qmd
format:
html:
lightbox: auto
+ highlight-style: pygments
syntax-definitions:
- ggsql.xml
theme:
diff --git a/doc/examples.qmd b/doc/examples.qmd
deleted file mode 100644
index 1c1d3ffb..00000000
--- a/doc/examples.qmd
+++ /dev/null
@@ -1,781 +0,0 @@
----
-title: Examples
----
-
-This document demonstrates various ggsql features with runnable examples using CSV files.
-
-```{ggsql}
-#| echo: false
-#| output: false
-COPY (
- SELECT * FROM (VALUES
- (5.2, 18.5),
- (8.7, 22.3),
- (12.3, 28.9),
- (15.8, 35.2),
- (19.4, 42.7),
- (23.1, 38.6),
- (26.8, 45.1),
- (30.2, 52.8),
- (33.9, 48.3),
- (37.5, 55.9),
- (41.2, 62.4),
- (44.8, 58.7),
- (48.3, 65.2),
- (52.1, 71.8),
- (55.7, 68.1),
- (59.4, 74.6)
- ) AS t(x, y)
-) TO 'data.csv' (HEADER, DELIMITER ',')
-```
-
-```{ggsql}
-#| echo: false
-#| output: false
-COPY (
- SELECT * FROM (VALUES
- ('2023-01-15'::DATE, 1000.0, 'North', 'Electronics', 5),
- ('2023-02-10'::DATE, 1200.0, 'South', 'Electronics', 8),
- ('2023-03-05'::DATE, 1400.0, 'East', 'Electronics', 7),
- ('2023-04-20'::DATE, 1100.0, 'West', 'Electronics', 6),
- ('2023-05-12'::DATE, 1600.0, 'North', 'Electronics', 9),
- ('2023-06-08'::DATE, 1800.0, 'South', 'Electronics', 10),
- ('2023-07-14'::DATE, 2000.0, 'East', 'Electronics', 11),
- ('2023-08-22'::DATE, 2200.0, 'West', 'Electronics', 12),
- ('2023-09-18'::DATE, 1900.0, 'North', 'Electronics', 8),
- ('2023-10-25'::DATE, 2400.0, 'South', 'Electronics', 14),
- ('2023-11-11'::DATE, 2600.0, 'East', 'Electronics', 15),
- ('2023-12-05'::DATE, 3000.0, 'West', 'Electronics', 16),
- ('2023-01-20'::DATE, 800.0, 'North', 'Clothing', 25),
- ('2023-02-15'::DATE, 900.0, 'South', 'Clothing', 30),
- ('2023-03-10'::DATE, 1100.0, 'East', 'Clothing', 35),
- ('2023-04-25'::DATE, 1300.0, 'West', 'Clothing', 38),
- ('2023-05-18'::DATE, 1500.0, 'North', 'Clothing', 42),
- ('2023-06-12'::DATE, 1700.0, 'South', 'Clothing', 45),
- ('2023-07-20'::DATE, 1900.0, 'East', 'Clothing', 48),
- ('2023-08-28'::DATE, 2100.0, 'West', 'Clothing', 50),
- ('2023-09-22'::DATE, 2300.0, 'North', 'Clothing', 52),
- ('2023-10-30'::DATE, 2500.0, 'South', 'Clothing', 55),
- ('2023-11-15'::DATE, 2700.0, 'East', 'Clothing', 58),
- ('2023-12-10'::DATE, 2900.0, 'West', 'Clothing', 60),
- ('2023-01-25'::DATE, 600.0, 'North', 'Furniture', 3),
- ('2023-02-18'::DATE, 700.0, 'South', 'Furniture', 3),
- ('2023-03-15'::DATE, 850.0, 'East', 'Furniture', 4),
- ('2023-04-28'::DATE, 950.0, 'West', 'Furniture', 4),
- ('2023-05-22'::DATE, 1050.0, 'North', 'Furniture', 5),
- ('2023-06-16'::DATE, 1150.0, 'South', 'Furniture', 5),
- ('2023-07-24'::DATE, 1250.0, 'East', 'Furniture', 5),
- ('2023-08-30'::DATE, 1350.0, 'West', 'Furniture', 6),
- ('2023-09-26'::DATE, 1450.0, 'North', 'Furniture', 6),
- ('2023-10-31'::DATE, 1550.0, 'South', 'Furniture', 6),
- ('2023-11-20'::DATE, 1650.0, 'East', 'Furniture', 7),
- ('2023-12-15'::DATE, 1750.0, 'West', 'Furniture', 7)
- ) AS t(sale_date, revenue, region, category, quantity)
-) TO 'sales.csv' (HEADER, DELIMITER ',')
-```
-
-```{ggsql}
-#| echo: false
-#| output: false
-COPY (
- SELECT * FROM (VALUES
- ('2023-01-01'::DATE, 100.0),
- ('2023-01-08'::DATE, 110.0),
- ('2023-01-15'::DATE, 105.0),
- ('2023-01-22'::DATE, 115.0),
- ('2023-01-29'::DATE, 120.0),
- ('2023-02-05'::DATE, 118.0),
- ('2023-02-12'::DATE, 125.0),
- ('2023-02-19'::DATE, 130.0),
- ('2023-02-26'::DATE, 128.0),
- ('2023-03-05'::DATE, 135.0),
- ('2023-03-12'::DATE, 142.0),
- ('2023-03-19'::DATE, 138.0),
- ('2023-03-26'::DATE, 145.0),
- ('2023-04-02'::DATE, 150.0),
- ('2023-04-09'::DATE, 148.0),
- ('2023-04-16'::DATE, 155.0),
- ('2023-04-23'::DATE, 160.0),
- ('2023-04-30'::DATE, 158.0),
- ('2023-05-07'::DATE, 165.0),
- ('2023-05-14'::DATE, 170.0)
- ) AS t(date, value)
-) TO 'timeseries.csv' (HEADER, DELIMITER ',')
-```
-
-```{ggsql}
-#| echo: false
-#| output: false
-COPY (
- SELECT * FROM (VALUES
- ('2023-01-01'::DATE, 45.2, 'Sales'),
- ('2023-02-01'::DATE, 52.1, 'Sales'),
- ('2023-03-01'::DATE, 48.7, 'Sales'),
- ('2023-04-01'::DATE, 58.3, 'Sales'),
- ('2023-05-01'::DATE, 62.5, 'Sales'),
- ('2023-06-01'::DATE, 67.8, 'Sales'),
- ('2023-07-01'::DATE, 71.2, 'Sales'),
- ('2023-08-01'::DATE, 75.6, 'Sales'),
- ('2023-09-01'::DATE, 80.1, 'Sales'),
- ('2023-10-01'::DATE, 85.4, 'Sales'),
- ('2023-11-01'::DATE, 90.2, 'Sales'),
- ('2023-12-01'::DATE, 95.8, 'Sales'),
- ('2023-01-01'::DATE, 120.5, 'Marketing'),
- ('2023-02-01'::DATE, 135.2, 'Marketing'),
- ('2023-03-01'::DATE, 128.9, 'Marketing'),
- ('2023-04-01'::DATE, 142.3, 'Marketing'),
- ('2023-05-01'::DATE, 155.7, 'Marketing'),
- ('2023-06-01'::DATE, 148.2, 'Marketing'),
- ('2023-07-01'::DATE, 162.8, 'Marketing'),
- ('2023-08-01'::DATE, 175.4, 'Marketing'),
- ('2023-09-01'::DATE, 168.9, 'Marketing'),
- ('2023-10-01'::DATE, 182.5, 'Marketing'),
- ('2023-11-01'::DATE, 195.1, 'Marketing'),
- ('2023-12-01'::DATE, 188.7, 'Marketing'),
- ('2023-01-01'::DATE, 78.3, 'Support'),
- ('2023-02-01'::DATE, 82.1, 'Support'),
- ('2023-03-01'::DATE, 75.6, 'Support'),
- ('2023-04-01'::DATE, 85.9, 'Support'),
- ('2023-05-01'::DATE, 92.4, 'Support'),
- ('2023-06-01'::DATE, 88.7, 'Support'),
- ('2023-07-01'::DATE, 95.2, 'Support'),
- ('2023-08-01'::DATE, 101.8, 'Support'),
- ('2023-09-01'::DATE, 97.5, 'Support'),
- ('2023-10-01'::DATE, 105.3, 'Support'),
- ('2023-11-01'::DATE, 112.6, 'Support'),
- ('2023-12-01'::DATE, 108.9, 'Support')
- ) AS t(date, value, category)
-) TO 'metrics.csv' (HEADER, DELIMITER ',')
-```
-
-## Basic Visualizations
-
-### Simple Scatter Plot
-
-```{ggsql}
-SELECT x, y FROM 'data.csv'
-VISUALISE x, y
-DRAW point
-```
-
-```{ggsql}
-VISUALISE bill_len AS x, bill_dep AS y, species AS color FROM ggsql:penguins
-DRAW point
-```
-
-### Line Chart with Date Scale
-
-```{ggsql}
-SELECT sale_date, revenue FROM 'sales.csv'
-WHERE category = 'Electronics'
-VISUALISE sale_date AS x, revenue AS y
-DRAW line
-SCALE x VIA date
-LABEL
- title => 'Electronics Revenue Over Time',
- x => 'Date',
- y => 'Revenue ($)'
-```
-
-```{ggsql}
-SELECT * FROM ggsql:airquality
-VISUALISE Date AS x
-DRAW line MAPPING Ozone AS y, 'Ozone' AS color
-DRAW line MAPPING Temp AS y, 'Temp' AS color
-```
-
-### Bar Chart by Category
-
-```{ggsql}
-SELECT category, SUM(revenue) as total
-FROM 'sales.csv'
-GROUP BY category
-VISUALISE category AS x, total AS y, category AS fill
-DRAW bar
-LABEL
- title => 'Total Revenue by Category',
- x => 'Category',
- y => 'Total Revenue ($)'
-```
-
-### Line chart with multiple lines with same aesthetics
-
-```{ggsql}
-SELECT * FROM 'sales.csv'
-VISUALISE sale_date AS x, revenue AS y
-DRAW line
- PARTITION BY category
-```
-
-## Statistical Transformations
-
-Statistical transformations automatically compute aggregations for certain geom types.
-
-### Histogram
-
-When using `DRAW histogram`, ggsql automatically bins continuous data and counts occurrences. You only need to specify the x aesthetic:
-
-```{ggsql}
-SELECT revenue FROM 'sales.csv'
-VISUALISE revenue AS x
-DRAW histogram
-LABEL
- title => 'Revenue Distribution',
- x => 'Revenue ($)',
- y => 'Count'
-```
-
-### Bar with Automatic Count
-
-When using `DRAW bar` without a y aesthetic, ggsql automatically counts occurrences of each x value:
-
-```{ggsql}
-SELECT category FROM 'sales.csv'
-VISUALISE category AS x
-DRAW bar
-LABEL
- title => 'Sales Count by Category',
- x => 'Category',
- y => 'Count'
-```
-
-### Bar with Weighted Count
-
-You can also specify a weight aesthetic to sum values instead of counting:
-
-```{ggsql}
-SELECT category, revenue FROM 'sales.csv'
-VISUALISE category AS x, revenue AS weight
-DRAW bar
-LABEL
- title => 'Total Revenue by Category',
- x => 'Category',
- y => 'Revenue ($)'
-```
-
-### Histogram Settings
-
-Control histogram binning with `SETTING` options:
-
-**Custom number of bins:**
-
-```{ggsql}
-SELECT revenue FROM 'sales.csv'
-VISUALISE revenue AS x
-DRAW histogram
- SETTING bins => 10
-LABEL
- title => 'Revenue Distribution (10 bins)',
- x => 'Revenue ($)',
- y => 'Count'
-```
-
-**Explicit bin width** (overrides bins):
-
-```{ggsql}
-SELECT revenue FROM 'sales.csv'
-VISUALISE revenue AS x
-DRAW histogram
- SETTING binwidth => 500
-LABEL
- title => 'Revenue Distribution (500 bin width)',
- x => 'Revenue ($)',
- y => 'Count'
-```
-
-**Left-closed intervals** (default is right-closed `(a, b]`):
-
-```{ggsql}
-SELECT revenue FROM 'sales.csv'
-VISUALISE revenue AS x
-DRAW histogram
- SETTING bins => 8, closed => 'left'
-LABEL
- title => 'Revenue Distribution (left-closed intervals)',
- x => 'Revenue ($)',
- y => 'Count'
-```
-
-### Histogram Remapping
-
-Histogram computes several statistics: `bin`, `bin_end`, `count`, and `density`. By default, `count` is mapped to `y`. Use `REMAPPING` to show density (proportion) instead:
-
-```{ggsql}
-SELECT revenue FROM 'sales.csv'
-VISUALISE revenue AS x
-DRAW histogram
- REMAPPING density AS y
-LABEL
- title => 'Revenue Density Distribution',
- x => 'Revenue ($)',
- y => 'Density'
-```
-
-### Bar Width Setting
-
-Control bar width with the `width` setting (0-1 scale, default 0.9):
-
-```{ggsql}
-SELECT category FROM 'sales.csv'
-VISUALISE category AS x
-DRAW bar
- SETTING width => 0.5
-LABEL
- title => 'Sales Count (Narrow Bars)',
- x => 'Category',
- y => 'Count'
-```
-
-### Bar Remapping
-
-Bar computes `count` and `proportion` statistics. By default, `count` is mapped to `y`. Use `REMAPPING` to show proportions instead:
-
-```{ggsql}
-SELECT category FROM 'sales.csv'
-VISUALISE category AS x
-DRAW bar
- REMAPPING proportion AS y
-LABEL
- title => 'Sales Proportion by Category',
- x => 'Category',
- y => 'Proportion'
-```
-
-Combine with `weight` to show weighted proportions:
-
-```{ggsql}
-SELECT category, revenue FROM 'sales.csv'
-VISUALISE category AS x, revenue AS weight
-DRAW bar
- REMAPPING proportion AS y
-LABEL
- title => 'Revenue Share by Category',
- x => 'Category',
- y => 'Share of Total Revenue'
-```
-
-## Multiple Layers
-
-### Line with Points
-
-```{ggsql}
-SELECT date, value FROM 'timeseries.csv'
-VISUALISE date AS x, value AS y
-DRAW line
- SETTING color => 'blue'
-DRAW point
- SETTING size => 6, color => 'red'
-SCALE x VIA date
-LABEL
- title => 'Time Series with Points',
- x => 'Date',
- y => 'Value'
-```
-
-### Colored Lines by Category
-
-```{ggsql}
-SELECT date, value, category FROM 'metrics.csv'
-VISUALISE date AS x, value AS y, category AS color
-DRAW line
-SCALE x VIA date
-LABEL
- title => 'Metrics by Category',
- x => 'Date',
- y => 'Value'
-```
-
-## Faceting
-
-### Facet by Region
-
-```{ggsql}
-SELECT sale_date, revenue, region FROM 'sales.csv'
-WHERE category = 'Electronics'
-VISUALISE sale_date AS x, revenue AS y
-DRAW line
-SCALE x VIA date
-FACET region
-LABEL
- title => 'Electronics Sales by Region',
- x => 'Date',
- y => 'Revenue ($)'
-```
-
-### Facet Grid
-
-```{ggsql}
-SELECT
- DATE_TRUNC('month', sale_date) as month,
- region,
- category,
- SUM(revenue) as total_revenue,
- SUM(quantity) * 100 as total_quantity_scaled
-FROM 'sales.csv'
-GROUP BY DATE_TRUNC('month', sale_date), region, category
-VISUALISE month AS x
-DRAW line
- MAPPING total_revenue AS y
- SETTING color => 'steelblue'
-DRAW point
- MAPPING total_revenue AS y
- SETTING size => 6, color => 'darkblue'
-DRAW line
- MAPPING total_quantity_scaled AS y
- SETTING color => 'coral'
-DRAW point
- MAPPING total_quantity_scaled AS y
- SETTING size => 6, color => 'orangered'
-SCALE x VIA date
-FACET region BY category
-LABEL
- title => 'Monthly Revenue and Quantity by Region and Category',
- x => 'Month',
- y => 'Value'
-```
-
-## Projections
-
-### Pie Chart with Polar Coordinates
-
-```{ggsql}
-SELECT category, SUM(revenue) as total
-FROM 'sales.csv'
-GROUP BY category
-VISUALISE total AS y, category AS fill
-DRAW bar
-PROJECT y, x TO polar
-LABEL
- title => 'Revenue Distribution by Category'
-```
-
-## Constant Mappings
-
-Constants can be used in both the VISUALISE clause (global) and MAPPING clauses (per-layer) to set fixed aesthetic values.
-
-### Different Constants Per Layer
-
-Each layer can have its own constant value, creating a legend showing all values:
-
-```{ggsql}
-WITH monthly AS (
- SELECT
- DATE_TRUNC('month', sale_date) as month,
- category,
- SUM(revenue) as revenue
- FROM 'sales.csv'
- GROUP BY DATE_TRUNC('month', sale_date), category
-)
-VISUALISE month AS x, revenue AS y
-DRAW line
- MAPPING 'Electronics' AS color FROM monthly
- FILTER category = 'Electronics'
-DRAW line
- MAPPING 'Clothing' AS color FROM monthly
- FILTER category = 'Clothing'
-DRAW line
- MAPPING 'Furniture' AS color FROM monthly
- FILTER category = 'Furniture'
-SCALE x VIA date
-LABEL
- title => 'Revenue by Category (Constant Colors)',
- x => 'Month',
- y => 'Revenue ($)'
-```
-
-### Mixed Constants and Columns
-
-When mixing constant and column mappings for the same aesthetic, the axis/legend label uses the first non-constant column name:
-
-```{ggsql}
-SELECT date, value, category FROM 'metrics.csv'
-VISUALISE date AS x
-DRAW line
- MAPPING value AS y, category AS color
-DRAW point
- MAPPING 120 AS y
- SETTING size => 3, color => 'blue'
-SCALE x VIA date
-LABEL
- title => 'Metrics with Threshold Line',
- x => 'Date'
-```
-
-### Numeric Constants
-
-Numbers work as constants too:
-
-```{ggsql}
-SELECT x, y FROM 'data.csv'
-VISUALISE x, y
-DRAW point
- SETTING color => 'blue', size => 10
-DRAW point
- SETTING color => 'red', size => 5
- FILTER y > 50
-LABEL
- title => 'Scatter Plot with Constant Sizes'
-```
-
-## Layer filtering
-
-### Filter one layer
-
-```{ggsql}
-SELECT date, value FROM 'timeseries.csv'
-VISUALISE date AS x, value AS y
-DRAW line
- SETTING color => 'blue'
-DRAW point
- SETTING color => 'red', size => 6
- FILTER value < 130
-SCALE x VIA date
-LABEL
- title => 'Time Series with Points',
- x => 'Date',
- y => 'Value'
-```
-
-## Layer ordering
-
-### ORDER BY in a layer
-
-Use `ORDER BY` to ensure data is sorted correctly within a layer. This is especially important for line charts where the order of points affects the visual path:
-
-```{ggsql}
-WITH unordered_data AS (
- SELECT * FROM (VALUES
- (150.0, '2023-03-01'::DATE),
- (100.0, '2023-01-01'::DATE),
- (120.0, '2023-05-01'::DATE),
- (200.0, '2023-02-01'::DATE),
- (180.0, '2023-04-01'::DATE)
- ) AS t(value, date)
-)
-VISUALISE
-DRAW path
- MAPPING date AS x, value AS y FROM unordered_data
- ORDER BY date
-DRAW point
- MAPPING date AS x, value AS y FROM unordered_data
- SETTING size => 6, color => 'red'
-SCALE x VIA date
-LABEL
- title => 'Line Chart with ORDER BY',
- x => 'Date',
- y => 'Value'
-```
-
-### Combining FILTER and ORDER BY
-
-The `ORDER BY` clause can be combined with `FILTER` and other layer options:
-
-```{ggsql}
-SELECT date, value, category FROM 'metrics.csv'
-VISUALISE
-DRAW path
- MAPPING date AS x, value AS y, category AS color
- FILTER category != 'Support'
- ORDER BY value
-DRAW point
- MAPPING date AS x, value AS y, category AS color
- SETTING size => 3
- FILTER category != 'Support'
-SCALE x VIA date
-LABEL
- title => 'Sales and Marketing Metrics (Ordered)',
- x => 'Date',
- y => 'Value'
-```
-
-## Common Table Expressions (CTEs)
-
-### Simple CTE with VISUALISE FROM
-
-```{ggsql}
-WITH monthly_sales AS (
- SELECT
- DATE_TRUNC('month', sale_date) as month,
- SUM(revenue) as total_revenue
- FROM 'sales.csv'
- GROUP BY DATE_TRUNC('month', sale_date)
-)
-VISUALISE month AS x, total_revenue AS y FROM monthly_sales
-DRAW line
-DRAW point
-SCALE x VIA date
-LABEL
- title => 'Monthly Revenue Trends',
- x => 'Month',
- y => 'Revenue ($)'
-```
-
-### Multiple CTEs
-
-```{ggsql}
-WITH daily_sales AS (
- SELECT sale_date, region, SUM(revenue) as revenue
- FROM 'sales.csv'
- GROUP BY sale_date, region
-),
-regional_totals AS (
- SELECT region, SUM(revenue) as total
- FROM daily_sales
- GROUP BY region
-)
-VISUALISE region AS x, total AS y, region AS fill FROM regional_totals
-DRAW bar
-PROJECT y, x TO cartesian
-LABEL
- title => 'Total Revenue by Region',
- x => 'Region',
- y => 'Total Revenue ($)'
-```
-
-## Layer-Specific Data Sources (MAPPING FROM)
-
-Layers can pull data from different sources using `MAPPING FROM`. This enables overlaying data from different CTEs or tables.
-
-### Comparing Actuals vs Targets
-
-Each layer can reference a different CTE using `MAPPING ... FROM cte_name`:
-
-```{ggsql}
-WITH actuals AS (
- SELECT
- DATE_TRUNC('month', sale_date) as month,
- SUM(revenue) as value
- FROM 'sales.csv'
- GROUP BY DATE_TRUNC('month', sale_date)
-),
-targets AS (
- SELECT * FROM (VALUES
- ('2023-01-01'::DATE, 5000.0),
- ('2023-02-01'::DATE, 5500.0),
- ('2023-03-01'::DATE, 6000.0),
- ('2023-04-01'::DATE, 6500.0),
- ('2023-05-01'::DATE, 7000.0),
- ('2023-06-01'::DATE, 7500.0),
- ('2023-07-01'::DATE, 8000.0),
- ('2023-08-01'::DATE, 8500.0),
- ('2023-09-01'::DATE, 9000.0),
- ('2023-10-01'::DATE, 9500.0),
- ('2023-11-01'::DATE, 10000.0),
- ('2023-12-01'::DATE, 10500.0)
- ) AS t(month, value)
-)
-VISUALISE
-DRAW line
- MAPPING month AS x, value AS y, 'Actual' AS color FROM actuals
-DRAW point
- MAPPING month AS x, value AS y, 'Actual' AS color FROM actuals
- SETTING size => 6
-DRAW line
- MAPPING month AS x, value AS y, 'Target' AS color FROM targets
-SCALE x VIA date
-LABEL
- title => 'Revenue: Actual vs Target',
- x => 'Month',
- y => 'Revenue ($)'
-```
-
-### CTE Chain: Raw → Filtered → Aggregated
-
-CTEs can reference other CTEs, creating a data transformation pipeline:
-
-```{ggsql}
-WITH raw_data AS (
- SELECT sale_date, revenue, category, region
- FROM 'sales.csv'
-),
-electronics_only AS (
- SELECT * FROM raw_data
- WHERE category = 'Electronics'
-),
-monthly_electronics AS (
- SELECT
- DATE_TRUNC('month', sale_date) as month,
- region,
- SUM(revenue) as total
- FROM electronics_only
- GROUP BY DATE_TRUNC('month', sale_date), region
-)
-VISUALISE month AS x, total AS y, region AS color FROM monthly_electronics
-DRAW line
-DRAW point
-SCALE x VIA date
-LABEL
- title => 'Electronics Revenue by Region (CTE Chain)',
- x => 'Month',
- y => 'Revenue ($)'
-```
-
-### Layer FROM with FILTER
-
-Combine `FROM` with `FILTER` to get filtered subsets from a CTE:
-
-```{ggsql}
-WITH all_sales AS (
- SELECT
- DATE_TRUNC('month', sale_date) as month,
- category,
- SUM(revenue) as revenue
- FROM 'sales.csv'
- GROUP BY DATE_TRUNC('month', sale_date), category
-)
-VISUALISE
-DRAW line
- MAPPING month AS x, revenue AS y, 'All Categories' AS color FROM all_sales
-DRAW line
- MAPPING month AS x, revenue AS y, 'Electronics' AS color FROM all_sales
- FILTER category = 'Electronics'
-DRAW line
- MAPPING month AS x, revenue AS y, 'Clothing' AS color FROM all_sales
- FILTER category = 'Clothing'
-SCALE x VIA date
-LABEL
- title => 'Revenue by Category (Filtered Layers)',
- x => 'Month',
- y => 'Revenue ($)'
-```
-
-## Advanced Examples
-
-### Complete Regional Sales Analysis
-
-```{ggsql}
-SELECT
- sale_date,
- region,
- SUM(quantity) as total_quantity
-FROM 'sales.csv'
-WHERE sale_date >= '2023-01-01'
-GROUP BY sale_date, region
-ORDER BY sale_date
-VISUALISE sale_date AS x, total_quantity AS y, region AS color
-DRAW line
-DRAW point
-SCALE x VIA date
-FACET region
-LABEL
- title => 'Sales Trends by Region',
- x => 'Date',
- y => 'Total Quantity'
-```
-
-### Multi-Category Analysis
-
-```{ggsql}
-SELECT
- category,
- region,
- SUM(revenue) as total_revenue
-FROM 'sales.csv'
-GROUP BY category, region
-VISUALISE category AS x, total_revenue AS y, region AS fill
-DRAW bar
-LABEL
- title => 'Revenue by Category and Region',
- x => 'Category',
- y => 'Revenue ($)'
-```
diff --git a/doc/faq.qmd b/doc/faq.qmd
index 20a3488a..2f28372b 100644
--- a/doc/faq.qmd
+++ b/doc/faq.qmd
@@ -1,8 +1,8 @@
---
-title: Frequently Asked Questions
+title: Frequently asked questions
---
-## Getting Started
+## Getting started
::: {.callout-note collapse="true"}
## What is ggsql?
@@ -19,7 +19,7 @@ DRAW line
::: {.callout-note collapse="true"}
## How do I install ggsql?
-See the installation instruction in the [Getting started](get_started.qmd) tutorial.
+See the installation instruction in the [Get started](get_started/installation.qmd) tutorial.
:::
::: {.callout-note collapse="true"}
@@ -34,7 +34,7 @@ ggsql is built in a modular way so we can gradually add new backends to it. Curr
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
+## Syntax & usage
::: {.callout-note collapse="true"}
## What's the difference between `VISUALISE` and `VISUALIZE`?
diff --git a/doc/gallery/examples/bar-chart.qmd b/doc/gallery/examples/bar-chart.qmd
index 42ab2382..8dba452c 100644
--- a/doc/gallery/examples/bar-chart.qmd
+++ b/doc/gallery/examples/bar-chart.qmd
@@ -1,5 +1,5 @@
---
-title: "Bar Chart"
+title: "Bar chart"
description: "Categorical comparisons using bars"
image: thumbnails/bar-chart.svg
categories: [basic, bar]
@@ -31,7 +31,7 @@ LABEL
## Variations
-### Horizontal Bars
+### Horizontal bars
Use `PROJECT y, x TO cartesian` to flip the axes for horizontal bars:
@@ -47,7 +47,7 @@ LABEL
y => 'Count'
```
-### Auto-Count Bar Chart
+### Auto-count bar chart
When you don't specify a y aesthetic, ggsql automatically counts occurrences:
diff --git a/doc/gallery/examples/faceted.qmd b/doc/gallery/examples/faceted.qmd
index 84e204c2..c06d5f94 100644
--- a/doc/gallery/examples/faceted.qmd
+++ b/doc/gallery/examples/faceted.qmd
@@ -1,5 +1,5 @@
---
-title: "Faceted Plot"
+title: "Faceted plot"
description: "Small multiples showing data split by category"
image: thumbnails/faceted.svg
categories: [faceted, advanced]
@@ -29,7 +29,7 @@ LABEL
## Variations
-### Grid Layout with Two Variables
+### Grid layout with two variables
Use `FACET rows BY cols` to create a grid layout:
@@ -44,7 +44,7 @@ LABEL
y => 'Bill Depth (mm)'
```
-### Free Scales
+### Free scales
Allow each facet to have independent axis scales with `SETTING free`:
diff --git a/doc/gallery/examples/histogram.qmd b/doc/gallery/examples/histogram.qmd
index b2479317..256650dc 100644
--- a/doc/gallery/examples/histogram.qmd
+++ b/doc/gallery/examples/histogram.qmd
@@ -28,7 +28,7 @@ LABEL
## Variations
-### Custom Bin Count
+### Custom bin count
Control the number of bins with `SETTING bins`:
@@ -43,7 +43,7 @@ LABEL
y => 'Count'
```
-### Custom Bin Width
+### Custom bin width
Set explicit bin width instead of count:
@@ -58,7 +58,7 @@ LABEL
y => 'Count'
```
-### Density Instead of Count
+### Density instead of count
Use `REMAPPING` to show density (proportion) instead of count:
diff --git a/doc/gallery/examples/line-chart.qmd b/doc/gallery/examples/line-chart.qmd
index e988113b..d398c755 100644
--- a/doc/gallery/examples/line-chart.qmd
+++ b/doc/gallery/examples/line-chart.qmd
@@ -1,5 +1,5 @@
---
-title: "Line Chart"
+title: "Line chart"
description: "Time series visualization with proper date scaling"
image: thumbnails/line-chart.svg
categories: [basic, line, time-series]
@@ -31,7 +31,7 @@ LABEL
## Variations
-### Multiple Lines by Category
+### Multiple lines by category
```{ggsql}
SELECT Date, Temp, Month FROM ggsql:airquality
diff --git a/doc/gallery/examples/multi-layer.qmd b/doc/gallery/examples/multi-layer.qmd
index b0a4924f..0d7f9c69 100644
--- a/doc/gallery/examples/multi-layer.qmd
+++ b/doc/gallery/examples/multi-layer.qmd
@@ -1,5 +1,5 @@
---
-title: "Multi-Layer Plot"
+title: "Multi-layer plot"
description: "Combining multiple geometric layers in one visualization"
image: thumbnails/multi-layer.svg
categories: [layers, advanced]
@@ -33,7 +33,7 @@ LABEL
## Variations
-### Different Aesthetics Per Layer
+### Different aesthetics per layer
Each layer can have its own aesthetic mappings using `MAPPING`:
@@ -51,7 +51,7 @@ LABEL
y => 'Value'
```
-### Layers from Different Data Sources
+### Layers from different data sources
Use `MAPPING ... FROM` to pull each layer from different CTEs:
diff --git a/doc/gallery/examples/scatterplot.qmd b/doc/gallery/examples/scatterplot.qmd
index e3d59100..85249711 100644
--- a/doc/gallery/examples/scatterplot.qmd
+++ b/doc/gallery/examples/scatterplot.qmd
@@ -1,5 +1,5 @@
---
-title: "Scatter Plot"
+title: "Scatter plot"
description: "Basic scatter plot mapping two numeric variables to position"
image: thumbnails/scatterplot.svg
categories: [basic, point]
@@ -28,7 +28,7 @@ LABEL
## Variations
-### With Color by Species
+### With color by species
```{ggsql}
VISUALISE bill_len AS x, bill_dep AS y, species AS color FROM ggsql:penguins
diff --git a/doc/gallery/examples/thumbnails/bar-chart.svg b/doc/gallery/examples/thumbnails/bar-chart.svg
index 19dfe657..f664c45f 100644
--- a/doc/gallery/examples/thumbnails/bar-chart.svg
+++ b/doc/gallery/examples/thumbnails/bar-chart.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/doc/gallery/index.qmd b/doc/gallery/index.qmd
index 5acd6f8a..41e4824e 100644
--- a/doc/gallery/index.qmd
+++ b/doc/gallery/index.qmd
@@ -1,5 +1,5 @@
---
-title: Example Gallery
+title: Example gallery
listing:
contents: examples
type: grid
diff --git a/doc/get_started.qmd b/doc/get_started.qmd
deleted file mode 100644
index 7cdd4618..00000000
--- a/doc/get_started.qmd
+++ /dev/null
@@ -1,119 +0,0 @@
----
-title: "Getting started"
----
-
-
-
-Before you spend time on the minutia of installing ggsql — not that it is particularly daunting — why not try it out right now, right here, in your browser?
-
-The code below shows a simple ggsql example. But it is not just a static piece of text and an image. It is ggsql running right in your browser, using one of the built-in datasets. Try to change e.g. the title and see the plot update as you type. Even though this may be your first encounter with the ggsql syntax you might already get a sense of how some of the things fit together. See if you can change the code to instead show the different species as different shapes
-
-```{ggsql}
-VISUALISE bill_len AS x, bill_dep AS y, species AS fill FROM ggsql:penguins
-DRAW point
-SCALE x RENAMING * => '{} mm'
-LABEL
- title => 'Relationship between bill dimensions in 3 species of penguins',
- x => 'Bill length',
- y => 'Bill depth'
-```
-
-Congratulations! You have started your journey with ggsql! All examples you see on this site will be interactive. Please experiment to your heart's content. If you want a more dedicated exploration experience head to [our playground](wasm/) which provides a simple IDE with a number of examples to try out.
-
-Now that you have gotten a feel for ggsql you may want to try running locally with your own data. Read on to learn how.
-
-## Installation
-
-### Building from Source
-
-If you prefer to build from source or need the latest development version:
-
-1. **Clone the repository:**
-
- ```bash
- git clone https://github.com/posit-dev/ggsql
- cd ggsql
- ```
-
-2. **Install tree-sitter CLI:**
-
- ```bash
- npm install -g tree-sitter-cli
- ```
-
-3. **Build the project:**
-
- ```bash
- cd tree-sitter-ggsql && tree-sitter generate && cd ..
- cargo build --release
- ```
-
-4. **Install the CLI:**
- ```bash
- cargo install --path src
- ```
-
-5. **Install the Jupyter kernel (optional):**
- ```bash
- cargo install --path ggsql-jupyter
- ggsql-jupyter --install
- ```
-
diff --git a/doc/get_started/_metadata.yml b/doc/get_started/_metadata.yml
new file mode 100644
index 00000000..08d3e224
--- /dev/null
+++ b/doc/get_started/_metadata.yml
@@ -0,0 +1,3 @@
+sidebar: get_started
+page-navigation: true
+toc: false
diff --git a/doc/get_started/first_plot.qmd b/doc/get_started/first_plot.qmd
new file mode 100644
index 00000000..56027f6d
--- /dev/null
+++ b/doc/get_started/first_plot.qmd
@@ -0,0 +1,19 @@
+---
+title: "Your first plot"
+---
+
+The code below shows a simple ggsql example. But it is not just a static piece of text and an image. It is ggsql running right in your browser, using one of the built-in datasets. Try to change e.g. the title and see the plot update as you type. Even though this may be your first encounter with the ggsql syntax you might already get a sense of how some of the things fit together. See if you can change the code to instead show the different species as different shapes
+
+```{ggsql}
+VISUALISE bill_len AS x, bill_dep AS y, species AS fill FROM ggsql:penguins
+DRAW point
+SCALE x RENAMING * => '{} mm'
+LABEL
+ title => 'Relationship between bill dimensions in 3 species of penguins',
+ x => 'Bill length',
+ y => 'Bill depth'
+```
+
+Congratulations! You have started your journey with ggsql! All examples you see on this site will be interactive. Please experiment to your heart's content. If you want a more dedicated exploration experience head to [our playground](wasm/) which provides a simple IDE with a number of examples to try out.
+
+Before we move further, you might have some questions about the syntax. For instance, "why isn't there just a scatterplot function?". The next section will give a brief glimpse into the concept of the grammar of graphics that underpin the ggsql syntax and why we think it is a superior approach to data visualisation.
diff --git a/doc/get_started/grammar.qmd b/doc/get_started/grammar.qmd
new file mode 100644
index 00000000..bc1bf860
--- /dev/null
+++ b/doc/get_started/grammar.qmd
@@ -0,0 +1,24 @@
+---
+title: The grammar of graphics
+---
+
+ggsql is a tool for visualising data, combining our 20 years of experience developing [ggplot2](https://ggplot2.tidyverse.org/) with a SQL-native syntax.
+Unlike most visualisation systems, ggsql has an underlying grammar, based on the [Grammar of Graphics](https://en.wikipedia.org/wiki/Wilkinson%27s_Grammar_of_Graphics) by Leland Wilkinson.
+This is a different approach than the one taken by most tools, which give you a set of pre-defined graphics, like scatterplots, bar charts, and pie charts.
+ggsql instead gives you a number of independent components that you can combine to solve a very wide set of problems.
+
+This means there's a learning curve to ggsql: you have to learn a few big ideas about the grammar before you can be productive.
+But we believe the payoff is worth it.
+The grammar gives you new vocabulary and new ways to think about visualizations.
+This allows you to create not only familiar graphics but also newer, better graphics.
+You'll gain the ability to look at a visualization that someone else has made, analyse the key components, then recreate it yourself.
+The hardest part of learning ggsql is likely to be unlearning the preconceptions that you bring over from previous visualization tools.
+
+We've tried to make the learning curve as easy as possible by keeping the grammar close to the SQL syntax that you're already familiar with.
+You'll start with a classic `SELECT` statement to get the data that you want.
+Then you'll use `VISUALIZE` (or `VISUALISE` 🇬🇧) to switch from creating a table of data to creating a plot of that data.
+Then you'll `DRAW` a layer that maps columns in your data to aesthetics (visual properties), like position, colour, and shape.
+Then you tweak the `SCALE`s, the mappings between the data and the visual properties, to make the plot easier to read.
+Then you `FACET` the plot to show how the relationships differ across subsets of the data.
+Finally you finish up by adding `LABEL`s to explain your plot to others.
+This allows you to produce graphics using the same structured thinking that you already use to design a SQL query.
diff --git a/doc/get_started/installation.qmd b/doc/get_started/installation.qmd
new file mode 100644
index 00000000..3ed99dac
--- /dev/null
+++ b/doc/get_started/installation.qmd
@@ -0,0 +1,286 @@
+---
+title: "Installation"
+---
+
+While all of the examples on this website uses the ggsql WebAssembly build to let you run it in the browser, you'll likely want it on your own computer, interfacing with your local data.
+
+ggsql provides native installers for Windows, macOS, and Linux. Choose the best option for your platform below.
+
+::: {#installer-recommended}
+
+:::
+
+### All platforms
+
+::: {#installer-table}
+
+:::
+
+```{=html}
+
+
+
+```
+
+
+::: {.icon-section}
+[{height=60} {height=60}]{.section-icons}
+
+## Jupyter kernel
+
+To use ggsql in Jupyter or Quarto notebooks, install the Jupyter kernel using either `uv` (recommended) or `cargo`. The kernel is also part of the main installer linked to above.
+
+#### Using uv
+
+[uv](https://docs.astral.sh/uv/) is the fastest way to install the binaries:
+
+```bash
+uv tool install ggsql-jupyter
+ggsql-jupyter --install
+```
+
+#### Using cargo
+
+If you have a Rust toolchain installed you can install with cargo:
+
+```bash
+cargo install ggsql-jupyter
+ggsql-jupyter --install
+```
+:::
+
+::: {.icon-section}
+[{height=60} {height=60}]{.section-icons}
+
+## VS Code / Positron extension
+
+For syntax highlighting and language support in VS Code or Positron, install the ggsql extension. You can either install it directly from the [extension marketplace](https://open-vsx.org/extension/ggsql/ggsql) from within the IDE or download and install it manually:
+
+1. Download [`ggsql.vsix`](https://github.com/posit-dev/ggsql/releases/latest/download/ggsql.vsix)
+2. Install via the command line:
+
+```bash
+# VS Code
+code --install-extension ggsql.vsix
+
+# Positron
+positron --install-extension ggsql.vsix
+```
+
+Or install from within the editor: open the Extensions view, click the `...` menu, select "Install from VSIX...", and choose the downloaded file.
+:::
diff --git a/doc/index.qmd b/doc/index.qmd
index ca61e912..19fca57f 100644
--- a/doc/index.qmd
+++ b/doc/index.qmd
@@ -24,11 +24,11 @@ include-in-header:
# QUERY{.hviz aria-hidden="true"}VISUALIZEUNDERSTAND
::: {.hero-body}
-ggsql brings the elegance of the Grammar of Graphics to SQL. Write familiar queries, add visualization clauses, and see your data transform into beautiful, composable charts — no context switching, no separate tools, just SQL with superpowers.
+ggsql brings the elegance of the [Grammar of Graphics](get_started/grammar.qmd) to SQL. Write familiar queries, add visualization clauses, and see your data transform into beautiful, composable charts — no context switching, no separate tools, just SQL with superpowers.
::: {.hero-buttons}
-[Get Started](get_started.qmd){.btn .btn-primary .btn-lg}
-[View Examples](gallery/index.qmd){.btn .btn-outline-primary .btn-lg}
+[Get started](get_started/installation.qmd){.btn .btn-primary .btn-lg}
+[View examples](gallery/index.qmd){.btn .btn-outline-primary .btn-lg}
:::
:::
@@ -37,8 +37,6 @@ ggsql brings the elegance of the Grammar of Graphics to SQL. Write familiar quer
::: {.content-block .dark-bg}
### Try it out
-ggsql runs in the browser as well! Edit the code and watch the plot update.
-
```{ggsql}
-- Regular query
SELECT * FROM ggsql:penguins
@@ -70,15 +68,29 @@ LABEL
::: {.content-block .dark-bg .install-section}
### Install it today
-::: {#installer-buttons}
+::: {.install-columns}
+::: {.install-col .install-col-left}
+::: {#installer-recommended}
:::
-::: {.install-cli-options}
-**Or via command line:**
-`uv pip install ggsql-jupyter && ggsql-jupyter --install`
-·
-`cargo install ggsql`
+[Other platforms](get_started/installation.qmd){.other-platforms-link}
+:::
+
+::: {.install-divider}
+[or]{.divider-text}
+:::
+
+::: {.install-col .install-col-right}
+```bash
+# Jupyter kernel
+uv tool install ggsql-jupyter
+ggsql-jupyter --install
+
+# CLI
+uv tool install ggsql
+```
+:::
:::
```{=html}
@@ -86,7 +98,7 @@ LABEL
(function() {
const repoOwner = 'posit-dev';
const repoName = 'ggsql';
- const includePreReleases = true; // Set to false to only show published releases
+ const includePreReleases = true;
function detectOS() {
const ua = navigator.userAgent.toLowerCase();
@@ -96,30 +108,30 @@ LABEL
return 'unknown';
}
- function getOSLabel(os) {
- switch(os) {
- case 'windows': return 'Windows';
- case 'macos': return 'macOS';
- case 'linux': return 'Linux';
- default: return 'your platform';
- }
+ function getOSIcon(os) {
+ const icons = {
+ windows: 'bi-windows',
+ macos: 'bi-apple',
+ linux: 'bi-ubuntu'
+ };
+ return icons[os] ? `` : '';
}
- async function loadInstallers() {
- const container = document.getElementById('installer-buttons');
+ const patterns = {
+ windows_exe: /^ggsql[_-]\d.*x64.*-setup\.exe$/i,
+ macos: /^ggsql[_-]\d.*(aarch64|arm64).*\.dmg$/i,
+ linux: /^ggsql[_-]\d.*amd64.*\.deb$/i
+ };
+
+ function findAsset(assets, pattern) {
+ return assets?.find(a => pattern?.test(a.name));
+ }
+
+ async function loadInstaller() {
+ const container = document.getElementById('installer-recommended');
if (!container) return;
const os = detectOS();
- const jupyterPattern = {
- windows: /ggsql-jupyter.*\.(exe|msi)$/i,
- macos: /ggsql-jupyter.*\.dmg$/i,
- linux: /ggsql-jupyter.*\.deb$/i
- }[os];
- const cliPattern = {
- windows: /^ggsql[^-].*\.(exe|msi)$/i,
- macos: /^ggsql[^-].*\.dmg$/i,
- linux: /^ggsql[^-].*\.deb$/i
- }[os];
try {
const endpoint = includePreReleases
@@ -132,29 +144,25 @@ LABEL
if (!release) throw new Error('No releases found');
const version = release.tag_name;
- const jupyterAsset = release.assets?.find(a => jupyterPattern?.test(a.name));
- const cliAsset = release.assets?.find(a => cliPattern?.test(a.name));
+ const assets = release.assets || [];
+
+ let asset;
+ if (os === 'windows') {
+ asset = findAsset(assets, patterns.windows_exe);
+ } else if (os === 'macos') {
+ asset = findAsset(assets, patterns.macos);
+ } else if (os === 'linux') {
+ asset = findAsset(assets, patterns.linux);
+ }
container.innerHTML = `
-