在筆記本電腦使用 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	依日曆日小時分組。
天	依日曆日分組。
週	依日曆週分組。
月	按日曆月分組。
季	按日曆季分組。
年	按日曆年度分組。
hour_of_day	按 24 小時分組 (1,2,...,24)。
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

如上例所示，即使 SHOW 或 GROUP BY 關鍵字中未包含 WHERE 參數，也可以使用該參數來篩選結果集。在此情況下，即使結果集中未包含 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
*/