使用 SHOPLINE QL 自定义分析报告
SHOPLINE QL 是 SHOPLINE 提供的分析查询语言,可帮助您在自定义报告中更灵活地查询和展示数据。通过 SHOPLINE QL,您可以选择要查看的指标,设置筛选条件,按维度拆分数据,并通过简单计算定义新的指标口径。
本文介绍 SHOPLINE QL 的术语、基本语法、常用关键词、查询示例和使用注意事项。
了解 SHOPLINE QL 常用术语
在阅读 SHOPLINE QL 示例前,您可以先了解以下常用术语:
| 术语 | 说明 |
| 数据来源(Dataset) | SHOPLINE QL 要查询的数据集。例如,sales 代表销售相关数据。 |
| 指标(Metric) | 可量化的数据,例如销售额、订单数、销售净额。 |
| 维度(Dimension) | 用来拆分或分组数据的字段,例如日期、商品、地区。 |
| 关键词(Clause) | SHOPLINE QL 中具有固定用途的语句区块,例如 FROM、VIEW、FILTER、LIMIT。 |
| 别名(Alias) | 使用 AS为字段或计算得出的自定义字段指定的显示名称,方便在报告中识别该字段。 |
| 时间范围(Time range) | 查询要覆盖的日期或时间区间,可通过 DURING 或 SINCE / UNTIL 设置。 |
| 对比范围(Compare range) | 使用 COMPARE 生成的对比时间范围,例如上一个时段或去年同时段。 |
| 汇总数据(Totals) | 使用 EXTEND TOTALS 生成的汇总结果。 |
了解 SHOPLINE QL 查询结构
SHOPLINE QL 查询由多个关键词组成。每个关键词都有固定用途,用来告诉系统要查询哪些数据、显示哪些字段、如何筛选、如何分组,以及要查看哪个时间范围。
在自定义报告中使用 SHOPLINE QL 时,建议每段查询都包含以下内容:
FROM:指定数据来源。VIEW:指定要显示的字段、指标或计算结果。- 时间范围:使用
DURING,或使用SINCE/UNTIL指定日期范围。
示例:
FROM sales
VIEW total_sales, order_cnt
FILTER payment_status IN ('支付成功', '未支付')
GROUP BY day
DURING last_30_day
COMPARE previous_period
EXTEND TOTALS
ORDER BY total_sales DESC
LIMIT 20下表汇总了常用 SHOPLINE QL 关键词及其用途。您可以点击关键词名称,跳转到对应段落查看详细说明和示例。
| 关键词 | 说明 |
FROM | 指定要查询的数据来源。例如,sales 代表销售相关数据。 |
VIEW | 指定报告中要显示的指标、字段或计算结果。 |
FILTER | 设置筛选条件,只查看符合条件的数据。 |
POSTFILTER | 在指标计算后筛选报告结果,例如只显示销售额高于指定金额的分组结果。 |
GROUP BY | 按维度拆分数据,例如按日期、商品或地区分组。 |
DURING | 使用预设时间范围,例如今天、过去 30 天、本月。 |
SINCE / UNTIL | 使用指定的开始时间和结束时间。 |
COMPARE | 将当前时间范围的数据与上一个时段或去年同时段进行对比。 |
EXTEND TOTALS | 显示汇总数据。 |
ORDER BY | 设置结果排序方式。目前一次查询支持按一个字段排序。 |
LIMIT | 限制报告返回的数据行数。 |
OFFSET | 跳过指定数量的数据行,通常与 LIMIT 搭配使用。 |
| 备注:建议使用大写关键词,并将不同语句分行书写。这样更容易检查和维护查询内容。 |
在自定义报告中配置 SHOPLINE QL
您可以在创建或编辑自定义报告时输入并运行 SHOPLINE QL。通过 SHOPLINE QL 编辑器写入查询语句后,您可以先运行查询并预览报告结果,确认无误后再保存报告。
如需在自定义报告中配置 SHOPLINE QL,请按以下步骤操作:
- 在 SHOPLINE 后台中,转至 【分析】 > 【报告】。
- 点击右上角的 【创建自定义报告】 进入编辑模式。
- 输入报告名称。报告名称须唯一;若与现有报告名称重复,系统会提示您修改。
- 在数据集下拉列表中选择数据集。当前新建自定义报告仅支持 【销售结果数据】。
- 点击 【下一步】 后,在报告编辑页面的 SHOPLINE QL 编辑器中输入查询语句。
- 点击 【运行】 预览报告结果。
- 检查预览结果。如果结果正确,请保存报告。
注意:如果系统无法解析查询,或预览结果不符合预期,请检查查询是否包含 FROM、VIEW 和时间范围,并确认字段名称、标点符号和引号格式是否正确。 |
在查询中使用 SHOPLINE QL 关键词
FROM 和 VIEW
FROM 用来指定数据来源。VIEW 用来指定报告中要显示的字段、指标或计算结果。
例如,查看今天的销售额:
FROM sales
VIEW total_sales
DURING today您也可以在同一份报告中显示多个指标:
FROM sales
VIEW total_sales, net_sales, order_cnt
DURING last_7_day如果需要根据已有指标计算新的指标,可以在 VIEW 中使用加减乘除,并通过 AS 为新指标命名。
例如,计算平均订单金额:
FROM sales
VIEW (net_sales / order_cnt) AS average_order_value
DURING last_month例如,基于销售总额和折扣金额计算调整后的销售额:
FROM sales
VIEW (gross_sales - discounts) AS adjusted_sales
DURING last_monthSHOPLINE QL 支持以下计算运算符:
运算符 | 说明 |
* | 乘法 |
/ | 除法 |
+ | 加法 |
- | 减法 |
当同一个计算字段中包含多个运算符时,乘法和除法会先于加法和减法计算。您也可以使用括号调整计算顺序。
例如,先计算调整后的销售额,再除以订单数:
FROM sales
VIEW ((gross_sales - discounts) / order_cnt) AS average_adjusted_sales
DURING last_month注意:使用计算字段时,需要通过 AS 为新字段命名。报告中的字段名称不能重复。 |
FILTER
FILTER 用来在指标计算前筛选数据。您可以用它查看特定状态、商品、地区或其他符合条件的数据。
例如,只查看支付成功的销售数据:
FROM sales
VIEW total_sales
FILTER payment_status IN ('支付成功')
DURING today例如,只查看商品名称包含 shirt 的销售数据:
FROM sales
VIEW total_sales, order_cnt
FILTER product_spu_name CONTAINS ('shirt')
DURING last_30_dayFILTER 支持以下比较运算符:
| 运算符 | 说明 |
= | 等于 |
!= | 不等于 |
<> | 不等于 |
> | 大于 |
< | 小于 |
>= | 大于或等于 |
<= | 小于或等于 |
例如,筛选销售额大于 100 的数据:
FROM sales
VIEW total_sales
FILTER total_sales > 100
DURING last_30_day您也可以使用 AND、OR、NOT 组合多个筛选条件,或使用 IN、NOT IN、CONTAINS、NOT CONTAINS 匹配特定值。
例如,筛选支付成功,且顾客类型不属于指定类型的数据:
FROM sales
VIEW total_sales
FILTER (payment_status IN ('支付成功')) AND NOT buyer_type IN ('新客', '老客')
DURING today例如,筛选订单状态不属于指定状态的数据:
FROM sales
VIEW total_sales
FILTER order_status NOT IN ('成单', '已发货')
DURING today注意:字符串值需要使用英文单引号,例如 'shirt'、'支付成功'。如果使用中文引号或其他格式,查询可能会执行失败。 |
POSTFILTER
POSTFILTER 用来在指标计算完成后筛选报告结果。它适合用于先按维度汇总数据,再只保留符合条件的汇总结果。
例如,按省份查看过去 30 天的销售额,并只显示销售额大于 1000 的省份:
FROM sales
VIEW total_sales
GROUP BY province
DURING last_30_day
POSTFILTER total_sales > 1000FILTER 和 POSTFILTER 的使用位置不同。FILTER 会先筛选原始数据,再计算指标;POSTFILTER 会先计算指标,再筛选计算后的结果。
例如,如果您想先计算每个省份的销售额,再只查看销售额达到指定金额的省份,可以使用 POSTFILTER。
GROUP BY
GROUP BY 用来按维度拆分数据。未使用 GROUP BY 时,报告通常会返回汇总结果。使用 GROUP BY 后,系统会按您指定的维度显示明细。
例如,按天查看过去 30 天的销售额:
FROM sales
VIEW total_sales
GROUP BY day
DURING last_30_day例如,按省份和城市查看过去 30 天的销售额:
FROM sales
VIEW total_sales
GROUP BY province, city
DURING last_30_day常用时间维度包括:
运算符 | 说明 |
hour | 按小时查看数据。 |
day | 按天查看数据。 |
week | 按周查看数据。 |
month | 按月查看数据。 |
quarter | 按季度查看数据。 |
year | 按年查看数据。 |
hour_of_day | 按一天中的小时查看数据。 |
day_of_week | 按一周中的星期查看数据。 |
week_of_year | 按一年中的周数查看数据。 |
month_of_year | 按一年中的月份查看数据。 |
DURING、SINCE 和 UNTIL
在自定义报告中使用 SHOPLINE QL 时,建议为每段查询设置时间范围。您可以使用 DURING 快速选择预设时间范围,也可以使用 SINCE 和 UNTIL 指定具体日期。
使用预设时间范围:
FROM sales
VIEW total_sales
DURING last_30_day使用指定日期范围:
FROM sales
VIEW total_sales
SINCE '2026-05-01' UNTIL '2026-05-31'如果需要精确到具体时间,也可以使用日期加时间的格式:
FROM sales
VIEW total_sales
SINCE '2026-05-01 00:00:00' UNTIL '2026-05-31 23:59:59'常用的 DURING 时间范围包括:
运算符 | 说明 |
today | 今天。 |
yesterday | 昨天。 |
last_24_hour | 过去 24 个完整小时。 |
last_7_day | 过去 7 天,不包含今天。 |
last_30_day | 过去 30 天,不包含今天。 |
last_90_day | 过去 90 天,不包含今天。 |
this_week | 本周。 |
this_month | 本月。 |
last_month | 上个月。 |
this_quarter | 本季度。 |
last_quarter | 上季度。 |
this_year | 今年。 |
last_year | 去年。 |
注意:如果需要使用具体日期,请使用 SINCE 和 UNTIL。DURING 适合使用系统支持的预设时间范围。 |
COMPARE
COMPARE 用来将当前时间范围的数据与另一个时间范围进行对比。
例如,将过去 30 天的数据与上一个时段进行对比:
FROM sales
VIEW total_sales
GROUP BY day
DURING last_30_day
COMPARE previous_period目前支持的对比方式包括:
对比方式 | 说明 |
previous_period | 与上一段等长时间进行对比。 |
previous_year | 与去年同时段进行对比。 |
EXTEND TOTALS
EXTEND TOTALS 用来显示汇总数据。适合在按地区、商品或其他维度拆分数据时,同时查看整体合计。
例如,按省份查看过去 30 天的销售额,并显示汇总数据:
FROM sales
VIEW total_sales, order_cnt
GROUP BY province
DURING last_30_day
EXTEND TOTALS注意: 目前 EXTEND 支持 TOTALS。如果使用其他未支持的写法,查询可能会执行失败。 |
ORDER BY、LIMIT 和 OFFSET
ORDER BY 用来设置排序方式。LIMIT 用来限制返回的数据行数。OFFSET 用来跳过指定数量的数据行,通常与 LIMIT 搭配使用。
例如,查看过去 30 天销售额最高的 10 个商品:
FROM sales
VIEW total_sales, order_cnt
GROUP BY product_spu_name
DURING last_30_day
ORDER BY total_sales DESC
LIMIT 10ASC 表示从低到高排序,DESC 表示从高到低排序。
如果您需要跳过前 40 行,并查看接下来的 20 行,可以使用:
FROM sales
VIEW total_sales
GROUP BY product_spu_name
DURING last_30_day
ORDER BY total_sales DESC
LIMIT 20
OFFSET 40注意: 目前 ORDER BY 一次查询支持按一个字段排序,用于排序的字段需要已出现在 VIEW 或 GROUP BY 中。 |
常见 SHOPLINE QL 示例
以下示例可作为创建自定义报告时的参考。您可以根据自己的报告需求,替换指标、维度、筛选条件或时间范围。
查看过去 30 天销售额最高的商品
FROM sales
VIEW total_sales, order_cnt
GROUP BY product_spu_name
DURING last_30_day
ORDER BY total_sales DESC
LIMIT 10查看每日销售趋势并对比上一个时段
FROM sales
VIEW total_sales, net_sales
GROUP BY day
DURING last_30_day
COMPARE previous_period
ORDER BY day ASC
LIMIT 30按商品名称筛选销售数据
FROM sales
VIEW total_sales, order_cnt
FILTER product_spu_name CONTAINS ('shirt')
GROUP BY product_spu_name
DURING last_7_day
ORDER BY total_sales DESC
LIMIT 20按省份查看本月销售汇总
FROM sales
VIEW total_sales, order_cnt
GROUP BY province
DURING this_month
EXTEND TOTALS
ORDER BY total_sales DESC
LIMIT 50筛选计算后的销售结果
FROM sales
VIEW total_sales
GROUP BY province
DURING last_30_day
POSTFILTER total_sales > 1000使用指定日期范围查看销售数据
FROM sales
VIEW total_sales
FILTER payment_status IN ('success', 'failed')
SINCE '2026-05-01 00:00:00' UNTIL '2026-05-20 23:59:59'
使用 SHOPLINE QL 时的注意事项
使用 SHOPLINE QL 创建自定义报告前,请留意以下规则:
- 建议每段查询都包含
FROM、VIEW和一个时间范围。 - 建议使用大写关键词,并将不同语句分行书写。
- 字符串值需要使用英文单引号。
- 使用计算字段时,需要通过
AS设置字段名称。 - 同一份报告中的字段名称不能重复。
- 目前
VIEW中的计算字段支持加减乘除,不支持使用函数调用。 ORDER BY目前一次查询支持按一个字段排序。ORDER BY中使用的字段需要已出现在VIEW或GROUP BY中。- 如果没有设置
LIMIT,系统默认最多返回2000行。 - 非导出场景下,
LIMIT不应超过2000。 EXTEND目前支持TOTALS。COMPARE目前支持previous_period和previous_year。-
DURING建议使用系统支持的预设时间范围。若要使用具体日期,请使用SINCE和UNTIL。 - 时间范围建议控制在 3 年以内。
- 建议先从简单查询开始,确认结果正确后,再逐步加入筛选、分组、对比或计算字段。
SHOPLINE QL 常见问题
Q:SHOPLINE QL 会修改我的店铺数据吗?
不会。SHOPLINE QL 只用于查询和展示分析报告数据,不会修改您的订单、商品、顾客或销售记录。
Q:什么时候适合使用 SHOPLINE QL?
当您需要更灵活地定义报告内容时,可以使用 SHOPLINE QL。例如,您可以自定义指标口径、组合多个筛选条件,或按特定维度拆分销售数据。
Q:我可以用 SHOPLINE QL 定义新的指标吗?
可以。您可以基于已有指标进行加减乘除计算,并使用 AS 为新指标命名。例如,您可以用销售净额除以订单数,计算平均订单金额。
Q:为什么我的 SHOPLINE QL 查询执行失败?
常见原因包括字段名称错误、缺少时间范围、计算字段未命名、字段名称重复,或使用了当前不支持的写法。建议先检查 FROM、VIEW 和时间范围是否完整,再确认字段名称和标点符号是否正确。
Q:我可以用 SHOPLINE QL 查看指定日期范围的数据吗?
可以。您可以使用 SINCE 和 UNTIL 指定开始时间和结束时间。例如,查看 2026 年 5 月 1 日至 2026 年 5 月 31 日的数据。
Q:报告返回的数据行数有限制吗?
有。您可以使用 LIMIT 控制返回的数据行数。如果未设置 LIMIT,系统会按默认行数返回结果。为了确保报告页面加载稳定,部分图表或表格会限制页面展示数量。若页面预览未显示全部结果,您可以导出报告数据查看更完整的数据。