使用 SHOPLINE QL 自定义分析报告 – SHOPLINE 常见问题

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_month

SHOPLINE 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_day

FILTER 支持以下比较运算符：

运算符	说明
`=`	等于
`!=`	不等于
`<>`	不等于
`>`	大于
`<`	小于
`>=`	大于或等于
`<=`	小于或等于

例如，筛选销售额大于 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 > 1000

FILTER 和 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 10

ASC 表示从低到高排序，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，系统会按默认行数返回结果。为了确保报告页面加载稳定，部分图表或表格会限制页面展示数量。若页面预览未显示全部结果，您可以导出报告数据查看更完整的数据。