在 Notebooks 中使用 ShopifyQL

ShopifyQL 是 Shopify 专为商务构建的查询语言。查询语言用于从数据库请求数据和检索数据。您可以将 ShopifyQL 与 Shopify Notebooks 应用配合使用来探索您商店的数据库以及检索数据，以便更深入地了解您的商店。

有关可用于 ShopifyQL Notebook 查询的可用值和维度的完整列表，请参阅订单架构和产品架构。

ShopifyQL 概述

您商店的数据存储在数据库表中，采用定义的列和行结构。列用于定义数据包含的信息类型，例如销售额，而行指定数据类型的实际值，例如 2,450 美元销售额。

若要以有意义的格式检索数据，则必须将查询提交到数据库。查询是请求提供特定数据作为答案的问题。查询语言（如 ShopifyQL）是构建该问题的标准化方式。查询由关键字及其相应参数构成。具有特定参数的多个关键字组合可构成查询。构建查询后，您可以运行查询并获得答案。

下方是采用 ShopifyQL 语法编写的查询的示例。关键字已加粗，相应的参数位于括号中。此处显示的参数是占位符：

FROM { table_name }
  SHOW { column1, column2, ... }
  GROUP BY { dimension | date_group }
  WHERE { condition }
  SINCE { date_offset }
  UNTIL { date_offset }
  ORDER BY { column } DESC
  LIMIT { count }

术语表

ShopifyQL 术语的定义

术语	定义
外形尺寸	对数据进行细分的属性，使数据可以更清晰地排序和呈现。维度的常见示例包括时间、产品和位置。维度在 ShopifyQL 中用作参数。
关键字	充当命令来引导查询的 ShopifyQL 语法。
指标	数据的定量衡量。指标的常见示例包括总销售额、订单数和毛利润。
参数	用于标识要在查询中包含的数据库元素或详细信息的 ShopifyQL 语法。

关键字参考表

这些是可用于编写查询的关键字：

ShopifyQL 关键字列表

关键字	功能用途
FROM	指定要从中选择数据的数据集表。
SHOW	选择要从数据集表提取的列。
VISUALIZE	以线形或条形可视化图表显示您的数据。
GROUP BY	按外形尺寸或时间维度对提取的数据进行分组。
WHERE	定义行要可供选择必须满足的条件。
SINCE	显示自过去某个指定时间起的数据。
UNTIL	显示截止至过去指定时间的数据。
DURING	显示自过去某个指定时间起的数据。
COMPARE TO	显示截止至过去指定时间的数据。
ORDER BY	指定按哪个列对数据排序。
LIMIT	限制显示的数据行数。
AS	将列重命名为您选择的名称。

编写 ShopifyQL 查询

ShopifyQL 查询涵盖基本查询（获得高级数据洞察）到全面查询（获得详细洞察）。每个关键字都有用于构建查询的特定功能。

ShopifyQL 基础知识：FROM 和 SHOW

创建最简单的 ShopifyQL 查询只需要两个关键字：FROM 和 SHOW（编写时采用该顺序）。FROM，后跟表格名称参数，用于指定要查询的表。SHOW，后跟列名称参数，用于指定要选择的列。

例如，您可以通过编写如下查询来列出销售表中的所有产品 ID 及其对应标题：

FROM products
  SHOW product_id, product_title

---

数据分组：GROUP BY

若要按维度对指标进行细分，例如按区域分组销售额，请使用 GROUP BY 关键字。GROUP BY 关键字可以与任何维度参数一起使用。

例如，按账单寄送国家/地区来对总运费进行分组的查询可编写为：

FROM orders
  SHOW shipping
  GROUP BY billing_country, billing_region

下方是另一个使用时间维度来按月显示净销售额的示例查询：

FROM orders
  SHOW net_sales
  GROUP BY month

上方查询不会返回您没有销售额的任何月份。如果您想让查询返回一个完整、不中断的时间段，请使用 ALL 修饰符：

FROM orders
  SHOW net_sales
  GROUP BY month ALL
  SINCE last_year
  UNTIL today

使用 ALL 修饰符时，您还需要指定 SINCE 和 UNTIL。请注意，ALL 修饰符仅适用于时间维度。

时间维度

下方是可用于对数据进行分组的时间维度：

ShopifyQL 时间维度

运算符	功能用途
hour	按日历日中的某一小时分组。
天	按日历日分组。
week	按日历周分组。
月	按日历月分组。
quarter	按日历季度分组。
year	按日历年分组。
hour_of_day	按 24 小时 (1,2,...,24) 分组。
day_of_week	按 day of week 分组（周一、周二、周三…周日）。
week_of_year	按一年中的周分组 (1,2,...,52)。

---

筛选数据：WHERE

通过 WHERE 关键字，您可以在整个 ShopifyQL 查询中应用维度筛选条件。

例如，如果您想返回按月分组但仅针对特定区域的净销售额，则可使用查询：

FROM orders
  SHOW net_sales
  GROUP BY month ALL
  WHERE billing_region = 'ohio'
  SINCE last_year
  UNTIL today

如上方示例所示，您可以使用 WHERE 参数筛选结果集，即使该参数未包含在 SHOW 或 GROUP BY 关键字中也是如此。在此示例中，即使结果集不包含 billing_region，系统也会将所有月份的净销售额筛选为仅包含账单地址位于俄亥俄州的订单。

比较运算符

WHERE 关键字使用比较运算符来筛选数据。在上面的示例中，“=”用于指定查询筛选特定值，但是，您还可以使用其他运算符：

ShopifyQL 比较运算符

比较运算符	功能用途
=	等于
!=	不等于
<	小于
>	大于
<=	小于或等于
>=	大于或等于

逻辑运算符

若要进一步筛选数据，您可以向查询中添加逻辑运算符。ShopifyQL 逻辑运算符包括：

ShopifyQL 逻辑运算符

逻辑运算符	功能用途
AND	筛选以显示满足 AND 分隔的所有条件的所有行。
OR	筛选以显示满足 OR 分隔的条件之一的所有行。
NOT	筛选以仅显示不满足条件的行，例如不包含指定值的行。

您可以通过添加逻辑运算符来对 WHERE 关键字使用多个筛选条件。

结合示例数据集查询，若要针对账单地址位于俄亥俄州且应用了折扣的所有订单进行每月净销售额分组，则查询为：

FROM orders
  SHOW net_sales
  GROUP BY month ALL
  WHERE billing_region = 'ohio' AND discounts > 0
  SINCE last_year
  UNTIL today

---

日期范围：SINCE 和 UNTIL

如果要按日期或某一时间段筛选查询，可以使用 SINCE 和 UNTIL 关键字及其相关参数。这些关键字是唯一的，因为它们仅筛选时间段。

例如，下方的查询用于查找加拿大过去 12 个月内（截至今天）的净销售额：

FROM orders
  SHOW net_sales
  GROUP BY month ALL
  WHERE billing_country = 'Canada'
  SINCE -12m
  UNTIL today

移位运算符

您可以按特定日期或日期偏移量进行筛选。ShopifyQL 移位运算符包括：

ShopifyQL 移位运算符

移位运算符	功能用途
-{#}d	此次运行查询距离上次运行查询的天数。
-{#}w	此次运行查询距离上次运行查询的周数。
-{#}m	此次运行查询距离上次运行查询的月数。
-{#}q	此次运行查询距离上次运行查询的季度数。
-{#}y	此次运行查询距离上次运行查询的年数。
yyyy-mm-dd	具体日期。
今天	运行查询的日期。
昨天	此次运行查询之前的 24 小时周期。

---

按日期范围筛选：DURING

DURING 关键字可简化日期范围的日期筛选。您可以使用 DURING 关键字筛选已知时间段（例如日历年或特定月份）的查询结果，或筛选每年日期不同的日期范围（例如黑色星期五/络星期一）的查询结果。例如：

FROM orders
  SHOW sum(net_sales)
  GROUP BY day ALL
  DURING bfcm2021

DURING 接受以下任一指定日期范围运算符：

ShopifyQL 指定日期范围运算符

日期范围运算符	功能用途
今天	运行查询的日期。
昨天	运行查询之前的 24 小时周期。
this_week	当前日历周。
this_month	当前日历月。
this_quarter	当前日历季度。
this_year	当前日历年。
last_week	上一个日历周。
last_month	上一个日历月。
last_quarter	上一个日历季度。
last_year	上一个日历年。
bfcm2022	2022 年 11 月 25 日 - 11 月 28 日。
bfcm2021	2021 年 11 月 26 日 - 11 月 29 日。

---

在日期范围之间进行比较：COMPARE TO

通过 COMPARE TO 关键字，您可以比较 DURING 和 COMPARE TO 在日期范围内的数据。它接受 DURING 部分中列出的任何指定日期范围操作符。COMPARE TO 使用的操作符的时间长度必须与 DURING 使用的操作符相同。例如，DURING this_week COMPARE TO last_week 是有效组合，而 DURING this_week COMPARE TO last_month 则无效。

以下示例将 2022 年黑色星期五/网络星期一期间的净销售额与 2021 年黑色星期五/网络星期一期间的净销售额进行比较。

FROM orders
  SHOW sum(net_sales)
  GROUP BY day ALL
  DURING bfcm2022
  COMPARE TO bfcm2021

---

数据排序：ORDER BY

您可以使用 ORDER BY 关键字及其参数指定如何对查询返回的数据进行排序：ASC（升序）和 DESC（降序）。

您可以在 ORDER BY 关键字指定要在查询中包含的任何指标或维度，包括多个字段。

例如，下方查询会返回每个账单寄送国家/地区的净销售额，这些销售额依次按账单寄送国家/地区以及每个国家/地区内的账单地区采用反向字母顺序排序。

FROM orders
  SHOW net_sales
  GROUP BY billing_country, billing_region
  SINCE -1y
  UNTIL today
  ORDER BY billing_country, billing_region DESC

您编写指标或维度的顺序非常重要。如果您为 ORDER BY 指定多个值，则该排序方式将应用于给定订单中的每个指标或维度。

---

限制

通过 LIMIT 关键字，您可以指定查询返回的行数。如果您只想了解每列数据的外观，这非常有用。或者，您可以将该关键字和 ORDER BY 组合使用来创建排名最前和排名最后的项列表。

下方的示例使用 LIMIT 和 ORDER BY 来创建过去 3 个月内销量前 10 的产品列表：

FROM products
  SHOW net_product_quantity
  GROUP BY product_title
  SINCE -3m
  UNTIL today
  ORDER BY net_product_quantity DESC
  LIMIT 10

---

绘制查询图表：VISUALIZE 和 TYPE

通过 VISUALIZE 关键字，您可以编写一个可在线形或条形可视化图表中显示数据的 ShopifyQL 查询。

TYPE 关键字是选填的，并且必须指定“line”或“bar”，这样查询才能相应地返回线形图或条形图的可视化图表。如果您的查询中未使用 TYPE，ShopifyQL 会自动确定最适合您查询的呈现方式。如果您的查询无法以书面形式进行可视化，ShopifyQL 将返回表格数据。

例如，您可以使用趋势线来可视化呈现过去一年按月显示的销售额趋势。下方查询将返回一个时间序列图表，显示过去一年按月显示的总销售额。销售额用一条线来描绘，x 轴标记为“月”，y 轴标记为“总销售额”：

FROM orders
  VISUALIZE gross_sales
  TYPE line
  GROUP BY month ALL
  SINCE -1y
  UNTIL today

---

数学运算符

ShopifyQL 允许对数据中的指标进行算数运算。可以使用以下数学运算符：

ShopifyQL 移位运算符

数学运算符	功能用途
+	将两个数值相加。
-	将两个数值相减。
*	将两个数值相乘。
/	将两个数值相除。

例如，下方的查询可计算过去一年每个区域的订单价值。将数学运算符应用于指标时，您可以使用 AS 关键字向新指标分配新名称。

FROM orders
  SHOW (net_sales + returns) AS order_value, orders, (net_sales + returns)/orders AS sales_per_order
  GROUP BY billing_region
  SINCE -1y
  UNTIL today

---

函数

通过 ShopifyQL 函数，您可以将 Microsoft Excel 中的数据进行聚合以生成数据透视表。对列进行聚合意味着将它们合并以产生新的值。当前版本的 ShopifyQL 中提供以下函数运算符：

ShopifyQL 移位运算符

函数运算符	功能用途
count()	结果集中的实例数。
sum()	结果集中值的总和。
min()	结果集中的最小值。
max()	结果集中的最大值。
avg()	结果集中的平均值。

sum、min、max 和 avg 函数只能用于数值，而 count 可用于计算维度属性的不同实例数。不能在函数中将聚合字段用作参数。聚合字段以 _sum、_count 或 _percent 结尾。

例如，下方的查询将返回错误，因为 total_sales 已进行过聚合：

FROM orders
  SHOW sum(total_sales)

下方是一个有效查询，其中混合了已聚合的字段和聚合函数：

FROM orders
  SHOW average_order_value, sum(gross_sales)
  GROUP BY billing_region
  SINCE 2021-01-01
  UNTIL 2021-12-31

此查询返回平均订单金额的聚合值以及使用 sum 函数计算出的总销售额。对于 2021 年下的所有订单，这些指标按账单地区进行细分。

---

评论

您可以使用注释解释 ShopifyQL 语句的分区，或阻止 ShopifyQL 语句的执行。在执行期间，注释中的任何文本都将被忽略。

单行注释以 -- 开头，在行末尾结束。

多行注释以 /* 开头，以 */ 结尾。

FROM orders
  SHOW average_order_value, sum(gross_sales)
  -- the line below has been commented out and will not run
  -- GROUP BY billing_region
  WHERE billing_country = 'United States'
  /*
  this line and the two lines below it have been commented out and will not run
  SINCE 2021-01-01
  UNTIL 2021-12-31
*/