> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AftersellQL (AQL) 参考

> AftersellQL 查询语言参考：可用的指标和维度、AQL 子句语法及示例，以及 Explorer 的时区规则。

你在 [Explorer](/zh/aftersell/reports_explorer) 中构建的每个查询都是一条 **AftersellQL (AQL)** 语句。大多数情况下，你通过可视化方式构建查询，从不需要手动编写 AQL；本页是关于可选指标和维度、AQL 文本形式以及时区规则的参考。

<div id="available-metrics">
  ## 可用指标
</div>

以下是你可以选择的指标，分组方式与指标选择器中的分组相同。

<div id="revenue-profit">
  ### 收入与利润
</div>

| 指标 | 说明 |
| - | - |
| **Revenue** | 以商店本币计的 upsell 收入。 |
| **Revenue (USD)** | 换算为美元的 upsell 收入，用于跨币种比较。 |
| **Revenue Per Visit** | 每个曝光会话的 upsell 收入。无法按产品、展示位置、漏斗或设备细分。 |
| **Avg. Conversion Value** | 每个已接受优惠的收入。也称为平均 upsell 价值（Average Upsell Value）。 |
| **Upsell Revenue Per Order** | upsell 收入（USD）除以订单总数。仅限商店级别。 |
| **Product Profit** | upsell 产品的收入减去销货成本（COGS）。依赖商家配置的 COGS，因此应视为估算值：未追踪成本的产品会将收入报告为利润，且成本覆盖范围因商店而异。仅限产品粒度；无法按漏斗、展示位置或设备细分。 |

<div id="conversions">
  ### 转化
</div>

| 指标 | 说明 |
| - | - |
| **Conversions** | 接受优惠事件的数量。一个已接受的优惠即一次转化，因此接受两个优惠的会话计为两次。 |
| **Accept Rate** | 基于会话：看到优惠并至少接受了一个优惠的会话所占比例。它独立于 Conversions 计算，来自不同的汇总，因此并不等于 Conversions ÷ Impressions。 |
| **Units Sold** | 通过 upsell 优惠售出的总件数。 |
| **Decline Rate** | 被明确拒绝的 post-purchase 优惠所占百分比。仅限 post-purchase。 |

<div id="engagement">
  ### 互动
</div>

| 指标 | 说明 |
| - | - |
| **Impressions** | 看到优惠的独立会话数。 |
| **Show Rate** | 产生曝光的决策所占百分比。 |

<div id="store-performance">
  ### 商店表现
</div>

| 指标 | 说明 |
| - | - |
| **Total Store Revenue** | Shopify 已付款订单的总收入。仅限商店级别；无法按触点、漏斗、展示位置或设备细分。 |
| **Orders** | Shopify 已付款订单总数。仅限商店级别。 |
| **Average Total Order Value** | 商店收入除以订单数。商店级别的平均订单价值。 |

<div id="rokt-network">
  ### Rokt 网络
</div>

| 指标 | 说明 |
| - | - |
| **Rokt Revenue** | 归因于你商店的 Rokt 网络收入。 |
| **Rokt Transactions** | 你商店的 Rokt 网络交易数。 |
| **Rokt Revenue / Transaction** | 每个时间分桶内 Rokt 收入除以交易数。 |
| **Rokt Impressions** | 你商店各展示位置上的 Rokt 网络总曝光次数。与 upsell 的 **Impressions** 不同。 |
| **Rokt Referrals** | Rokt 网络推荐次数，即将购物者引导至 Rokt 合作伙伴的正向互动。 |

<div id="dimensions">
  ## 维度
</div>

维度按某个属性对指标进行细分。并非所有维度都与每个指标兼容；Explorer 会自动阻止不兼容的组合（例如，**Decline rate** 和 **Show rate** 无法按 **Currency** 细分）。

<div id="available-dimensions">
  ### 可用维度
</div>

| 维度 | 说明 |
| - | - |
| **Date** | 按天、周或月对结果分组。 |
| **Surface** | upsell 触点：PPU（post-purchase）、Checkout、Thank You Page 或 Cart。 |
| **Funnel** | 优惠所属的具体漏斗。 |
| **Product** | 被 upsell 的产品。 |
| **Placement** | 漏斗中的展示位置。 |
| **Device** | 设备类型：Mobile、Desktop 或 Unknown。没有单独的平板电脑值。 |
| **Currency** | ISO 货币代码（例如 USD、EUR、GBP）。适用于多币种商店。 |

<div id="unavailable-dimensions">
  ### 不可用维度
</div>

以下维度仍在开发中。它们会显示在选择器中，但在实现之前，对每个指标都显示为"Not compatible"。

| 维度 | 说明 |
| - | - |
| **Flow type** | upsell 流程的类型。 |
| **Experiment** | A/B 测试或实验变体。 |
| **Outcome** | 决策结果（例如 eligible、out of stock）。 |
| **Reason code** | 决策结果的原因。 |
| **Scope** | 决策范围（Flow、Experience、Placement 或 ItemSlot）。 |
| **Response type** | 优惠响应（Accepted、Declined 或 Timeout）。 |

<div id="aql-statement-syntax">
  ## AQL 语句语法
</div>

一条 AQL 语句是由多个子句组成的单个问题。只有 `SELECT` 和时间范围（`SINCE`）是必需的；其他都是可选的。包含可选子句时，它们必须按以下顺序出现：

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT    <metrics>                    -- what to measure (required)
WHERE     <filters>                    -- narrow the data
GROUP BY  <dimensions>                 -- break the numbers down
SINCE     <time range>                 -- the period to cover (required)
GRAIN     <time grain>                 -- bucket size for time series
COMPARE   <comparison>                 -- compare against another period
CHART     <visualization>              -- how to display the result
TIMEZONE  "<timezone>"                 -- timezone for date buckets
ORDER BY  <field> <direction>          -- sort the results
LIMIT     <number>                     -- cap the number of rows
```

一个最简示例，过去 30 天每日的 upsell 收入和接受率：

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
```

<Note>
  关键字不区分大小写（`SELECT` 和 `select` 都可以），语句不以分号结尾。字符串值用双引号括起来；数字和列表则不需要。
</Note>

<div id="select-and-group-by">
  ### SELECT 和 GROUP BY
</div>

* **`SELECT`** 列出要衡量的指标，以逗号分隔，例如 `SELECT revenue, impressions, accept_rate`。
* **`GROUP BY`** 按一个或多个维度细分这些指标，例如 `date`、`device`、`surface` 或 `funnel`。没有 `GROUP BY` 时，你会得到整个期间的单一总计值。

<div id="filtering-with-where">
  ### 使用 WHERE 筛选
</div>

`WHERE` 在衡量之前缩小数据范围。使用 `AND` 组合多个条件。

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue
WHERE device = "mobile"
GROUP BY date
SINCE last_month
GRAIN day
```

<Warning>
  `impressions`、`accept_rate` 和 `rpv` **无法**按设备、漏斗、展示位置或产品进行筛选或分组；它们的源汇总中没有这些列。在选择了其中任一指标的查询中添加 `WHERE device = "mobile"` 会被拒绝，并提示 `metric "impressions" cannot be filtered by "device"`。
</Warning>

支持的比较运算符有 `=`、`!=`、`IN`、`NOT IN`、`>`、`<`、`>=` 和 `<=`。使用 `IN` 加列表可匹配多个值：

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
WHERE surface IN ["PPU", "Checkout"]
```

`experiment` **不是**可筛选字段；它没有汇总数据源，因此 `WHERE experiment IN [...]` 会被拒绝，并提示 `filters on "experiment" are not supported.`

**funnel** 筛选器支持多选：**is one of**（`IN`）仅包含所选漏斗，**is not one of**（`NOT IN`）则排除它们。当你按 **Funnel** 分组并应用 **is one of** 筛选器时，图表会为每个所选漏斗显示一条线，不会合并为"Other"。

<div id="time-ranges-and-comparisons">
  ### 时间范围与比较
</div>

每个查询都需要一个时间范围，通过 `SINCE` 设置：

| 形式 | 示例 | 含义 |
| - | - | - |
| 预设 | `SINCE last_30d` | 截至**昨天**（UTC）的滚动窗口。进行中的当天会被刻意排除，因此 `last_1d` 仅表示昨天，`this_month` 表示从 1 日到昨天。 |
| 自定义窗口 | `SINCE 2026-07-02 UNTIL 2026-07-05` | 固定范围，使用 ISO 日期（`YYYY-MM-DD`）。 |

可用的预设：`last_1d`、`last_7d`、`last_30d`、`last_90d`、`this_month`、`last_month` 和 `this_year`。

* **`GRAIN`** 设置时间序列的分桶大小：`day`、`week` 或 `month`。（`hour` 可以被解析，但没有汇总提供按小时的数据，因此此类查询会被拒绝，并提示 `group_by / time_grain combination is not supported.`）
* **`COMPARE`** 叠加第二个期间。使用 `previous_period`，即紧接在前、长度相同的窗口。`previous_year` 在 Compare 选择器中被隐藏，因为数据仓库中没有 2026 年 2 月之前的数据；它在 AQL 中仍可输入，只是为了让之前保存的查询能继续被解析。

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- A four-day sale vs the four days immediately before it
SELECT revenue, impressions, accept_rate
GROUP BY date
SINCE 2026-07-02 UNTIL 2026-07-05
GRAIN day
COMPARE previous_period
```

<Note>
  报告数据从 **2026 年 2 月**开始，因此早于此时间的窗口在两个期间都会返回空结果。
</Note>

<div id="choosing-a-chart">
  ### 选择图表
</div>

* **`CHART`** 设置结果的显示方式：`scorecard`、`line_chart`、`bar_chart`、`area_chart`、`funnel_chart` 或 `table`。
* **`TIMEZONE`** 设置用于日期分桶的时区，以带引号的 IANA 名称表示，例如 `TIMEZONE "America/New_York"`。默认为 UTC（参见[时区](#timezones)）。

`funnel_chart` 类型有特定要求：

* **Placement 模式。** 按 `placement` 分组并选择一个指标。各阶段按标准展示位置顺序排列（先默认 upsell，再 downsell，然后是其他 upsell）。只会绘制第一个指标；其他指标会在脚注中注明。
* **Metric 模式。** 选择两个或更多指标，且不使用 `GROUP BY`。每个指标按查询顺序成为一个漏斗阶段（例如，`SELECT impressions, conversions` 显示从曝光到转化的流失）。所有指标必须使用相同的单位。

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Placement funnel: conversion drop-off across placements
SELECT conversions
GROUP BY placement
SINCE last_30d
CHART funnel_chart
```

<Warning>
  Placement 模式需要一个可以按展示位置细分的指标。`impressions`、`accept_rate` 和 `rpv` 不行；对于这些指标，漏斗图会显示"These metrics can't be grouped by placement"。
</Warning>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Metric funnel: impressions to conversions drop-off
SELECT impressions, conversions
SINCE last_30d
CHART funnel_chart
```

<div id="sorting-and-limiting">
  ### 排序与限制
</div>

* **`ORDER BY`** 按指标或维度对结果排序，使用 `ASC` 或 `DESC`。
* **`LIMIT`** 限制返回的行数，适用于"前 N 名"类问题。

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Top 20 products by upsell revenue this month
SELECT revenue, conversions, avg_conversion_value
GROUP BY product
SINCE this_month
ORDER BY revenue DESC
LIMIT 20
```

<div id="more-examples">
  ### 更多示例
</div>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Daily performance vs the previous period
SELECT revenue, impressions, conversions, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
COMPARE previous_period
```

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Mobile vs desktop revenue over the last 90 days
SELECT revenue
GROUP BY device
SINCE last_90d
ORDER BY revenue DESC
```

<Note>
  `impressions`、`accept_rate` 和 `rpv` 无法按设备细分；它们的汇总粒度为商店 × 触点 × 天，没有设备列。进行设备比较时，请使用 `revenue`（或其他来源于转化数据的指标）。
</Note>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Which surface is driving the most revenue?
SELECT revenue, impressions, accept_rate
GROUP BY surface
SINCE last_30d
ORDER BY revenue DESC
```

<div id="timezones">
  ## 时区
</div>

默认情况下，查询以 UTC 运行。你可以覆盖时区，使按日期分桶的结果反映当地时间（工具栏操作步骤请参见[设置时区](/zh/aftersell/reports_explorer#setting-a-timezone)）。

<Note>
  包含 **Impressions**、**Accept Rate** 或 **Revenue Per Visit** 的查询始终以 UTC 对日期分桶，无论你选择哪个时区，因为这些指标来源于按 UTC 天上报的每日汇总。如果一个查询将其中一个指标与其他指标混合，整个结果集会回退到 UTC，以保持日期分桶对齐。
</Note>

<div id="the-timezone-clause">
  ### TIMEZONE 子句
</div>

使用 `TIMEZONE` 子句直接在 AQL 中指定时区，该子句位于 `CHART` 和 `ORDER BY` 之间：

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT ...
CHART ...
TIMEZONE "Asia/Tokyo"
ORDER BY ...
```

存在该子句时，它会覆盖该查询的工具栏选择，并在你保存和重新加载时保留。

<div id="available-timezones">
  ### 可用时区
</div>

选择器（以及 `TIMEZONE` 子句）仅接受一个由十个时区组成的固定集合。任何其他 IANA 时区都会被视为不支持而被拒绝。

| 时区 | 示例地点 |
| - | - |
| UTC | 协调世界时 |
| America/New\_York | 纽约（ET） |
| America/Chicago | 芝加哥（CT） |
| America/Denver | 丹佛（MT） |
| America/Los\_Angeles | 洛杉矶（PT） |
| Europe/London | 伦敦（GMT/BST） |
| Europe/Paris | 巴黎（CET/CEST） |
| Asia/Tokyo | 东京（JST） |
| Asia/Singapore | 新加坡（SGT） |
| Australia/Sydney | 悉尼（AEST/AEDT） |

<div id="account-default-and-how-timezone-affects-results">
  ### 账户默认值以及时区对结果的影响
</div>

如果在分析设置中启用了 **Lock reporting timezone**，选择 **Account default** 将使用该锁定的时区（工具栏会显示解析后的时区，例如 **Timezone: Account default (Paris (CET))**）。分析设置页面接受完整的 IANA 列表，但 Reports 仅支持上述十个时区；如果你锁定的时区不在其中，**Account default** 会静默解析为 UTC。如果未启用 **Lock reporting timezone**，**Account default** 会回退到 UTC。

设置时区后，日期分桶将使用当地时间而非 UTC。例如，发生在 `2026-03-29T01:30:00Z` 的事件在纽约（ET）属于 3 月 28 日，而在巴黎（CET）属于 3 月 29 日。未设置时区的查询（包括之前保存的查询）将继续以 UTC 运行。