Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 66 additions & 68 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ DRAW line
SCALE x VIA date
SCALE y FROM [0, 100000]
LABEL title => 'Sales by Region', x => 'Date', y => 'Revenue'
THEME minimal
```

**Statistics**:
Expand Down Expand Up @@ -74,16 +73,18 @@ Direct visualization from tables/CTEs (auto-injects `SELECT * FROM`):
```sql
-- Direct table visualization
VISUALISE FROM sales
DRAW bar MAPPING region AS x, total AS y
DRAW bar
MAPPING region AS x, total AS y

-- CTE visualization
WITH monthly_totals AS (
SELECT DATE_TRUNC('month', sale_date) as month, SUM(revenue) as total
FROM sales
GROUP BY month
SELECT DATE_TRUNC('month', sale_date) as month, SUM(revenue) as total
FROM sales
GROUP BY month
)
VISUALISE FROM monthly_totals
DRAW line MAPPING month AS x, total AS y
DRAW line
MAPPING month AS x, total AS y
```

---
Expand Down Expand Up @@ -789,14 +790,15 @@ cargo build --release --package ggsql-jupyter
-- Cell 1: Create data
CREATE TABLE sales AS
SELECT * FROM (VALUES
('2024-01-01'::DATE, 100, 'North'),
('2024-01-02'::DATE, 120, 'South')
('2024-01-01'::DATE, 100, 'North'),
('2024-01-02'::DATE, 120, 'South')
) AS t(date, revenue, region)

-- Cell 2: Visualize
SELECT * FROM sales
VISUALISE
DRAW line MAPPING date AS x, revenue AS y, region AS color
DRAW line
MAPPING date AS x, revenue AS y, region AS color
SCALE x VIA date
LABEL title => 'Sales Trends'
```
Expand Down Expand Up @@ -1207,10 +1209,10 @@ Where `<global_mapping>` can be:

```sql
DRAW <geom>
[MAPPING <value> AS <aesthetic>, ...]
[SETTING <param> => <value>, ...]
[PARTITION BY <column>, ...]
[FILTER <condition>]
[MAPPING <value> AS <aesthetic>, ...]
[SETTING <param> => <value>, ...]
[PARTITION BY <column>, ...]
[FILTER <condition>]
```

All clauses (MAPPING, SETTING, PARTITION BY, FILTER) are optional.
Expand Down Expand Up @@ -1261,57 +1263,58 @@ Applies a filter to the layer data. Supports basic comparison operators.
```sql
-- Basic mapping
DRAW line
MAPPING date AS x, revenue AS y, region AS color
MAPPING date AS x, revenue AS y, region AS color

-- Mapping with literal
DRAW point
MAPPING date AS x, revenue AS y, 'value' AS color
MAPPING date AS x, revenue AS y, 'value' AS color

-- Setting parameters
DRAW point
MAPPING x AS x, y AS y
SETTING size => 5, opacity => 0.7
MAPPING x AS x, y AS y
SETTING size => 5, opacity => 0.7

-- With filter
DRAW point
MAPPING x AS x, y AS y, category AS color
FILTER value > 100
MAPPING x AS x, y AS y, category AS color
FILTER value > 100

-- Combined
DRAW line
MAPPING date AS x, value AS y
SETTING stroke_width => 2
FILTER category = 'A' AND year >= 2024
MAPPING date AS x, value AS y
SETTING stroke_width => 2
FILTER category = 'A' AND year >= 2024

-- With PARTITION BY (single column)
DRAW line
MAPPING date AS x, value AS y
PARTITION BY category
MAPPING date AS x, value AS y
PARTITION BY category

-- With PARTITION BY (multiple columns)
DRAW line
MAPPING date AS x, value AS y
PARTITION BY category, region
MAPPING date AS x, value AS y
PARTITION BY category, region

-- PARTITION BY with color (grouped lines with different colors)
DRAW line
MAPPING date AS x, value AS y, region AS color
PARTITION BY category
MAPPING date AS x, value AS y, region AS color
PARTITION BY category

-- All clauses combined
DRAW line
MAPPING date AS x, value AS y
SETTING stroke_width => 2
PARTITION BY category, region
FILTER year >= 2020
MAPPING date AS x, value AS y
SETTING stroke_width => 2
PARTITION BY category, region
FILTER year >= 2020
```

### PLACE Clause (Annotation Layers)

**Syntax**:

```sql
PLACE <geom> SETTING <aesthetic/parameter> => <value>, ...
PLACE <geom>
SETTING <aesthetic/parameter> => <value>, ...
```

Creates annotation layers with literal values only (no data mappings). All aesthetics set via SETTING; supports arrays that are recycled to longest length. No FILTER/PARTITION BY/ORDER BY support.
Expand All @@ -1334,7 +1337,8 @@ PLACE rule SETTING x => 5, color => 'red'
**Syntax**:

```sql
SCALE [TYPE] <aesthetic> [FROM <input>] [TO <output>] [VIA <transform>] [SETTING <properties>]
SCALE [TYPE] <aesthetic> [FROM <input>] [TO <output>] [VIA <transform>]
[SETTING <properties>]
```

**Type Modifiers** (optional, placed before aesthetic):
Expand Down Expand Up @@ -1404,7 +1408,8 @@ SCALE DISCRETE color FROM ['A', 'B', 'C'] TO ['red', 'green', 'blue']
SCALE color TO viridis

-- Scale with input range and additional settings
SCALE x VIA date FROM ['2024-01-01', '2024-12-31'] SETTING breaks => '1 month'
SCALE x VIA date FROM ['2024-01-01', '2024-12-31']
SETTING breaks => '1 month'
```

### FACET Clause
Expand All @@ -1413,10 +1418,12 @@ SCALE x VIA date FROM ['2024-01-01', '2024-12-31'] SETTING breaks => '1 month'

```sql
-- Wrap layout (single variable = automatic wrap)
FACET <vars> [SETTING <param> => <value>, ...]
FACET <vars>
[SETTING <param> => <value>, ...]

-- Grid layout (BY clause for row × column)
FACET <row_vars> BY <col_vars> [SETTING ...]
FACET <row_vars> BY <col_vars>
[SETTING ...]
```

**SETTING Properties**:
Expand Down Expand Up @@ -1446,26 +1453,30 @@ FACET region
FACET region BY category

-- With free y-axis scales
FACET region SETTING free => 'y'
FACET region
SETTING free => 'y'

-- With column count for wrap
FACET region SETTING ncol => 3
FACET region
SETTING ncol => 3

-- With label renaming via scale
FACET region
SCALE panel RENAMING 'N' => 'North', 'S' => 'South'
SCALE panel
RENAMING 'N' => 'North', 'S' => 'South'

-- Combined grid with settings
FACET region BY category
SETTING free => ['x', 'y'], spacing => 10
SETTING free => ['x', 'y'], spacing => 10
```

### PROJECT Clause

**Syntax**:

```sql
PROJECT [<aesthetic>, ...] TO <coord_type> [SETTING <properties>]
PROJECT [<aesthetic>, ...] TO <coord_type>
[SETTING <properties>]
```

**Components**:
Expand Down Expand Up @@ -1544,13 +1555,16 @@ PROJECT y, x TO polar
PROJECT y, x TO polar SETTING start => 90

-- Clip marks to plot area
PROJECT TO cartesian SETTING clip => true
PROJECT TO cartesian
SETTING clip => true

-- Combined with other clauses
DRAW bar MAPPING category AS x, value AS y
DRAW bar
MAPPING category AS x, value AS y
SCALE x FROM [0, 100]
SCALE y FROM [0, 200]
PROJECT y, x TO cartesian SETTING clip => true
PROJECT y, x TO cartesian
SETTING clip => true
LABEL x => 'Category', y => 'Count'
```

Expand Down Expand Up @@ -1579,25 +1593,6 @@ LABEL
caption => 'Data from Q4 2024'
```

### THEME Clause

**Syntax**:

```sql
THEME <name> [SETTING <overrides>]
```

**Base Themes**: `minimal`, `classic`, `gray`, `bw`, `dark`, `void`

**Example**:

```sql
THEME minimal
THEME dark SETTING background => '#1a1a1a'
```

---

## Complete Example Walkthrough

### Query
Expand All @@ -1608,15 +1603,18 @@ FROM sales
WHERE sale_date >= '2024-01-01'
GROUP BY sale_date, region
ORDER BY sale_date

VISUALISE
DRAW line
MAPPING sale_date AS x, total AS y, region AS color
MAPPING sale_date AS x, total AS y, region AS color
DRAW point
MAPPING sale_date AS x, total AS y, region AS color
MAPPING sale_date AS x, total AS y, region AS color
SCALE x VIA date
FACET region
LABEL title => 'Sales Trends by Region', x => 'Date', y => 'Total Quantity'
THEME minimal
LABEL
title => 'Sales Trends by Region',
x => 'Date',
y => 'Total Quantity'
```

### Execution Flow
Expand Down
Loading
Loading