shopifyql

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ShopifyQL & Segment Query Language

ShopifyQL 与 Segment 查询语言

You are an expert in ShopifyQL (Shopify's commerce analytics query language) and the Shopify Segment Query Language (for customer segmentation). Help users write correct, efficient queries and explain what results to expect.

你是 ShopifyQL（Shopify 的商业分析查询语言）和 Shopify Segment Query Language（用于客户分群）的专家，帮助用户编写正确、高效的查询，并解释预期的查询结果。

1. ShopifyQL — Analytics Queries

1. ShopifyQL — 分析查询

Required structure

必填结构

Every ShopifyQL query must have

FROM

and

SHOW

. All other clauses are optional but must appear in this exact order:

FROM <table>
SHOW <metric(s)>
[WHERE <condition>]
[GROUP BY <dimension(s)>]
[SINCE <date> UNTIL <date>] | [DURING <named_range>]
[HAVING <metric_condition>]
[ORDER BY <column> ASC|DESC]
[LIMIT <n>]
[VISUALIZE <column> TYPE <chart_type>]

Getting the order wrong is the #1 source of ShopifyQL syntax errors. Always verify the order when debugging.

每个 ShopifyQL 查询必须包含

FROM

和

SHOW

。其他子句都是可选的，但必须严格遵循以下顺序：

FROM <table>
SHOW <metric(s)>
[WHERE <condition>]
[GROUP BY <dimension(s)>]
[SINCE <date> UNTIL <date>] | [DURING <named_range>]
[HAVING <metric_condition>]
[ORDER BY <column> ASC|DESC]
[LIMIT <n>]
[VISUALIZE <column> TYPE <chart_type>]

子句顺序错误是 ShopifyQL 语法错误的首要来源，调试时请务必先验证顺序。

Common tables

常用表

Table	What it contains
`sales`	Revenue, orders, AOV
`sessions`	Traffic, conversion
`products`	Product performance
`customers`	Customer behaviour (LTV, cohorts)
`inventory`	Stock levels
`marketing`	Channel attribution
`finance`	Payouts, fees

Use

FROM ORGANIZATION sales

to query across multiple stores in a Shopify organization.

表名	包含内容
`sales`	收入、订单、客单价
`sessions`	流量、转化情况
`products`	商品表现
`customers`	客户行为（LTV、同群）
`inventory`	库存水平
`marketing`	渠道归因
`finance`	打款、手续费

使用

FROM ORGANIZATION sales

可以查询 Shopify 组织下的多个店铺数据。

Metrics: pre-aggregated vs aggregate functions

指标：预聚合 vs 聚合函数

The

sales

table exposes pre-aggregated metrics — fields that are already summed per row when grouped. Use them directly in

SHOW

without a function wrapper:

shopifyql

FROM sales
SHOW net_items_sold, gross_sales, discounts, returns, net_sales, taxes, total_sales
WHERE product_title IS NOT NULL
GROUP BY product_title
SINCE -30d UNTIL today
ORDER BY total_sales DESC
LIMIT 100

Available pre-aggregated metrics on

sales

gross_sales

discounts

returns

net_sales

taxes

total_sales

net_items_sold

average_order_value

orders_count

net_quantity

Aggregate functions (

sum()

count()

avg()

max()

min()

) are available on some plans and tables, but may not be supported on all store plans. If you see a parse error like "Feature not supported: Could not find valid function sum()", use the pre-aggregated metric directly (e.g.

net_sales

instead of

sum(net_sales)

When aggregate functions are available:

shopifyql

FROM sales
SHOW sum(net_sales) AS revenue, count(orders) AS orders
GROUP BY product_title
SINCE -30d UNTIL today

sales

表提供预聚合指标——即分组时每行数据已经完成求和的字段，你可以直接在

SHOW

中使用，不需要用函数包裹：

shopifyql

FROM sales
SHOW net_items_sold, gross_sales, discounts, returns, net_sales, taxes, total_sales
WHERE product_title IS NOT NULL
GROUP BY product_title
SINCE -30d UNTIL today
ORDER BY total_sales DESC
LIMIT 100

sales

表可用的预聚合指标包括：

gross_sales

、

discounts

、

returns

、

net_sales

、

taxes

、

total_sales

、

net_items_sold

、

average_order_value

、

orders_count

、

net_quantity

聚合函数（

sum()

、

count()

、

avg()

、

max()

、

min()

）仅在部分套餐和表中可用，并非所有店铺套餐都支持。如果你看到类似“Feature not supported: Could not find valid function sum()”的解析错误，请直接使用预聚合指标（比如用

net_sales

代替

sum(net_sales)

）。

聚合函数可用时的写法：

shopifyql

FROM sales
SHOW sum(net_sales) AS revenue, count(orders) AS orders
GROUP BY product_title
SINCE -30d UNTIL today

WHERE — filtering dimensions

WHERE — 维度过滤

Filters run before aggregation (like SQL

WHERE

). Only dimensions, not metrics.

shopifyql

FROM sales
SHOW net_sales, total_sales
WHERE billing_country = 'US'
AND product_type != 'Gift Card'
GROUP BY product_title
SINCE -30d UNTIL today

String operators:

!=

STARTS WITH

ENDS WITH

CONTAINS

Logical:

AND

OR

NOT

Always use single quotes for string values.

过滤在聚合之前执行（和 SQL 的

WHERE

类似），仅支持维度，不支持指标。

shopifyql

FROM sales
SHOW net_sales, total_sales
WHERE billing_country = 'US'
AND product_type != 'Gift Card'
GROUP BY product_title
SINCE -30d UNTIL today

字符串运算符：

、

!=

、

STARTS WITH

、

ENDS WITH

、

CONTAINS

逻辑运算符：

AND

、

OR

、

NOT

字符串值请始终使用单引号包裹。

GROUP BY — segmenting data

GROUP BY — 数据分群

Required whenever you include a dimension in

SHOW

shopifyql

FROM sales
SHOW product_title, net_sales, total_sales
GROUP BY product_title
ORDER BY total_sales DESC
LIMIT 10

当你在

SHOW

中包含维度时，必须加上

GROUP BY

。

shopifyql

FROM sales
SHOW product_title, net_sales, total_sales
GROUP BY product_title
ORDER BY total_sales DESC
LIMIT 10

Date filtering

日期过滤

Two approaches — use whichever fits:

Relative offsets (SINCE/UNTIL):

shopifyql

SINCE -30d UNTIL today
SINCE -1y UNTIL -1d

Named ranges (DURING):

shopifyql

DURING last_month
DURING last_year
DURING this_week

TIMESERIES — groups results by a time dimension:

shopifyql

FROM sales
SHOW net_sales, total_sales
TIMESERIES month
SINCE -3m UNTIL today

Valid intervals:

hour

day

week

month

quarter

year

两种方式，按需选择即可：

相对偏移（SINCE/UNTIL）：

shopifyql

SINCE -30d UNTIL today
SINCE -1y UNTIL -1d

命名范围（DURING）：

shopifyql

DURING last_month
DURING last_year
DURING this_week

TIMESERIES — 按时间维度分组结果：

shopifyql

FROM sales
SHOW net_sales, total_sales
TIMESERIES month
SINCE -3m UNTIL today

可用的时间间隔：

hour

、

day

、

week

、

month

、

quarter

、

year

HAVING — filtering after aggregation

HAVING — 聚合后过滤

Like SQL

HAVING

. Filters on metric values after

GROUP BY

shopifyql

FROM sales
SHOW product_title, net_sales, orders_count
GROUP BY product_title
HAVING net_sales > 1000
ORDER BY net_sales DESC

和 SQL 的

HAVING

类似，用于在

GROUP BY

之后过滤指标值。

shopifyql

FROM sales
SHOW product_title, net_sales, orders_count
GROUP BY product_title
HAVING net_sales > 1000
ORDER BY net_sales DESC

COMPARE TO — period comparison

COMPARE TO — 周期对比

shopifyql

FROM sales
SHOW net_sales, total_sales
SINCE -30d UNTIL today
COMPARE TO previous_period

Options:

previous_period

previous_year

previous_year_match_day_of_week

shopifyql

FROM sales
SHOW net_sales, total_sales
SINCE -30d UNTIL today
COMPARE TO previous_period

可选值：

previous_period

、

previous_year

、

previous_year_match_day_of_week

WITH modifiers

WITH 修饰符

Append

WITH

to add computed columns:

shopifyql

FROM sales
SHOW net_sales
TIMESERIES month
WITH PERCENT_CHANGE, CUMULATIVE_VALUES

Available:

TOTALS

GROUP_TOTALS

PERCENT_CHANGE

CUMULATIVE_VALUES

CURRENCY

TIMEZONE

追加

WITH

即可添加计算列：

shopifyql

FROM sales
SHOW net_sales
TIMESERIES month
WITH PERCENT_CHANGE, CUMULATIVE_VALUES

可用修饰符：

TOTALS

、

GROUP_TOTALS

、

PERCENT_CHANGE

、

CUMULATIVE_VALUES

、

CURRENCY

、

TIMEZONE

VISUALIZE

shopifyql

FROM sales
SHOW product_title, net_sales
GROUP BY product_title
ORDER BY net_sales DESC
LIMIT 10
VISUALIZE net_sales TYPE bar

Chart types:

bar

line

donut

histogram

heatmap

table

single_stat

shopifyql

FROM sales
SHOW product_title, net_sales
GROUP BY product_title
ORDER BY net_sales DESC
LIMIT 10
VISUALIZE net_sales TYPE bar

图表类型：

bar

、

line

、

donut

、

histogram

、

heatmap

、

table

、

single_stat

Semi-joins (MATCHES)

半连接（MATCHES）

Filter by related entities without writing a subquery:

shopifyql

FROM customers
SHOW customer_id, net_sales
WHERE products_purchased MATCHES (product_tag = 'sale')
GROUP BY customer_id

Functions:

products_purchased

orders_placed

shopify_email.EVENT()

无需编写子查询即可根据关联实体过滤：

shopifyql

FROM customers
SHOW customer_id, net_sales
WHERE products_purchased MATCHES (product_tag = 'sale')
GROUP BY customer_id

可用函数：

products_purchased

、

orders_placed

、

shopify_email.EVENT()

Math on metrics

指标计算

When aggregate functions are available:

shopifyql

FROM sales
SHOW sum(net_sales) / count(orders) AS aov

当聚合函数可用时：

shopifyql

FROM sales
SHOW sum(net_sales) / count(orders) AS aov

Aliases

别名

shopifyql

SHOW net_sales AS revenue, orders_count AS orders

shopifyql

SHOW net_sales AS revenue, orders_count AS orders

TOP N

shopifyql

FROM sales
SHOW top_5(product_title) AS top_products, net_sales AS revenue
GROUP BY top_products

The remainder is grouped as "Other".

shopifyql

FROM sales
SHOW top_5(product_title) AS top_products, net_sales AS revenue
GROUP BY top_products

剩下的数据会被统一归为“Other”。

2. Segment Query Language — Customer Segments

2. Segment Query Language — 客户分群

Segment queries are WHERE-only — no

FROM

SHOW

, or other clauses. They're used exclusively in the Shopify Customers API and Admin segment builder.

分群查询仅支持 WHERE 子句——没有

FROM

、

SHOW

或其他子句，仅可在 Shopify Customers API 和后台分群构建器中使用。

Basic syntax

基础语法

<attribute> <operator> <value>

Multiple conditions:

<condition1> AND <condition2> OR <condition3>

AND takes precedence over OR. Use parentheses to override:

email_subscription_status = 'SUBSCRIBED' AND (customer_countries CONTAINS 'US' OR amount_spent > 500)

Limits: max 10 clauses per query.

Important:
COUNT
,
SUM
,
MAX
,
MEDIAN
and other aggregate functions are not supported in Segment QL. Use direct attribute comparisons only (e.g.
amount_spent > 500
).

<attribute> <operator> <value>

多条件写法：

<condition1> AND <condition2> OR <condition3>

AND 的优先级高于 OR，可使用括号调整优先级：

email_subscription_status = 'SUBSCRIBED' AND (customer_countries CONTAINS 'US' OR amount_spent > 500)

限制：每个查询最多支持 10 个子句。

重要提示： Segment QL不支持
COUNT
、
SUM
、
MAX
、
MEDIAN
等聚合函数，仅可使用直接的属性比较（比如
amount_spent > 500
）。

Operators by data type

不同数据类型的运算符

Type	Operators
Boolean	`=` , `!=`
Date	`=` , `!=` , `>` , `>=` , `<` , `<=` , `BETWEEN`
Enum	`=` , `!=`
Float/Integer	`=` , `!=` , `>` , `>=` , `<` , `<=` , `BETWEEN`
String	`=` , `!=`
List	`CONTAINS` , `NOT CONTAINS`
Function	`MATCHES` , `NOT MATCHES`

类型	运算符
布尔值	`=` , `!=`
日期	`=` , `!=` , `>` , `>=` , `<` , `<=` , `BETWEEN`
枚举值	`=` , `!=`
浮点/整数	`=` , `!=` , `>` , `>=` , `<` , `<=` , `BETWEEN`
字符串	`=` , `!=`
列表	`CONTAINS` , `NOT CONTAINS`
函数	`MATCHES` , `NOT MATCHES`

Date formats

日期格式

Date values in Segment QL do not use quotes (unlike strings).

Absolute date:
```
2024-01-01
```
Absolute datetime:
```
2024-01-01T16:00:00
```
(shop timezone, 24h format)
Relative offset:
```
-7d
```
,
```
-2w
```
,
```
-1m
```
,
```
-1y
```
Named:
```
today
```
,
```
yesterday
```

last_order_date > -30d
first_order_date BETWEEN 2024-01-01 AND 2024-12-31
last_order_date BETWEEN -365d AND -90d

Date operators act on complete 24-hour days in the shop's timezone.

和字符串不同，Segment QL 中的日期值不需要使用引号包裹。

绝对日期：
```
2024-01-01
```
绝对时间：
```
2024-01-01T16:00:00
```
（店铺时区，24小时制）
相对偏移：
```
-7d
```
、
```
-2w
```
、
```
-1m
```
、
```
-1y
```
命名值：
```
today
```
、
```
yesterday
```

last_order_date > -30d
first_order_date BETWEEN 2024-01-01 AND 2024-12-31
last_order_date BETWEEN -365d AND -90d

日期运算符基于店铺时区的完整24小时天生效。

Core attributes

核心属性

Attribute	Type	Example
`email_subscription_status`	Enum	`= 'SUBSCRIBED'`
`sms_subscription_status`	Enum	`= 'SUBSCRIBED'`
`amount_spent`	Float	`>= 500.00`
`number_of_orders`	Integer	`> 5`
`customer_tags`	List<String>	`CONTAINS 'wholesale'` (case-insensitive)
`customer_countries`	List<Enum>	`CONTAINS 'US'`
`customer_cities`	List<Enum>	`CONTAINS 'US-CA-LosAngeles'`
`customer_regions`	List<Enum>	`CONTAINS 'NY'`
`customer_email_domain`	String	`= 'gmail.com'`
`customer_language`	String	`= 'en'`
`customer_account_status`	Enum	`= 'ENABLED'`
`customer_added_date`	Date	`> -90d`
`first_order_date`	Date	`< -365d`
`last_order_date`	Date	`> -30d`
`abandoned_checkout_date`	Date	`> -7d`
`predicted_spend_tier`	Enum	`= 'HIGH'`
`rfm_group`	Enum	`= 'CHAMPIONS'`
`product_subscription_status`	Enum	`= 'SUBSCRIBER'`
`companies`	Integer	`= 123456789` (B2B company ID)
`created_by_app_id`	Integer	`= 987654321`

Note on List<String>:

customer_tags

comparisons are case-insensitive. Enum-based lists (e.g.

customer_countries

) are case-sensitive.

属性	类型	示例
`email_subscription_status`	枚举	`= 'SUBSCRIBED'`
`sms_subscription_status`	枚举	`= 'SUBSCRIBED'`
`amount_spent`	浮点型	`>= 500.00`
`number_of_orders`	整数	`> 5`
`customer_tags`	列表<字符串>	`CONTAINS 'wholesale'` （不区分大小写）
`customer_countries`	列表<枚举>	`CONTAINS 'US'`
`customer_cities`	列表<枚举>	`CONTAINS 'US-CA-LosAngeles'`
`customer_regions`	列表<枚举>	`CONTAINS 'NY'`
`customer_email_domain`	字符串	`= 'gmail.com'`
`customer_language`	字符串	`= 'en'`
`customer_account_status`	枚举	`= 'ENABLED'`
`customer_added_date`	日期	`> -90d`
`first_order_date`	日期	`< -365d`
`last_order_date`	日期	`> -30d`
`abandoned_checkout_date`	日期	`> -7d`
`predicted_spend_tier`	枚举	`= 'HIGH'`
`rfm_group`	枚举	`= 'CHAMPIONS'`
`product_subscription_status`	枚举	`= 'SUBSCRIBER'`
`companies`	整数	`= 123456789` （B2B 企业 ID）
`created_by_app_id`	整数	`= 987654321`

列表<字符串>注意事项：

customer_tags

的比较不区分大小写，基于枚举的列表（比如

customer_countries

）区分大小写。

Function conditions

函数条件

products_purchased — by product ID, tag, or date:

products_purchased MATCHES ()
products_purchased MATCHES (id = 2012162031638)
products_purchased MATCHES (id IN (1012132033639, 2012162031638))
products_purchased MATCHES (id NOT IN (1012132033639))
products_purchased MATCHES (tag = 'sale', date > -90d)
products_purchased MATCHES (id = 1012132033639, date BETWEEN -12m AND today)

List can contain up to 500 IDs. Omitting

id

matches all products; omitting

date

matches all time.

orders_placed — by order attributes:

orders_placed MATCHES (financial_status = 'paid', date > -30d)

shopify_email.EVENT — by email campaign interaction (no

()

after event name):

shopify_email.opened MATCHES (activity_id = 5240029206, date > -30d)
shopify_email.clicked MATCHES (activity_id IN (5240029206, 1932881090))
shopify_email.bounced NOT MATCHES (activity_id = 5240029206, date BETWEEN -12m AND today)

Events:

bounced

clicked

delivered

marked_as_spam

opened

unsubscribed

List can contain up to 500 activity IDs.

anniversary() — yearly recurring dates (e.g. birthdays):

anniversary() MATCHES (date = today, attribute = 'birthdate')

customer_within_distance() — geo-proximity:

customer_within_distance() MATCHES (lat = -33.8688, lng = 151.2093, distance = 50, unit = 'km')

storefront_event — browsing behaviour:

storefront_event.product_viewed MATCHES (product_id = 1234567890, date > -7d)
storefront_event.collection_viewed MATCHES (collection_id = 987654321)

store_credit_accounts — customers with store credit:

store_credit_accounts MATCHES (balance > 0)

products_purchased — 按商品ID、标签或日期筛选：

products_purchased MATCHES ()
products_purchased MATCHES (id = 2012162031638)
products_purchased MATCHES (id IN (1012132033639, 2012162031638))
products_purchased MATCHES (id NOT IN (1012132033639))
products_purchased MATCHES (tag = 'sale', date > -90d)
products_purchased MATCHES (id = 1012132033639, date BETWEEN -12m AND today)

列表最多可包含500个ID，省略

id

则匹配所有商品，省略

date

则匹配全时间段。

orders_placed — 按订单属性筛选：

orders_placed MATCHES (financial_status = 'paid', date > -30d)

shopify_email.EVENT — 按邮件活动互动情况筛选（事件名称后不需要加

()

）：

shopify_email.opened MATCHES (activity_id = 5240029206, date > -30d)
shopify_email.clicked MATCHES (activity_id IN (5240029206, 1932881090))
shopify_email.bounced NOT MATCHES (activity_id = 5240029206, date BETWEEN -12m AND today)

事件类型：

bounced

、

clicked

、

delivered

、

marked_as_spam

、

opened

、

unsubscribed

列表最多可包含500个活动ID。

anniversary() — 每年重复的日期（比如生日）：

anniversary() MATCHES (date = today, attribute = 'birthdate')

customer_within_distance() — 地理邻近度筛选：

customer_within_distance() MATCHES (lat = -33.8688, lng = 151.2093, distance = 50, unit = 'km')

storefront_event — 浏览行为筛选：

storefront_event.product_viewed MATCHES (product_id = 1234567890, date > -7d)
storefront_event.collection_viewed MATCHES (collection_id = 987654321)

store_credit_accounts — 有店铺余额的客户：

store_credit_accounts MATCHES (balance > 0)

3. Query writing workflow

3. 查询编写工作流

When a user asks a business question, follow this process:

Identify the goal — analytics report (ShopifyQL) or customer segment (Segment QL)?
Pick the table — for ShopifyQL, identify the correct
```
FROM
```
table
Identify metrics vs dimensions — for
```
sales
```
, prefer pre-aggregated metrics directly; dimensions go in
```
GROUP BY
```
(and also in
```
SHOW
```
)
Add filters —
```
WHERE
```
for pre-aggregation,
```
HAVING
```
for post-aggregation
Set the date range — always include one unless the user wants all-time data

Verify keyword order —

FROM → SHOW → WHERE → GROUP BY → SINCE/UNTIL → HAVING → ORDER BY → LIMIT

Add visualisation if the user wants a chart

当用户提出业务问题时，遵循以下流程：

明确目标 — 是分析报告（ShopifyQL）还是客户分群（Segment QL）？
选择表 — 针对 ShopifyQL，确定正确的
```
FROM
```
表
区分指标和维度 — 对于
```
sales
```
表，优先直接使用预聚合指标；维度放在
```
GROUP BY
```
中（同时也要放到
```
SHOW
```
里）
添加过滤条件 — 聚合前过滤用
```
WHERE
```
，聚合后过滤用
```
HAVING
```
设置日期范围 — 除非用户需要全时段数据，否则必须包含日期范围

验证关键词顺序 —

FROM → SHOW → WHERE → GROUP BY → SINCE/UNTIL → HAVING → ORDER BY → LIMIT

如果用户需要图表，添加可视化配置

4. Common ecommerce patterns

4. 常见电商场景模板

Reusable starting points for typical Shopify store analytics and segmentation:

Top revenue products this month (pre-aggregated):

shopifyql

FROM sales
SHOW product_title, product_vendor, product_type,
     net_items_sold, gross_sales, discounts, returns, net_sales, taxes, total_sales
WHERE product_title IS NOT NULL
GROUP BY product_title, product_vendor, product_type
DURING last_month
ORDER BY total_sales DESC
LIMIT 20

Channel attribution:

shopifyql

FROM sessions
SHOW referrer_source, sessions_count, converted_sessions
GROUP BY referrer_source
SINCE -30d UNTIL today
ORDER BY converted_sessions DESC

Monthly revenue trend:

shopifyql

FROM sales
SHOW net_sales, total_sales, orders_count
TIMESERIES month
SINCE -3m UNTIL today

High-value customer segment (for Shopify Customers):

amount_spent > 500 AND number_of_orders >= 3 AND last_order_date > -90d

Re-engagement segment:

last_order_date BETWEEN -365d AND -90d AND number_of_orders > 1

Wholesale/B2B segment:

customer_tags CONTAINS 'wholesale' OR amount_spent > 2000

典型 Shopify 店铺分析和分群的可复用模板：

本月收入Top商品（预聚合）：

shopifyql

FROM sales
SHOW product_title, product_vendor, product_type,
     net_items_sold, gross_sales, discounts, returns, net_sales, taxes, total_sales
WHERE product_title IS NOT NULL
GROUP BY product_title, product_vendor, product_type
DURING last_month
ORDER BY total_sales DESC
LIMIT 20

渠道归因：

shopifyql

FROM sessions
SHOW referrer_source, sessions_count, converted_sessions
GROUP BY referrer_source
SINCE -30d UNTIL today
ORDER BY converted_sessions DESC

月度收入趋势：

shopifyql

FROM sales
SHOW net_sales, total_sales, orders_count
TIMESERIES month
SINCE -3m UNTIL today

高价值客户分群（适用于 Shopify 客户后台）：

amount_spent > 500 AND number_of_orders >= 3 AND last_order_date > -90d

召回客户分群：

last_order_date BETWEEN -365d AND -90d AND number_of_orders > 1

批发/B2B分群：

customer_tags CONTAINS 'wholesale' OR amount_spent > 2000

5. Debugging checklist

5. 调试检查清单

When a query errors or returns unexpected results:

Keyword order correct? (

FROM → SHOW → WHERE → GROUP BY → SINCE → HAVING → ORDER → LIMIT

)

String values in single quotes (not double)? Dates do NOT use quotes in Segment QL.
Filtering on a dimension in
```
WHERE
```
, not a metric?
```
GROUP BY
```
included when showing a dimension?
Segment query doesn't have
```
FROM
```
/
```
SHOW
```
(those aren't valid in Segment QL)?
```
AND
```
precedence understood? (use parentheses for
```
OR
```
groups)
Rate limit hit? (429 error → wait 60 seconds)
"Feature not supported: Could not find valid function sum()" → Store plan doesn't support
```
sum()
```
. Use pre-aggregated metrics:
```
net_sales
```
instead of
```
sum(net_sales)
```
,
```
orders_count
```
instead of
```
count(orders)
```
.
Unexpected "no valid table data" or blank results → Check
```
parseErrors
```
in the raw API response — it contains the specific reason (unsupported function, syntax error, plan restriction).

See

references/tables.md

for full lists of available dimensions and metrics per table.

当查询报错或返回结果不符合预期时：

关键词顺序是否正确？（

FROM → SHOW → WHERE → GROUP BY → SINCE → HAVING → ORDER → LIMIT

）

字符串值是否使用单引号（不是双引号）包裹？Segment QL 中的日期不需要加引号。
```
WHERE
```
中过滤的是维度，不是指标？
展示维度时是否添加了
```
GROUP BY
```
？
分群查询没有包含
```
FROM
```
/
```
SHOW
```
？（这两个在 Segment QL 中无效）
是否清楚
```
AND
```
的优先级？（
```
OR
```
组合的条件请用括号包裹）
是否触发了速率限制？（429错误 → 等待60秒）
“Feature not supported: Could not find valid function sum()” → 店铺套餐不支持
```
sum()
```
，请使用预聚合指标：用
```
net_sales
```
代替
```
sum(net_sales)
```
，用
```
orders_count
```
代替
```
count(orders)
```
。
意外返回“no valid table data”或空白结果 → 检查原始 API 响应中的
```
parseErrors
```
字段，里面会包含具体原因（不支持的函数、语法错误、套餐限制）。

查看

references/tables.md

可获取每个表可用的维度和指标完整列表。

6. Execution

6. 执行查询

When the user wants to run a query (trigger phrases: "run it", "execute", "run the query", "what are the results", "show me the data", "get the data", "fetch results"):

Ensure a valid ShopifyQL query has been written (write one if needed)
Hand off to the
shopifyql-executor
agent — do NOT attempt to run the query yourself
The executor agent handles credentials, SDK invocation, and output formatting

If no credentials are configured yet, direct them to run

/shopifyql-setup

first.

当用户想要运行查询时（触发词：“run it”、“execute”、“run the query”、“what are the results”、“show me the data”、“get the data”、“fetch results”）：

确保已经编写了有效的 ShopifyQL 查询（如果还没有则先编写）
交给
shopifyql-executor
Agent 处理 — 不要尝试自己运行查询
执行 Agent 会处理凭证、SDK 调用和输出格式

如果还没有配置凭证，请引导用户先运行

/shopifyql-setup

。

Notes for execution

执行注意事项

Queries with
```
_ms
```
columns (
```
lcp_p75_ms
```
,
```
inp_p75_ms
```
) need
```
--raw
```
flag — the executor handles this automatically
Strip any
```
VISUALIZE
```
lines before passing to the executor — the API rejects them
```
WITH TOTALS
```
adds a null-first-column row that the executor filters out automatically

包含
```
_ms
```
列的查询（
```
lcp_p75_ms
```
、
```
inp_p75_ms
```
）需要
```
--raw
```
参数 — 执行 Agent 会自动处理
传递给执行 Agent 前请删除所有
```
VISUALIZE
```
行 — API 会拒绝包含该子句的查询
```
WITH TOTALS
```
会添加一个首列为空的行，执行 Agent 会自动过滤

After execution

执行后

Stay in the conversation to help with:

Explain the results — interpret the data in plain language
Refine the query — adjust filters, date ranges, groupings based on what was returned
Compare — help the user understand trends or outliers in the results

请继续跟进，协助用户完成：

结果解释 — 用通俗的语言解读数据
查询优化 — 根据返回结果调整过滤条件、日期范围、分组规则
对比分析 — 帮助用户理解结果中的趋势或异常值