{"id":"ggsql","name":"ggsql","summary":"ggsqlクエリを書いてください — SQLのグラフィックの文法です。ユーザーがggsqlの可視化クエリを作成、修正、または理解したい場合に使います。","body":"# ggsql Query Writer\n\nggsql is a SQL extension for declarative data visualization based on Grammar of Graphics principles. It lets users combine SQL data queries with visualization specifications in a single, composable syntax.\n\nWhen the user describes a visualization they want, write a valid ggsql query. Use ONLY syntax documented below. NEVER invent clauses, settings, aesthetics, or layer types.\n\n## Query structure\n\nA ggsql query has two parts:\n\n1. **SQL part** (optional): Standard SQL executed on the backend. Any tables, CTEs, or SELECT results are available to the visualization.\n2. **VISUALISE part** (required): Begins with `VISUALISE` (or `VISUALIZE`). Everything after this is the visualization query.\n\nThere are two patterns for combining SQL with VISUALISE:\n\n### Pattern A: SELECT → VISUALISE\n\nThe last SQL statement is a SELECT. Data flows from its result set into VISUALISE, which has no `FROM` clause.\n\n```ggsql\nSELECT name, score_a, score_b FROM 'dataset.csv' WHERE value > 50\nVISUALISE score_a AS x, score_b AS y\n[DRAW / PLACE / SCALE / FACET / PROJECT / LABEL clauses]\n```\n\nWorks with any SQL that ends in a SELECT: bare SELECT, WITH...SELECT, UNION/INTERSECT/EXCEPT.\n\n### Pattern B: VISUALISE FROM\n\nVISUALISE provides its own data source via `FROM`. Use when referencing a table, file, CTE, or built-in dataset directly without a trailing SELECT.\n\n```ggsql\nVISUALISE score_a AS x, score_b AS y FROM 'dataset.csv'\nDRAW point\n```\n\n```ggsql\nWITH summary AS (SELECT category, COUNT(*) AS n FROM 'dataset.csv' GROUP BY category)\nVISUALISE category AS x, n AS y FROM summary\nDRAW bar\n```\n\n## Data sources\n\nData sources can appear in `VISUALISE ... FROM` or `DRAW ... MAPPING ... FROM`:\n\n- **Table/CTE name** (unquoted): `FROM sales`, `FROM my_cte`\n- **File path** (single-quoted string): `FROM 'data.parquet'`, `FROM 'data.csv'`\n- **Built-in datasets**: `FROM ggsql:penguins`, `FROM ggsql:airquality`\n\n## VISUALISE clause\n\nMarks the start of the visualization. Optionally defines global mappings inherited by all layers.\n\n```\nVISUALISE , ... FROM \n```\n\n### Mapping forms\n\n- **Explicit**: `column AS aesthetic` — e.g. `revenue AS y`\n- **Implicit**: `column` — column name must match aesthetic name, e.g. `x` maps to `x`\n- **Wildcard**: `*` — all columns with names matching aesthetics are mapped\n- **Constants**: `'red' AS fill`, `42 AS size` — literal values mapped to aesthetic\n\n```ggsql\nVISUALISE bill_len AS x, bill_dep AS y, species AS fill FROM ggsql:penguins\nVISUALISE * FROM my_table\nVISUALISE FROM ggsql:penguins\n```\n\n## DRAW clause\n\nDefines a layer. Multiple DRAW clauses stack layers (first = bottom, last = top).\n\n```\nDRAW \n MAPPING , ... FROM \n REMAPPING AS , ...\n SETTING => , ...\n FILTER \n PARTITION BY , ...\n ORDER BY , ...\n```\n\nAll subclauses are optional if VISUALISE provides global mappings and data.\n\n### MAPPING\n\nSame syntax as VISUALISE mappings. Layer mappings merge with global mappings (layer takes precedence). Can include `FROM` for layer-specific data.\n\n- Use `null` to prevent inheriting a global mapping: `MAPPING null AS color`\n\n### REMAPPING\n\nFor statistical layers (histogram, density, boxplot, violin, smooth, bar without y). Maps calculated statistics to aesthetics. Each layer documents its available stats and default remapping.\n\n```ggsql\nDRAW histogram\n MAPPING body_mass AS x\n REMAPPING density AS y -- use density instead of default count\n```\n\n### SETTING\n\nSet literal aesthetic values or layer parameters. Aesthetics set here bypass scales.\n\n```ggsql\nDRAW point\n SETTING size => 5, opacity => 0.7, stroke => 'red'\n```\n\n**Position adjustment** is a special setting:\n```ggsql\nSETTING position => 'identity' -- no adjustment (default for most)\nSETTING position => 'stack' -- stack (default for bar, histogram, area)\nSETTING position => 'dodge' -- side by side (default for boxplot, violin)\nSETTING position => 'jitter' -- random offset\n```\n\n### FILTER\n\nSQL WHERE condition applied to layer data. Content is passed to the database:\n```ggsql\nDRAW point\n FILTER sex = 'female' AND body_mass > 4000\n```\n\n### PARTITION BY\n\nAdditional grouping columns beyond mapped discrete aesthetics:\n```ggsql\nDRAW line\n MAPPING Day AS x, Temp AS y\n PARTITION BY Month\n```\n\n### ORDER BY\n\nControls record order (important for path layers):\n```ggsql\nDRAW path\n ORDER BY timestamp\n```\n\n## PLACE clause\n\nCreates annotation layers with literal values only (no data mappings). Supports tuples for multiple annotations.\n\n```\nPLACE \n SETTING => , ...\n```\n\n```ggsql\nPLACE point SETTING x => 5, y => 10, color => 'red'\nPLACE rule SETTING y => 70, linetype => 'dotted'\nPLACE text SETTING x => (34, 44), y => (66, 49), label => ('Mean = 34', 'Mean = 44')\n```\n\n## SCALE clause\n\nControls how data values are translated to aesthetic values. Sensible defaults are always provided.\n\n```\nSCALE FROM TO VIA \n SETTING => , ...\n RENAMING =>