Finish Get started section by thomasp85 · Pull Request #274 · posit-dev/ggsql

thomasp85 · 2026-03-28T01:39:11Z

This PR builds upon the current Get started section and adds three additional pages for users to familarise themselves with. In addition it contains a range of fixes to bugs I uncovered as I developed the examples (all issues are unsurprisingly confined to the vegalite writer). The issues fixed are:

Fix free scales in faceted views. Vegalite makes some very weird choices that I'm working around now
Fix missing keys in size legend if fill is set to null
Fix plotting non-bar data in polar coordinate system
Fix faceting of polar data (panels were blank before)
Fix missing subtitle in plots

georgestagg

This looks like a great introduction, thanks!

georgestagg · 2026-03-30T10:23:14Z

doc/get_started/anatomy.qmd

@@ -0,0 +1,101 @@
+---


Not strictly part of this PR, but in the grammar.qmd page can we add something like a diagram or example, just to break up the text.

I found these types of diagram for ggplot2 helpful, if we can easily make something similar for ggsql:

georgestagg · 2026-03-30T10:41:26Z

doc/get_started/anatomy.qmd

+  SETTING stroke => null, bins => 20
+```
+
+but, if mappings and data source have already been taken care off, it can be as simple as


Suggested change

but, if mappings and data source have already been taken care off, it can be as simple as

but, if mappings and data source have already been taken care of, it can be as simple as

georgestagg · 2026-03-30T10:42:10Z

doc/get_started/anatomy.qmd

+```
+
+### `SCALE`
+As [described above](#scales) ggsql automatically creates a default for mapped aesthetics and if those suit your need there is no reason to modify them. However, if change is needed you do it with the [`SCALE`](../syntax/clause/scale.qmd) clause. 


Suggested change

As [described above](#scales) ggsql automatically creates a default for mapped aesthetics and if those suit your need there is no reason to modify them. However, if change is needed you do it with the [`SCALE`](../syntax/clause/scale.qmd) clause.

As [described above](#scales), ggsql automatically creates a default for mapped aesthetics and if those suit your needs there is no reason to modify them. However, if change is needed you do it with the [`SCALE`](../syntax/clause/scale.qmd) clause.

georgestagg · 2026-03-30T10:42:40Z

doc/get_started/anatomy.qmd

+### `SCALE`
+As [described above](#scales) ggsql automatically creates a default for mapped aesthetics and if those suit your need there is no reason to modify them. However, if change is needed you do it with the [`SCALE`](../syntax/clause/scale.qmd) clause. 
+
+The clause both allows you to set the type of scale, the input range, the output range, and transform, and let you control breaks and label formatting. So, the clause can end up with a lot of information but the syntax has been designed so it reads very natural. Further, every part is optional and can be left out if the default fits. An example of a rather complex `SCALE` clause could be:


Suggested change

The clause both allows you to set the type of scale, the input range, the output range, and transform, and let you control breaks and label formatting. So, the clause can end up with a lot of information but the syntax has been designed so it reads very natural. Further, every part is optional and can be left out if the default fits. An example of a rather complex `SCALE` clause could be:

The clause allows you to set the type of scale, the input range, the output range, the transformation, and lets you control breaks and label formatting. So, the clause can end up with a lot of information but the syntax has been designed so it reads very natural. Further, every part is optional and can be left out if the default fits. An example of a rather complex `SCALE` clause could be:

georgestagg · 2026-03-30T10:48:33Z

doc/get_started/anatomy.qmd

+  SETTING breaks => 4
+```
+
+In the above we create a global mapping of bill_len to the `x` aesthetic and bill_dep to the `y` aesthetic using the built-in penguins dataset. We use `DRAW` to create two layers: A point layer for a scatter plot and a smooth layer for regression lines. For the point layer we _map_ the body_mass to size to create a bubble chart and _set_ the fill aesthetic to be empty (`null`) so only the outline is shown. For the smooth layer we set the layer parameter `method` to `'ols'` to estimate a straight regression line. Lastly, we modify the stroke scale to use the dark2 palette from the ColorBrewer project and apply a binned scale to size that goes from 4pt to 15pt with 4 breaks (resulting in 3 bins).


Suggested change

In the above we create a global mapping of bill_len to the `x` aesthetic and bill_dep to the `y` aesthetic using the built-in penguins dataset. We use `DRAW` to create two layers: A point layer for a scatter plot and a smooth layer for regression lines. For the point layer we _map_ the body_mass to size to create a bubble chart and _set_ the fill aesthetic to be empty (`null`) so only the outline is shown. For the smooth layer we set the layer parameter `method` to `'ols'` to estimate a straight regression line. Lastly, we modify the stroke scale to use the dark2 palette from the ColorBrewer project and apply a binned scale to size that goes from 4pt to 15pt with 4 breaks (resulting in 3 bins).

In the above we create a global mapping of bill_len to the `x` aesthetic and bill_dep to the `y` aesthetic using the built-in penguins dataset. We use `DRAW` to create two layers: A point layer for a scatter plot and a smooth layer for regression lines. For the point layer we _map_ the body_mass to size to create a bubble chart and _set_ the fill aesthetic to be empty (`null`) so only the outline is shown. For the smooth layer we set the layer parameter `method` to `'ols'` to estimate a straight regression line. Lastly, we modify the stroke scale to use the dark2 palette from the ColorBrewer project and apply a binned scale to `size` that goes from 4pt to 15pt with 4 breaks (resulting in 3 bins).

georgestagg · 2026-03-30T10:50:25Z

doc/get_started/tooling.qmd

+VISUALISE ...
+```
+
+Each block in the document are using the same session, so tables created in one block will be available in subsequent blocks.


Suggested change

Each block in the document are using the same session, so tables created in one block will be available in subsequent blocks.

Each block in the document uses the same session, so tables created in one block will be available in subsequent blocks.

georgestagg · 2026-03-30T10:54:21Z

doc/get_started/the_rest.qmd

+
+The above alludes to the fact that coordinate systems have different position aesthetics. Often you expect `x` and `y` as position aesthetics and while these are indeed the default name for the [`cartesian`](../syntax/coord/cartesian.qmd) coordinate system they would be nonsensical for a [`polar`](../syntax/coord/polar.qmd) system which uses `radius` and `angle` as defaults. You can, however, freely define your own names, e.g. `r` and `a` for a polar system if you value brevity over comprehension.
+
+`PROJECT` also takes a `SETTING` clause which works much like the `SETTING` clause in `DRAW` and `SCALE`, allowing you to modify the behavior of the coordinate system. An example of a full `PROJECT` query could be:


An example of a full PROJECT query could be

Should we call this a "query", since it's only partially complete? Maybe "statement", "snippet", "clause" or something else?

georgestagg · 2026-03-30T10:55:43Z

doc/get_started/the_rest.qmd

+### `FACET`
+Faceting is applied with the [`FACET`](../syntax/clause/facet.qmd) clause. It allows you to either facet by a single variable (`FACET var`) or by a combination of two variables `FACET var1 BY var2`. In the former case the small multiples are laid out in a row-wise manner, wrapping to the next row if there are more multiples than the number of column. In the latter case the first variable is related to the rows and the second is related to the columns.
+
+There is an alternative to using the `FACET` variable, which is to map the variables directly to the facet aesthetics. There are three of these: `panel` is used when faceting by a single variable and `row` and `column` is used when faceting by two variables. `FACET var` is thus equivalent to `VISUALISE var AS panel`. Whichever you choose to use is thus a matter of personal preference as well as whether you also need to modify faceting behavior (in which case )


whether you also need to modify faceting behavior (in which case )

I think the end of this went missing?

thomasp85 added 3 commits March 24, 2026 06:52

first stab

91386fc

more getting started

739ad1a

Last part

8e02030

thomasp85 requested a review from georgestagg March 28, 2026 01:39

reformat

ef8a4fa

georgestagg approved these changes Mar 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Finish Get started section#274

Finish Get started section#274
thomasp85 wants to merge 4 commits intoposit-dev:mainfrom
thomasp85:get_started_again

thomasp85 commented Mar 28, 2026

Uh oh!

georgestagg left a comment

Uh oh!

georgestagg Mar 30, 2026

Uh oh!

georgestagg Mar 30, 2026

Uh oh!

georgestagg Mar 30, 2026

Uh oh!

georgestagg Mar 30, 2026

Uh oh!

georgestagg Mar 30, 2026

Uh oh!

georgestagg Mar 30, 2026

Uh oh!

georgestagg Mar 30, 2026

Uh oh!

georgestagg Mar 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	but, if mappings and data source have already been taken care off, it can be as simple as
	but, if mappings and data source have already been taken care of, it can be as simple as

	As [described above](#scales) ggsql automatically creates a default for mapped aesthetics and if those suit your need there is no reason to modify them. However, if change is needed you do it with the [`SCALE`](../syntax/clause/scale.qmd) clause.
	As [described above](#scales), ggsql automatically creates a default for mapped aesthetics and if those suit your needs there is no reason to modify them. However, if change is needed you do it with the [`SCALE`](../syntax/clause/scale.qmd) clause.

	The clause both allows you to set the type of scale, the input range, the output range, and transform, and let you control breaks and label formatting. So, the clause can end up with a lot of information but the syntax has been designed so it reads very natural. Further, every part is optional and can be left out if the default fits. An example of a rather complex `SCALE` clause could be:
	The clause allows you to set the type of scale, the input range, the output range, the transformation, and lets you control breaks and label formatting. So, the clause can end up with a lot of information but the syntax has been designed so it reads very natural. Further, every part is optional and can be left out if the default fits. An example of a rather complex `SCALE` clause could be:

	Each block in the document are using the same session, so tables created in one block will be available in subsequent blocks.
	Each block in the document uses the same session, so tables created in one block will be available in subsequent blocks.


		The above alludes to the fact that coordinate systems have different position aesthetics. Often you expect `x` and `y` as position aesthetics and while these are indeed the default name for the [`cartesian`](../syntax/coord/cartesian.qmd) coordinate system they would be nonsensical for a [`polar`](../syntax/coord/polar.qmd) system which uses `radius` and `angle` as defaults. You can, however, freely define your own names, e.g. `r` and `a` for a polar system if you value brevity over comprehension.

		`PROJECT` also takes a `SETTING` clause which works much like the `SETTING` clause in `DRAW` and `SCALE`, allowing you to modify the behavior of the coordinate system. An example of a full `PROJECT` query could be:

Conversation

thomasp85 commented Mar 28, 2026

Uh oh!

georgestagg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants