countryatlas and ggsql

ggsql is a grammar of graphics for SQL: you describe a plot inside a SQL query and it renders in the database (DuckDB), returning a web-ready Vega-Lite widget — no ggplot2 or sf runtime required. The spatial layer this vignette targets (DRAW spatial, which reads WKB geometry) arrived in the ggsql engine at 0.4.0. As of August 2026 the ggsql R package is still at 0.3.3, so the bridge below is forward-looking: world_query() builds the query today, and the chunks that would execute one are shown but not evaluated.

Emit a query (no dependencies)

world_query() is a pure string builder — it needs nothing installed — so you can see exactly what will be sent to ggsql:

world_query(
  gdp_per_capita,
  projection = "equal_earth",
  palette    = "magma",
  transform  = "log10",
  title      = "GDP per capita"
)
#> VISUALISE gdp_per_capita AS fill
#> FROM countryatlas_world
#> DRAW spatial
#> PROJECT TO equal_earth
#> SCALE fill TO magma VIA log10
#> LABEL title => 'GDP per capita'

Render in the database

as_ggsql_source() exports a curated countryatlas table (with sf geometry WKB-encoded) to a DuckDB connection, a Parquet file, or a nanoarrow stream that ggsql can read. The one-call path is interactive_map(engine = "ggsql"):

# needs: ggsql, duckdb, DBI, sf
world_data(2020, geometry = "sf") |>
  interactive_map(gdp_per_capita, engine = "ggsql", transform = "log10")

Under the hood that is just the two building blocks, which you can also drive yourself for full control over the query:

src <- world_data(2020, geometry = "sf") |>
  as_ggsql_source(format = "duckdb")          # a DuckDB connection

q <- world_query(gdp_per_capita, projection = "orthographic", palette = "viridis")

ggsql::ggsql_execute(src, q)                  # -> Vega-Lite widget

In a Quarto / R Markdown document

Loading ggsql registers a chunk engine. Export the source once, then chart it in a ```{ggsql} block, referencing the registered table by name:

```{r}
library(countryatlas)
library(ggsql)

src <- world_data(2020, geometry = "sf") |>
  as_ggsql_source(format = "duckdb")          # registers countryatlas_world
```

```{ggsql connection=src}
VISUALISE gdp_per_capita AS fill
FROM countryatlas_world
DRAW spatial
PROJECT TO equal_earth
SCALE fill TO magma VIA log10
LABEL title => 'GDP per capita, 2020'
```

Why bother?

The win is the same as ggsql’s everywhere else: only the rendered result leaves the database. For a single world map that is minor, but the moment your country panel lives in a warehouse — millions of rows, many years — pushing the aggregation and rendering down to where the data already is, rather than pulling it into R, is the whole point. countryatlas makes sure what you push down is keyed on an honest, reconciled ISO spine.