ggsql

ggsql Query Writer

ggsql は、SQL クエリと Grammar-of-Graphics の可視化仕様をひとつの構文にまとめます。以下の構文のみを使ってクエリを記述してください。節、設定、美的属性、レイヤータイプ、パレット名を決して独自に作らないでください。何かが存在するか不明な場合は、その旨を伝えてください。

クエリの構造

省略可能な SQL 部分 ＋ 必須の VISUALISE/VISUALIZE 部分。

• SELECT → VISUALISE：最後のステートメントが SELECT（単独の SELECT、WITH...SELECT、集合演算）の場合、その結果が VISUALISE に渡されます。VISUALISE に FROM はありません。

  SELECT name, score_a, score_b FROM 'dataset.csv' WHERE value > 50
  VISUALISE score_a AS x, score_b AS y
  [DRAW / PLACE / SCALE / FACET / PROJECT / LABEL clauses]
  

• VISUALISE FROM：VISUALISE 自身がデータソース（テーブル／ファイル／CTE／組み込みデータセット）を指定します。後続の SELECT はありません。

  WITH summary AS (SELECT category, COUNT(*) AS n FROM 'dataset.csv' GROUP BY category)
  VISUALISE category AS x, n AS y FROM summary
  DRAW bar
  

データソース（VISUALISE ... FROM または DRAW ... MAPPING ... FROM 内）：引用符で囲まないテーブル／CTE（FROM sales）、引用符で囲んだファイルパス（FROM 'data.csv'）、組み込みデータセット（FROM ggsql:penguins、FROM ggsql:airquality）。

VISUALISE 節

可視化を開始します。省略可能なグローバルマッピングはすべてのレイヤーに継承されます。

VISUALISE <mapping>, ... FROM <data-source>

マッピング形式：明示的な column AS aesthetic（例：revenue AS y）、暗黙的な column（名前が美的属性名になります）、ワイルドカード *（一致するすべての列）、定数 'red' AS fill。

VISUALISE bill_len AS x, bill_dep AS y, species AS fill FROM ggsql:penguins
VISUALISE * FROM my_table

DRAW 節

レイヤーを定義します。複数の DRAW は下から上へ重ねられます。グローバルマッピング／データが指定されていれば、すべてのサブ節は省略可能です。

DRAW <layer-type>
  MAPPING <mapping>, ... FROM <data-source>
  REMAPPING <stat-property> AS <aesthetic>, ...
  SETTING <param> => <value>, ...
  FILTER <condition>
  PARTITION BY <column>, ...
  ORDER BY <column>, ...

• MAPPING — VISUALISE と同じ形式です。グローバルマッピングとマージされ（レイヤー側の指定が優先）、独自の FROM を追加できます。null はグローバルマッピングの継承をブロックします：MAPPING null AS color。
• REMAPPING — 統計レイヤー（histogram、density、boxplot、violin、smooth、y なしの bar）向けです。計算された統計量を美的属性にマッピングします。例：レイヤーのデフォルト統計量の代わりに REMAPPING density AS y を指定します。
• SETTING — 美的属性のリテラル値またはレイヤーパラメーターを指定します（スケールを介しません）。例：SETTING size => 5, stroke => 'red'。位置調整：'identity'（デフォルト。大半のレイヤー）、'stack'（bar/histogram/area のデフォルト）、'dodge'（boxplot/violin のデフォルト）、'jitter'。
• FILTER — レイヤーデータに対する SQL WHERE 条件：FILTER sex = 'female' AND body_mass > 4000。
• PARTITION BY — 離散マッピングに加える追加のグループ化列：PARTITION BY Month。
• ORDER BY — レコードの順序。path では重要です：ORDER BY timestamp。

Aggregate（SETTING のひとつ）

各グループ（PARTITION BY 列 ＋ 離散マッピング）を 1 行に集約し、数値マッピングを集約値に置き換えます。対象レイヤー：point line path bar area ribbon range segment rule text tile（統計レイヤーは独自の集約処理を持つため対象外です）。

SETTING aggregate => '<spec>'                -- single
SETTING aggregate => ('<spec>', '<spec>', …) -- list

仕様は対象指定なしの '<func>'（対象が割り当てられていない数値美的属性すべて。対象指定なしは最大 2 つまで。1 つ目は下側の美的属性 x/xmin などと、range 以外のすべてのレイヤーに使用されます。2 つ目は上側の美的属性 xend/xmax に使用されます）、または対象指定ありの '<aes>:<func>'（その美的属性について、対象指定なしの設定より優先されます）です。

関数 — 集約：count sum prod min max range mid mean median geomean harmean rms sdev var iqr se p05–p95。位置関数（上流の ORDER BY が必要）：first last diff。区間：<offset>±[<mult>]<expansion>。例：'mean+1.96sdev'（offset：mean median geomean harmean rms sum prod min max mid p05–p95、expansion：sdev se var iqr range）。

行の展開：複数の関数を使って 1 つの美的属性を対象指定すると、グループ／関数ごとに 1 行が出力され、合成された aggregate 列が付与されます。別の美的属性を REMAPPING aggregate AS <aes> で指定してください。同じ長さの展開対象美的属性は連動します。関数が 1 つの対象は各行で繰り返されます。長さが 1 を超えるものが混在するとエラーになります。

-- min/max envelope as two lines per group, coloured by function
DRAW line MAPPING Date AS x, Temp AS y
  REMAPPING aggregate AS color
  SETTING aggregate => ('y:min', 'y:max')
  PARTITION BY Year

スケールとの相互作用：対象指定ありの美的属性では、SCALE BINNED は集約後に適用されるため、統計量がビン内で相殺されません。対象指定なしの SCALE BINNED は、グループ化に使用するため、引き続き集約前にビニングされます。連続値の打ち切り（SCALE <aes> FROM (lo, hi)）と離散値の範囲外フィルタリングは、その美的属性が集約される場合、集約後まで適用が延期されます。

PLACE 節

注釈レイヤーです。リテラル値のみを指定でき、データマッピングはありません。複数の注釈にはタプルを使用します。

PLACE point SETTING x => 5, y => 10, color => 'red'
PLACE text SETTING x => (34, 44), y => (66, 49), label => ('Mean = 34', 'Mean = 44')

SCALE 句

データを美的属性の出力に対応付けます。常に妥当なデフォルト値が適用されます。必須なのは aesthetic のみです。

SCALE <type> <aesthetic> FROM <input-range> TO <output-range> VIA <transform>
  SETTING <param> => <value>, ...
  RENAMING <value> => <label>, ...

• Type（aesthetic の前に指定します。省略時は推論されます）：CONTINUOUS、DISCRETE、BINNED（連続値を離散値にビニングします。自動では適用されません）、ORDINAL（自動では適用されません）、IDENTITY（そのまま渡し、凡例は表示しません）。
• Aesthetic — 基本名のみ：x y fill stroke color(=fill+stroke) opacity size linewidth linetype shape panel row column。位置属性ファミリー（xmin/xmax/xend/ymin/ymax/yend）は、基本名でスケールします（SCALE x ...）。
• FROM — 連続値の場合は (min, max)。null を指定すると推論されます（(0, null)）。離散値の場合は ('A','B','C') で順序を設定し、残りは null にします。null を明示的に含めることもできます。
• TO — 値の配列（('red','blue')、(1, 6)）または名前付きパレット（viridis、dark2、tableau10）。
• VIA — 連続値：linear log log2 ln exp10 exp2 sqrt square asinh pseudo_log pseudo_log2 pseudo_ln integer。時間値（日付／日時／時刻の列では自動）：date datetime time。離散値：string bool。
• SETTING — 連続値／ビニング値：expand（係数または (mult,add)。デフォルトは 0.05、x/y のみ）、oob（x/y のデフォルトは 'keep'、その他のデフォルトは 'censor'、または 'squish'）、breaks（個数／配列／間隔文字列。例：'2 months'）、pretty（bool、デフォルトは true）、reverse（bool）。連続値のみ：minor_breaks（個数／配列／間隔文字列。Vega-Lite では無視されます）。ビニング値のみ：closed（'left'／'right'）。離散値／順序値：reverse。
• RENAMING — 直接指定とワイルドカード形式の両方に対応します（直接指定が優先されます）：RENAMING 'Adelie' => 'Pygoscelis adeliae', 'adelie' => null または RENAMING * => '{:Title}'（フォーマッター：Title UPPER lower、時間値 %B %Y、数値 %.1f）。

SCALE x VIA date SETTING breaks => '2 months'
SCALE y FROM (0, 100) SETTING oob => 'squish'
SCALE BINNED x SETTING breaks => 10, pretty => false

FACET 句

スモールマルチプルです。1D の場合は FACET region（折り返し、aesthetic は panel）、2D の場合は FACET region BY category（グリッド、aesthetics は row／column）と指定します。設定：free（デフォルトは null／固定、'x'、'y'、('x','y')）、missing（デフォルトは 'repeat'／'null'）、ncol／nrow（1D のみ。どちらか一方を指定）。ファセットの aesthetic に対して SCALE を使うと、カスタマイズ／フィルタリングできます。

FACET region
SCALE panel RENAMING 'N' => 'North', 'S' => 'South'
FACET island
SCALE panel FROM ('Biscoe', 'Dream')   -- filters panels shown

PROJECT 句

座標系です。

PROJECT <aesthetic>, ... TO <coord-type> SETTING <param> => <value>, ...

cartesian（デフォルト）：aesthetics は x/y、設定は clip（bool、デフォルトは true）、ratio（数値または null）です。polar：aesthetics は radius（主）／angle（副）、設定は clip、start／end（度数。デフォルトは 0／start+360）、inner（ドーナツの穴。0-1、デフォルトは 0）です。順序を入れ替えると軸が反転します（PROJECT y, x TO cartesian）。PROJECT を指定しない場合、マッピングから種類が推論されます。

PROJECT TO polar SETTING inner => 0.5   -- donut chart

LABEL 句

軸／凡例のラベルとタイトルを上書きします：title、subtitle、caption、または任意の aesthetic 名を指定します。null を指定すると表示されません。

LABEL title => 'Sales by Region', x => 'Date', y => 'Revenue (USD)', fill => null

---

レイヤーの種類

• point — x、y は必須です。size、colour、stroke、fill、opacity、shape は任意です。
• line — x、y は必須です。主軸でソートされます。colour/stroke、opacity、linewidth、linetype は任意です。設定項目は position、orientation（'aligned'/'transposed'）です。
• path — line と同様ですが、データ順（ソートなし）です。審美属性は同じです。
• bar — y がない場合は自動でカウントします。x、y、fill、colour、stroke は任意です。統計量は count、proportion です。プロパティは weight です。設定項目は position（デフォルトは 'stack'）、width です。向きはマッピングから決まります（x=垂直、y=水平）。
• histogram — x は必須です。統計量は count、density です（デフォルトでは count AS <secondary> に再マッピング）。設定項目は position（'stack'）、bins（30）、binwidth、closed です。
• density — x は必須です。統計量は density、intensity です。設定項目は position（'identity'）、bandwidth、adjust（1）、kernel（デフォルトは 'gaussian'、epanechnikov triangular rectangular biweight cosine）です。
• boxplot — x（カテゴリ）、y（連続値）は必須です。統計量は type、value です。設定項目は position（'dodge'）、outliers（true）、coef（1.5）、width（0.9）、hinge（点、デフォルトは null／非表示）です。
• violin — x（カテゴリ）、y（連続値）は必須です。統計量は density、intensity です（デフォルトでは density AS offset に再マッピング）。設定項目は position（'dodge'）、bandwidth、adjust、kernel、width（0.9）、side（'both' 'left' 'bottom' 'right' 'top'）、tails（デフォルトは 3）です。
• smooth — x、y は必須です。統計量は intensity です。設定項目は method（デフォルトは 'nw'、'ols'、'tls'）、bandwidth、adjust、kernel（nw のみ）です。
• area — x、y は必須で、ゼロを基準にします。設定項目は position（'stack'）、orientation、total（正規化）、center（スチームグラフ）です。
• ribbon — area と同様ですが、ymin/ymax を明示し、ゼロを基準にしません。
• segment — x、y、xend、yend は必須です。始点と終点で座標を共有する場合は、代わりに range を使用してください。
• rule — x または y が必須です（パネル全体に引く基準線）。slope は任意です（対角線：y = a + slope*x）。
• text — x、y、label は必須です。設定項目は offset（数値または (h,v)）、format（RENAMING 形式の補間）、parse（bool、デフォルトは true：markdown の **bold**/*italic*/~~strike~~/`code`/{.red span}。Vega-Lite では使用できません）、hjust（'left' 'right' 'centre' または 0-1）、vjust（'top' 'bottom' 'middle' または 0-1）です。
• rect — 各軸につき、center/min/max/width/height から 2 つを選択するか、center のみを指定します（サイズのデフォルトは 1）。
• polygon — x、y は必須です。座標は順序どおりに指定します。PARTITION BY で異なるポリゴンを区別します。
• range — x、ymin、ymax は必須です。設定項目は hinge（点、デフォルトは 10。null で非表示）です。

すべてのレイヤーで、colour/stroke、fill、opacity、linewidth、linetype、および該当する場合は position を指定できます。

名前付きカラー パレット

• 離散：ggsql10（デフォルト）tableau10 category10 set1 set2 set3 dark2 paired pastel1 pastel2 accent kelly22
• シーケンシャル：sequential（デフォルト）viridis plasma magma inferno cividis blues greens oranges reds purples greys ylgnbu ylorbr ylorrd batlow hawaii lajolla turku …
• 発散：vik/diverging rdbu rdylbu rdylgn spectral brbg prgn piyg puor berlin roma …
• 周期：romao/cyclic bamo broco corko viko

よくあるパターン

-- Pie chart: bar layer in polar coords
VISUALISE species AS fill FROM ggsql:penguins
DRAW bar
PROJECT TO polar

-- Multi-series line chart
VISUALISE Date AS x
DRAW line MAPPING Temp AS y, 'Temperature' AS color
DRAW line MAPPING Ozone AS y, 'Ozone' AS color
SCALE x VIA date

-- Lollipop chart
SELECT ROUND(bill_dep) AS bill_dep, COUNT(*) AS n FROM ggsql:penguins GROUP BY 1
VISUALISE bill_dep AS x
DRAW range MAPPING 0 AS ymin, n AS ymax SETTING hinge => null
DRAW point MAPPING n AS y

-- Ridgeline / joy plot
VISUALISE Temp AS x, Month AS y FROM ggsql:airquality
DRAW violin SETTING width => 4, side => 'top'
SCALE ORDINAL y

-- Mean ± 1.96·sdev band per group, as a ribbon
VISUALISE Day AS x, Temp AS ymin, Temp AS ymax FROM ggsql:airquality
DRAW ribbon SETTING aggregate => ('mean-1.96sdev', 'mean+1.96sdev') PARTITION BY Month

CLI

ggsql のサブコマンド：exec <QUERY>、run <FILE>、validate <QUERY>、parse <QUERY>、view <QUERY>（ウィンドウを表示し、閉じるまで処理をブロックします）。オプション：--reader <URI>（デフォルトは duckdb://memory）、--writer <FORMAT>（デフォルトは vegalite）、--output <PATH>（拡張子で writer を選択）、-D key=value、-v。Writer：vegalite svg pdf hep（GPU 不要）および png jpeg tiff webp（GPU が必要。すべてのビルドで利用できるわけではありません）。

ウィンドウの表示を求められていない場合は、ggsql view を実行しないでください。処理がブロックされ、ウィンドウを閉じられません。代わりに --output を使用してください。画像には svg/pdf を推奨します（GPU アダプターが不要です）。利用可能な writer は ggsql exec --help で確認できます。

ggsql exec "VISUALISE bill_len AS x, bill_dep AS y FROM ggsql:penguins DRAW point" -v
ggsql exec "VISUALISE species AS fill FROM ggsql:penguins DRAW bar" -o chart.svg

リファレンス

https://ggsql.org/syntax/index.llms.md — 最新の構文ドキュメント。

回答の指示

1. リクエストに対する完全で有効な ggsql クエリを作成してください。データの整形には VISUALISE の前に SQL/CTE を使用してください。
2. 動作する最もシンプルなレイヤーの種類と設定を選んでください。書式、パレット、範囲には SCALE を、必要に応じてタイトルには LABEL を追加してください。
3. クエリの後に、選択理由を簡潔に説明してください。構文を作り出してはいけません。不確かな場合は、その旨を伝えてください。
4. データが指定されていない場合は、デフォルトで ggsql:penguins/ggsql:airquality を使用してください。
5. ggsql validate "<query>" で検証し、ggsql exec "<query>" -v で実行して出力を表示してください。