ggsql 0.5.0 发布 beta：用 SQL 绘图

我们非常激动地宣布发布 ggsql 0.5.0，这是 ggsql 自四月份首次发布以来的首个测试版。虽然这个版本带来了许多核心改进，但测试版这个标签更多地标志着项目的成熟，而非本版本中的任何特定功能。话虽如此，所包含的功能还是很令人兴奋的，所以让我们向你详细介绍它们。

新的读取器范式#

ggsql 在设计上就是模块化的，读取器模块负责与你数据所在的各种后端进行交互。我们希望 ggsql 不是一个单体，而是能够集成到你或你的组织所使用的任何数据配置中，而读取器就是我们实现这一目标的方式。

我们已经在第一个版本中展示了这种灵活性，该版本同时包含了 DuckDB、SQLite 和通用的 ODBC 读取器。自那以后，我们添加了对新的、性能更高的 ADBC 驱动规范的支持。有了它和 ODBC，可以说所有广泛使用的数据库都可以访问了，不过要充分利用每个数据库的优势仍有工作要做。

我们最初设计中缺少的一件事是对只读数据库连接的支持。ggsql 在后端使用 TEMP TABLE 大量缓存计算，但这需要写权限，而你可能没有。为了解决这个使用场景，ggsql 0.5.0 现在包含了混合读取器模式。在这种模式下，初始数据查询从后端数据库读取，然后立即传输到你选择的内存数据库（例如 DuckDB 或 SQLite）进行进一步处理。这显然在你没有后端写权限的情况下有所帮助，但如果你的后端没有针对分析查询进行优化，也可以加快执行速度。另一方面，当要绘制的数据非常庞大时，它确实会带来额外开销。

你可以通过将兼容缓存的读取器传递给 CLI 中的 --cache 参数来开启混合模式，例如

ggsql exec --reader odbc://... --cache duckdb`"VISUALIZE ..."

或者在内核中将其以 + 作为分隔符前缀到读取器 url 上：

-- @connect: duckdb+odbc://...
VISUALIZE ...

我们对这个新设置所提供的功能感到兴奋，既因为它允许更多用户使用 ggsql，也因为在展望 ggsql 图形的交互性时——你可能确实不希望每当用户在图表的某处悬停时都去访问你的数据库后端。

一位新的写入器登场#

虽然读取器设置方面的改进对用户来说可能基本上是无形的，但另一项基础性变化必定会引人注目。ggsql 从一开始就依赖 Vega-Lite 进行实际渲染。这意味着 ggsql 将查询转换为 json 规范，并将其交给 Vega-Lite JavaScript 库进行进一步处理。这一选择意味着我们可以在 ggsql 的核心上快速迭代，而不会被实际渲染的复杂性所拖累。从一开始我们就知道 Vega-Lite 并不是 ggsql 中唯一的写入器，但随着开发的推进，很明显它总体上并不合适，必须被完全替换。因此，我花了整个夏天创建了一个新的写入器，它将适时完全取代 Vega-Lite。这样做的好处已经很多（我们将在下面逐一介绍），而且这项工作还将继续带来回报，因为我们可以更自由地支持我们认为相关的功能，而不必依赖另一个库的底层支持。

文件类型大集合#

如果你的目标是实时 HTML 文档，那么输出 JSON 规范以供进一步 JavaScript 处理是合理的，但除此之外，用户通常期望某种形式的图像。有了新的写入器，我们终于能够开箱即用地提供这一点。

而且我们并没有止步于 PNG……

新的写入器开箱即用，能够渲染 PNG、JPEG、TIFF、WebP、SVG 和 PDF 文档，希望能满足你所有的导出需求。SVG 输出针对在矢量图形软件中的进一步编辑进行了优化，而 PDF 输出则针对跨机器的稳定渲染进行了优化，因此会自动嵌入文档中使用的字形。

输出类型在 CLI 中根据文件扩展名自动推断，因此你可以例如直接创建图表的 PDF 版本，使用

ggsql exec --output plot.pdf "
VISUALIZE bill_dep AS x FROM ggsql:penguins
DRAW density"

在 Positron 中，新格式可作为绘图窗格的导出选项使用。

原生查看器#

虽然本身不是一种输出格式，但新的渲染器还允许直接从 CLI 输出到原生窗口进行预览。此功能可以通过 ggsql 的新 view 命令访问，例如

ggsql view "
VISUALIZE bill_dep AS x FROM ggsql:penguins
DRAW density"

新写入器带来的绘图能力#

虽然不同的输出模式是写入器能够渲染更多格式的直接结果，但新的写入器还通过提高可绘制内容的上限，提供了纯粹的数据可视化之乐。这是我们放弃 Vega-Lite 的主要原因，也是我们不能永远保留旧写入器的原因——它的能力就是不够。未来我们将继续从中获益，但我们已在本次版本中包含了一些：

通过扩展 markdown 实现的富文本支持#

文本在数据可视化中很重要。对于关注我多年来努力改进 R 的字体和文本渲染能力的人来说，这个立场应该并不意外。仅仅因为我们转向了 SQL，并不意味着我放弃了那项追求。因此，新的写入器完全支持 markdown，以及现代字体支持，包括字体特性和字体变体。由于后两者目前仍无法从 ggsql 中访问，我们在这里将重点放在 markdown 支持上。

默认情况下，所有标题和标签中都开启了 markdown 解析，但换行标签中没有。不过，一旦我们确定了主题系统，这一切都将可配置。最后，文本图层也可以通过设置 parse => true 来开启 markdown 解析。该 markdown 很大程度上受到我在 R 的 marquee 包中开发的风味的启发。这意味着标准 markdown 中你所期望的一切都可用，外加许多增强功能：

• 斜体 (*), 粗体 (**), 下划线 (_), 删除线 (~~), 下标 (~), 上标 (^), 代码（`），链接（[text](url)）
• 标题 1 — 6（# — ######）
• 引用块（>）
• 代码块（```）
• 无序列表和有序列表（前者用 - 或 *，后者用 1.）
• 水平线（* * *）
• 图片（![alt text](url)）

从 marquee 中，它获得了通过自定义 span 语法进行即时着色和调整大小的支持：{.red I'm colored red} 和 {#0000FF I'm colored blue} 允许在一段文本上设置命名颜色和十六进制编码颜色，而 {.40 I have big letters} 让你即时设置字体大小。writer 提供的自定义功能还要更深入，但再次强调，目前的瓶颈是主题系统，而不是渲染器。让我们看看它们的实际效果：

VISUALIZE species AS fill, species AS x FROM ggsql:penguins
DRAW bar
SCALE fill TO ('steelblue', 'goldenrod', 'forestgreen')
LABEL 
  title => '![](logo.png) Distribution of penguin (*Pygoscelis*) species',
  subtitle => 'This plot focuses on 3 species: {.steelblue *P. adeliae*}, {.goldenrod *P. antarcticus*}, {.forestgreen *P. papua*}'

对说明文字的支持#

Vega-Lite 的一个小而明显的缺陷是不支持说明文字。说明文字通常用于提供数据来源信息，以便它随可视化一起传播：

FROM ggsql:penguins
VISUALIZE species AS fill, bill_dep AS x, bill_len AS y 
DRAW point
LABEL 
  caption => 'Data source: [Gorman KB *et al.*](www.doi.org/10.1371/journal.pone.0090081)'

一个特定于渲染器的附注。如果你将上述内容导出为 SVG 或 PDF，其中包含的链接将是可点击的，并会将你带到那篇文章。

现在支持次要刻度#

在前两个示例中可见但被忽略的是输出中次要刻度的出现。这个概念在 Vega-Lite 中并不存在，因此我们一直在等待新的渲染器来启用它。接口与主要刻度非常相似：提供一个数量或一个精确位置数组，以让次要刻度出现：

FROM ggsql:penguins
VISUALIZE species AS fill, bill_dep AS x, body_mass AS y 
DRAW point
SCALE x
  SETTING minor_breaks => 3
SCALE y
  SETTING minor_breaks => (3200, 4200, 5200)

真正可变的线条美学#

旧的渲染器像 ggplot2 一样，通过将线条切成小段来支持沿线条变化的宽度和颜色。这在实用性上可行，但它唯一看起来正确的方法是使用圆形端点，而这既会强制使用圆角，也会因线段重叠而破坏透明度。在新的渲染器中，我不遗余力地让它在视觉上正确无误，方法是将线条转换为网格，并作为三角形进行渲染。这意味着渐变和可变宽度线条现在在底层得到完全支持，而不是通过任何取巧手段：

VISUALIZE Date AS x, Temp AS y FROM ggsql:airquality
DRAW line
  MAPPING Ozone AS stroke, Wind AS linewidth

（不以任何方式为上述可视化背书）

展望未来#

自首次发布以来的大约 5 个月里，我们已经涵盖了很多内容，但我们仍有很多要补充，而且我们迫不及待。这里不真正深入讨论其中任何一项的细节，我认为在 ggsql 退出 beta 之前有 3 项主要工作，以及肯定会随之而来的大量较小增强：

1. 支持表格输出。正如最近在我的 posit::conf(2026) 演讲中展示的那样，我们正在积极努力将 gt 的表格格式化功能引入 great-tables。这将允许你直接从 SQL 查询中格式化出版质量的表格，并使纯 (gg)SQL 驱动的报告成为许多用例的显而易见的选择。
2. 图形组合。一个图很好，多个图（有时）更好。受 R 的 patchwork 包为 ggplot2 图形所做工作的启发，我们希望允许图形、表格，或许还有更多内容的组合。谁知道有一天单个 SQL 查询是否能创建一个漂亮的仪表板呢。好消息是，新的渲染器已经内置了所有组合逻辑（分面就是通过该 API 完成的），所以其中很多问题只是落实正确语法的问题（我们对此极其重视）。
3. 交互性。对于某些任务，交互性是更好的解决方案（尽管并非对所有任务都是如此）。ggsql 的目标不是成为像 D3 那样用于高度定制交互式可视化的游乐场，但它确实希望在语法允许且不崩溃的范围内让可视化具有交互性。我非常期待这项设计工作。

这些是我们的主要关注点，但 writer 切换本身为我们提供了如此多唾手可得的成果，以至于在未来一年中会有大量用户可见的新增功能。