# 📊 Shopify Sessions 表完整字段参考

- Link: https://yjyj.net/learn/shopify/7768.html
- Published: 2026-02-20T12:43:14+08:00
- Author: 小 虾

⚡ 生猛大蝦编辑部 · 30 秒核心看点

 * 指标字段可直接 SHOW 自动聚合；维度字段通常要配合 GROUP BY 才能出结果。
 * 文章重点梳理了 session_country、session_device_type 等易混字段，避免把 location_*、
   device_* 误写进查询。
 * 从流量来源、UTM 到页面与搜索维度，本文更像一份 ShopifyQL 实战字段字典，适合查表
   即用。

## 一、指标 (Metrics) – 可直接 SHOW

这些字段会自动聚合,不需要 GROUP BY:

| 字段名 | 说明 | 用途 | 
| `sessions` | 会话总数 | 追踪网站流量 | 
| `online_store_visitors` | 在线商店访客数 | 追踪独立访客 | 
| `pageviews` | 页面浏览量 | 衡量内容参与度 | 
| `average_session_duration` | 平均会话时长 | 评估用户参与度 | 
| `bounce_rate` | 跳出率 | 识别需改进的页面 | 
| `conversion_rate` | 转化率 | 衡量销售效果 | 
| `sessions_with_cart_additions` | 加购会话数 | 追踪购物意向 | 
| `sessions_that_reached_checkout` | 到达结账的会话数 | 分析结账漏斗 | 
| `sessions_that_completed_checkout` | 完成结账的会话数 | 追踪转化成功 |

## 二、维度 (Dimensions) – 需要 GROUP BY

### 📅 时间维度

| 字段名 | 说明 | 
| `day` | 按天分组 | 
| `week` | 按周分组 | 
| `month` | 按月分组 | 
| `year` | 按年分组 | 
| `hour` | 按小时分组 |

### 🌍 地理位置维度

| 字段名 | 说明 | 注意 | 
| `session_country` | 会话国家 | ⚠️ 不是 `location_country` | 
| `session_country_code` | 国家代码 |  | 
| `session_region` | 会话地区/州 | ⚠️ 不是 `location_region` | 
| `session_city` | 会话城市 | ⚠️ 不是 `location_city` |

### 📱 设备维度

| 字段名 | 说明 | 注意 | 
| `session_device_type` | 设备类型(桌面/移动/平板) | ⚠️ 不是 `device_type` | 
| `session_browser` | 浏览器类型 | ⚠️ 不是 `device_browser` | 
| `session_browser_version` | 浏览器版本 | ⚠️ 不是 `device_browser_version` | 
| `session_device_os` | 操作系统 | ⚠️ 不是 `device_os` | 
| `session_device_os_version` | 操作系统版本 | ⚠️ 不是 `device_os_version` | 
| `browser_family` | 浏览器系列 |  | 
| `device_type` | 设备类型(用于性能分析) |  |

### 🔗 流量来源维度

| 字段名 | 说明 | 
| `referrer_source` | 推荐来源类型(自然搜索、邮件等) | 
| `referrer_domain` | 推荐网站域名 | 
| `referrer_site` | 推荐网站 | 
| `referrer_url` | 具体的外部推荐页面 | 
| `referrer_terms` | 搜索引擎查询词 |

### 📊 UTM 营销参数

| 字段名 | 说明 | 
| `utm_source` | UTM 来源(google、facebook等) | 
| `utm_medium` | UTM 媒介(cpc、email、social) | 
| `utm_campaign` | UTM 活动名称 | 
| `utm_content` | UTM 内容 | 
| `utm_term` | UTM 关键词 |

### 📄 页面维度

| 字段名 | 说明 | 
| `landing_page_url` | 着陆页完整 URL | 
| `landing_page_path` | 着陆页路径 | 
| `landing_page_type` | 着陆页类型 | 
| `page_type` | 页面类型(产品、集合等) | 
| `page_host` | 页面主机 | 
| `page_path` | 页面路径 |

### 🔍 搜索相关维度

| 字段名 | 说明 | 
| `search_query` | 站内搜索查询词 | 
| `search_query_intent` | 搜索意图 | 
| `search_result_was_clicked` | 是否点击搜索结果 | 
| `search_results_were_returned` | 是否返回结果 | 
| `is_product_search_query` | 是否产品搜索 | 
| `is_article_search_query` | 是否文章搜索 | 
| `is_page_search_query` | 是否页面搜索 | null### 🤖 会话行为维度 | 
| 字段名 | 说明 | 
| ——- | —— | 
| `human_or_bot_session` | 人类或机器人会话 | 
| `session_bounced` | 是否跳出 | 
| `session_duration` | 会话时长(秒) | 
| `session_id` | 会话唯一标识符 | 
| `micro_session_id` | 微会话标识符 | null### 🏪 应用/店面维度 | 
| 字段名 | 说明 | 
| ——- | —— | 
| `app` | 客户端类型(Hydrogen、在线商店等) | 
| `shop_mini_name` | Shop Mini 名称 | 
| `shop_post_purchase_discount_code` | 购后折扣码 | null### 📝 表单相关维度 | 
| 字段名 | 说明 | 
| ——- | —— | 
| `form_id` | 表单标识符 | 
| `form_type` | 表单类型(弹窗/内嵌) | 
| `form_page_type` | 表单所在页面类型 | null### ⚡ 性能指标维度 | 
| 字段名 | 说明 | 
| ——- | —— | 
| `largest_contentful_paint_target` | LCP 测量资源 | 
| `cumulative_layout_shift_target` | CLS 测量资源 | 
| `interaction_to_next_paint_target` | INP 测量资源 | null## 三、ShopifyQL 语法规则 |

### ✅ 基本语法结构

    ```wp-block-code
    FROM table_name
    SHOW metric1, metric2, ...
    [WHERE condition]
    [GROUP BY dimension1, dimension2, ...]
    [TIMESERIES time_dimension]
    [WITH TOTALS, GROUP_TOTALS, PERCENT_CHANGE]
    [HAVING condition]
    [SINCE date_offset]
    [UNTIL date_offset]
    [COMPARE TO date_offset]
    [ORDER BY column ASC|DESC]
    [LIMIT number]
    [VISUALIZE column TYPE visualization_type]
    ```

### 📋 关键规则

 1. **必需关键字**: `FROM` 和 `SHOW` 是必需的
 2. **关键字顺序**: 必须按上述顺序排列
 3. **指标 vs 维度**:
 4.  * **指标**0 可以直接 SHOW,会自动聚合
     * **维度**
        - 必须在null`GROUP BY` 中声明null4. **时间序列**: 使用 `TIMESERIES day/week/
          month` 自动填充日期
 5. **过滤条件**: `WHERE` 用于过滤,值必须用单引号 `'`
 6. **聚合后过滤**: `HAVING` 用于过滤聚合后的结果null## 四、常用查询示例

### 1️⃣ 基础时间序列查询

    ```wp-block-code
    FROM sessions
    SHOW sessions, online_store_visitors
    WHERE human_or_bot_session = 'human'
    TIMESERIES day
    SINCE -30d
    UNTIL today
    ORDER BY day ASC
    LIMIT 1000
    ```

### 2️⃣ 按来源分组

    ```wp-block-code
    FROM sessions
    SHOW sessions, online_store_visitors, referrer_source
    GROUP BY referrer_source
    WHERE human_or_bot_session = 'human'
    SINCE -30d
    UNTIL today
    ORDER BY sessions DESC
    LIMIT 100
    ```

null### 3️⃣ 按设备类型和国家分组

    ```wp-block-code
    FROM sessions
    SHOW sessions, nullonline_store_visitors,
         session_device_type,
         session_country
    GROUP BY session_device_type, session_country
    WHERE human_or_bot_session = 'human'
    SINCE -30d
    UNTIL today
    ORDER BY sessions DESC
    LIMIT 100
    ```

null### 4️⃣ 转化漏斗分析

    ```wp-block-code
    FROM sessions
    SHOW sessions,
         sessions_with_cart_additions,
         sessions_that_reached_checkout,
         sessions_that_completed_checkout,
         conversion_rate
    WHERE human_or_bot_session = 'human'
    TIMESERIES day
    SINCE -30d
    UNTIL today
    ORDER BY day ASC
    LIMIT 1000
    ```

### 5️⃣ UTM 营销分析

    ```wp-block-code
    FROM sessions
    SHOW sessions,
         online_store_visitors,
         utm_source,
         utm_medium,
         utm_campaign
    GROUP BY utm_source, utm_medium, utm_campaign
    WHERE utm_source IS NOT NULL
    SINCE -30d
    UNTIL today
    ORDER BY sessions DESC
    LIMIT 100
    ```

### 6️⃣ 多维度时间序列

    ```wp-block-code
    FROM sessions
    SHOW sessions,
         day,
         referrer_source,
         session_device_type
    GROUP BY day, referrer_source, session_device_type
    WHERE human_or_bot_session = 'human'
    TIMESERIES day
    SINCE -7d
    UNTIL today
    ORDER BY day ASC, sessions DESC
    LIMIT 1000
    ```

### 7️⃣ 带同比的查询

    ```wp-block-code
    FROM sessions
    SHOW sessions, online_store_visitors
    WHERE human_or_bot_session = 'human'
    TIMESERIES day
    WITH TOTALS, PERCENT_CHANGE
    SINCE startOfDay(-7d)
    UNTIL today
    COMPARE TO previous_period
    ORDER BY day ASC
    LIMIT 1000
    ```

## 五、常见错误及修正

| null❌ 错误写法 | ✅ 正确写法 | 说明 | 
| `SHOW timestamp` | `TIMESERIES day` | 使用时间序列而非时间戳 | 
| `SHOW location_country` | `SHOW session_country` | 字段名前缀是null`session_` | 
| `SHOW device_type` | `SHOW session_device_type` | 设备字段需要 `session_` 前缀 | 
| `SHOW referrer_source` (无 GROUP BY) | `GROUP BY referrer_source` | 维度必须在 GROUP BY 中 | 
| `WHERE is_bot = true` | `WHERE human_or_bot_session = 'bot'` | 使用正确的字段名和值 | 
| `SINCE "2026-01-20"` | `SINCE -30d` 或 `SINCE startOfDay(-30d)` | 使用相对日期 | null## 六、最佳实践 |

 1. ✅ **过滤机器人流量**: 始终使用 `WHERE human_or_bot_session = 'human'`
 2. ✅ **使用 TIMESERIES**: 自动填充缺失日期,避免数据断层
 3. ✅ **限制结果数量**: 使用 `LIMIT` 避免查询超时
 4. ✅ **合理使用 GROUP BY**: 只在需要分组时使用维度
 5. ✅null**注意字段前缀**: Sessions 表的地理和设备字段都有 `session_` 前缀
 6. ✅ **使用相对日期**: `-30d`, `today`, `startOfDay(-7d)` 等

这份参考指南应该能帮助您正确构建 Sessions 查询!如果有任何疑问,请随时告诉我。null

❓ 延伸问答与排错指南（FAQ）

Shopify Sessions 表里哪些字段能直接 SHOW？

文中列出的指标类字段可直接 SHOW，系统会自动聚合，不需要 GROUP BY。比如 sessions、
online_store_visitors、pageviews、average_session_duration、bounce_rate、conversion_rate，
以及加购、到达结账、完成结账等转化指标都属于这一类。

为什么维度字段查询时要加 GROUP BY？

因为维度字段用于切分数据，不加 GROUP BY 往往只会得到汇总结果或报错。像 day、session_country、
session_device_type、utm_source、page_path 这类字段，通常要和指标一起分组，才能按
时间、地区、设备或来源看趋势。

session_country 和 location_country 有什么区别？

文章明确提醒 session_country 才是会话国家字段，不是 location_country；同理还有 session_region、
session_city、session_device_type 等命名。实操时要优先按 Sessions 表的字段名写，
避免把别的维度名误套进 ShopifyQL。

📚 【[Shopify 学习](https://yjyj.net/category/learn/shopify)】专栏延伸阅读与热门
精选（[全站文章归档](https://yjyj.net/archive)）：

 * [Shopify Sessions 数据维度表](https://yjyj.net/learn/shopify/7764.html)
 * [解锁 Shopify 与自建站商家的“代理式电商” (Agentic Commerce) 潜力](https://yjyj.net/learn/7749.html)
 * [npm : 无法加载文件 xxx，因为在此系统上禁止运行脚本 的解决办法](https://yjyj.net/learn/7774.html)
 * [解决: windows 环境下 无法将“git”项识别为 cmdlet、函数、脚本文件或可运行程序的名称](https://yjyj.net/learn/7776.html)
 * 热门必读[程序员漫游指南](https://yjyj.net/what/5830.html)
 * 热门必读[升级一下iptables](https://yjyj.net/learn/centos/3208.html)
