SQLly 指令

功能的

小型 SQL 注释,用来记住结果集的样子:列、宽度、格式、颜色、数据透视表和图表。

A 指令 是一条 SQLly 能看懂的普通 SQL 注释。对数据库来说它只是条注释,SQLly 则用它来调整结果的形态或格式。指令就写在查询文本里,所以它们会跟着文件走,每次运行都重新生效。

每个指令共享相同的命名空间——这个词 sqlly 在注释标记之后:

-- sqlly view: pivot
-- sqlly grid: order=Region, Year, Sales; freeze=1; sort=Sales desc
-- sqlly pivot: row:Region; column:Year; value:Sales:sum
-- sqlly chart: kind:bar; label:Region; values:Sales
-- sqlly format: column=Sales; number=2; width=40dp
-- sqlly conditional: column=Sales; bar=#5B9BD5
-- sqlly column: Running Total = !Sales + N(!"Running Total"[1])
-- sqlly map: lat=Latitude; lon=Longitude; color=Region; cluster=on

你很少需要手动输入它们。按你喜欢的方式排列结果,然后点击 锁 在结果名称前面:SQLly 会把整个布局作为一块指令写入查询。参见 锁定网格.

指令系列

指令作用示例
view:打开结果,视图为 grid (默认), pivot,或 chart; map 会保留网格,同时还会在地图上打开结果。-- sqlly view: chart
grid:网格的列布局:顺序、隐藏与冻结的列、排序、分组、列筛选以及外键标签。 grid 2: 设置一个结果集,从 1 开始计数。-- sqlly grid: hide=Notes; freeze=1; sort=Total desc
format:一个结果列如何显示,宽度是多少。-- sqlly format: column=Created; date=%Y-%m-%d; width=40dp
conditional:按值为本次查询的单元格着色:一条高亮规则、一个色阶或一个数据条。每行一条规则。-- sqlly conditional: column=Status; when=is Failed; text=#B00020; bold
column:添加一列,通过 Excel 公式从结果自身的列计算得出: !Name 是这一行, !Name[1] 前一行。Excel 的函数和运算符。-- sqlly column: Total = !Qty * !Price
pivot:数据透视表的行、列和汇总值。 result:N 选择它所属的结果集。-- sqlly pivot: row:Rep; column:Quarter; value:Deals:count
chart:图表类型、类别标签、系列和聚合。 result:N 选择它所属的结果集。-- sqlly chart: kind:line; label:Month; values:Revenue,Cost
map:结果在地图上的绘制方式:位置列、标签和工具提示、颜色和大小、点或 热力图 (权重、半径、模糊、强度、不透明度、调色板)、聚类、街道地图、初始视图、点击行为,以及地图是否自动打开。 map 2: 设置一个结果集,从 1 开始计数。-- sqlly map: mode=heatmap; weight=orders; radius=30
/* sqlly lock当你在结果上点击锁定时,SQLly 写入的块注释。它的 -- sqlly 行会原样复现当时的结果。/* sqlly lock — … … */
name为结果集的标签页标注,从 1 开始计数。批处理返回多个结果时很方便。-- sqlly name 2: Open Orders
2x2 / result:在一个画布上布局多个结果集,将每个语句的结果放在一个单元格中。-- sqlly result: 1|2
layout:打开运行结果,布局为 stacked, tabbed,或 canvas,无论文件在哪里打开。-- sqlly layout: stacked
lines:分配给每个堆叠卡片的行数; lines 2: 设置一个结果集,从 1 开始计数。-- sqlly lines 2: 20
focus:结果返回时,正在查看哪个结果集:标签式会选中对应标签页,堆叠式会滚动到对应卡片。从 1 开始计数。-- sqlly focus: 2
param:声明一个参数,或为 :name 占位符指定类型和默认值。结果上方有一条输入条,每次运行前可以在那里输入它的值;普通的 :id, ? 和 $1 占位符无需声明即可获得值(参见 查询参数).-- sqlly param: @CustomerId int
set定义一个文本变量,用于替换每个 ${name} 在查询运行之前。-- sqlly set schema = dbo

param: 和 set 则是真正会改变数据库所收内容的两个。SQLly 会在发送前把它们的值替换进 SQL,且只替换字符串和注释之外的部分。参数值会以声明类型的转义字面量形式进入 SQL(text, int, decimal, bool, date,或 datetime)。一个 set 值会原样插入。 计算列 公式则把两者都读作 @name.

指令应放在哪里

  • 单独占一行。 位于同一行 SQL 代码之后的指令会被忽略。 name 是唯一的例外,可以作为行尾注释使用。
  • view: 以及画布大小放在第一行。 它们只在查询的第一个非空行上读取。如果顶部有锁块,则该块的第一条指令行就算作这一行。
  • 对空格要求很宽松 ,大多数类别都适用: --sqlly view: pivot 和 -- SQLLY view: pivot 两者都有效。
  • format: 是严格的。 必须一字不差地拼写为 -- sqlly format:,并且后面有一个空格 --.
  • 在块注释内,指令会被停用 - 这是临时禁用某条指令的方便方法。唯一的例外是 /* sqlly lock 块: 其中每一行的效果都与单独写在一行时完全一样。
-- sqlly view: pivot
-- sqlly pivot: row:Region; column:Year; value:Sales:sum
-- sqlly format: column=Sales; number=2
SELECT Region, Year, Sales FROM sales;
你输入时的安全网。 如果注释使用了 sqlly 命名空间拼写错误、放置在无法应用的位置或给予未知值时,SQLly 会在编辑器中用下划线标出并说明原因,而不是默默地忽略它。例如, -- sqlly view: table 得到 未知视图 —— 应为 -- sqlly view: grid, -- sqlly view: pivot, -- sqlly view: chart,或 -- sqlly view: map.

Autocomplete as you type

You don't have to remember any of the spellings above. As soon as a comment looks like a directive, the editor's suggestion list follows the cursor through it and offers the next thing the directive can take:

You have typedThe list offers
-- on a line of its ownA ready-made starter line for each kind of directive. view: and the canvas size are offered only on the query's first line, where they work.
-- sq这 sqlly namespace.
-- sqlly Every directive family: view:, grid:, format:, pivot:, chart: and the rest.
-- sqlly grid: The settings that family takes, leaving out the ones already on the line.
-- sqlly grid: sort=The values that setting accepts: here the result's columns. Elsewhere chart kinds, pivot aggregates, filter operators, map modes, number and date formats, time zones, colors.
-- sqlly grid: sort=Total What may follow the value: here asc 或者 desc.
  • One choice opens the next. Accepting a setting opens its values straight away, so a whole directive can be built by picking from lists with Tab or Enter.
  • Your real column names. Wherever a directive expects a column, the list shows the columns the tab's last run returned, quoted the way that directive needs them. Run the query once to get them.
  • Formulas and parameters too. In a column: formula the list completes column references, Excel worksheet functions and @ variables. On a param: line it offers the query's placeholders that are not declared yet, then every parameter type.
  • Only what works. Everything in the list is exactly what the directive accepts, so an accepted suggestion never earns the warning underline described above.
  • Bring it back anywhere inside a directive with Ctrl+空格, on macOS too.

应用内帮助

  • 悬停 任意 -- sqlly 写进注释作为简短说明,并附完整选项列表的链接。
  • 帮助 › 格式化指令… (也在命令面板中) 会打开一个参考窗口,里面有每个指令族、其参数和可直接复制的示例。
  • 让 SQLly 替你写。 点击结果名称前的锁图标,将整个结果写为指令,或者右键点击结果列标题并选择 格式 › 设置格式覆盖… 生成一个 format: 指令,已经帮你写好。

在本节中

网格
将列顺序、隐藏和冻结列、排序、分组以及筛选写入查询。
格式化 进行中
让每一列都得到它应得的展示形式和宽度,每次查询运行时自动完成。
条件
针对单个查询,按值为单元格着色:高亮规则、色阶和数据条。
计算列
添加以 Excel 公式编写的列:累计总和、利润率、相对上一行的变化以及日期。
数据透视表
用一条简短、可移植的注释,把熟悉的结果集变成交叉表。
图表
结果还没返回,就能告诉图表标签页要画一个什么样的故事。
锁定网格
一键就能把结果按当前看到的样子写进查询,这样每次运行得到的都一样。