查询参考(Query)
查询参考(Query)
Section titled “查询参考(Query)”根查询入口,共五个查询:
| 查询 | 返回 | 用途 |
|---|---|---|
dailyMetrics |
[DailyMetric!]! |
每日客流核心指标 |
hourlyMetrics |
[HourlyMetric!]! |
每小时客流核心指标 |
poiMetrics |
[PoiMetric!]! |
兴趣点(柜台/出入口/通道)指标 |
customerProfiles |
[CustomerProfile!]! |
顾客档案:人级游逛步骤 + 店员介入时段 |
peoplePaths |
[PeoplePath!]! |
按人的店内游逛链路 |
flowEvents |
[FlowEvent!]! |
镜头区域进出事件明细 |
dailyMetrics / hourlyMetrics / peoplePaths / flowEvents 使用同一套公共参数:
| 参数 | 类型 | 说明 |
|---|---|---|
storeId |
Int! |
门店 ID |
startDate |
String! |
起始日期,YYYY-MM-DD(闭区间,含当天) |
endDate |
String! |
结束日期,YYYY-MM-DD(闭区间,含当天) |
poiMetrics 的参数不同(支持 ISO8601 时间与类型过滤),见下文。
dailyMetrics
Section titled “dailyMetrics”按日返回客流核心指标。字段见 DailyMetric。
query { dailyMetrics(storeId: 1, startDate: "2026-07-01", endDate: "2026-07-31") { date passByVisits enteringPeople enteringVisits receptionPeople dwellPeople servedPeople serviceDurationSeconds counterLingerPeople counterLingerDurationSeconds counterLingerAvgSeconds }}hourlyMetrics
Section titled “hourlyMetrics”按小时返回客流核心指标。字段与 dailyMetrics 一致(多一个 hour),字段说明见 DailyMetric。
query { hourlyMetrics(storeId: 1, startDate: "2026-07-01", endDate: "2026-07-01") { date hour passByVisits enteringPeople enteringVisits receptionPeople dwellPeople servedPeople serviceDurationSeconds counterLingerPeople counterLingerDurationSeconds counterLingerAvgSeconds }}customerProfiles
Section titled “customerProfiles”按人返回顾客档案:每个顾客的游逛步骤(柜台集进入/离开时间)与店员介入时段(with staff 的开始/结束时间)。字段见 CustomerProfile。
参数:与 poiMetrics 相同的日期参数(支持 ISO8601,可精确到小时):
| 参数 | 类型 | 说明 |
|---|---|---|
storeId |
Int! |
门店 ID |
startAt |
String |
起始时间,ISO8601 含时区偏移,如 2026-08-31T10:00:00+08:00 |
endAt |
String |
结束时间,排他边界,如当天数据传次日零点 |
startDate |
String |
已废弃:请使用 startAt(YYYY-MM-DD,闭区间) |
endDate |
String |
已废弃:请使用 endAt(YYYY-MM-DD,闭区间) |
query { customerProfiles( storeId: 1 startAt: "2026-08-31T00:00:00+08:00" endAt: "2026-09-01T00:00:00+08:00" ) { peopleId steps { poi { id poiType name serviceThresholdSeconds } enterTime leaveTime staffSegments { staffId startTime endTime } } }}说明:
- 返回角色为顾客(
role0)与提袋(role101)的所有人员,不做进店过滤,与服务人数口径一致; steps为该柜台集的游逛段(进入/离开时间);staffSegments是与游逛步时间相交的店员介入时段(店员×顾客×柜台集的重叠窗口),原样返回(不裁剪、不合并、不过滤阈值);- 服务秒数 / 累计时长 / 阈值判定由调用方根据
endTime - startTime自行计算(阈值可参考poi.serviceThresholdSeconds); - 仅当前端请求
staffSegments字段时才查询服务明细表。
poiMetrics
Section titled “poiMetrics”按 POI(兴趣点)返回客流、逗留与贴柜指标。字段见 PoiMetric。
参数:与公共参数不同,推荐使用 ISO8601 时间参数:
| 参数 | 类型 | 说明 |
|---|---|---|
storeId |
Int! |
门店 ID |
startAt |
String |
起始时间,ISO8601 含时区偏移,如 2026-08-26T00:00:00+08:00 |
endAt |
String |
结束时间,排他边界,如查 8 月 26 日传次日零点 2026-08-27T00:00:00+08:00 |
startDate |
String |
已废弃:请使用 startAt(YYYY-MM-DD,闭区间) |
endDate |
String |
已废弃:请使用 endAt(YYYY-MM-DD,闭区间) |
poiTypes |
[PoiType!] |
可选。按 POI 类型过滤,不传返回全部类型(AISLE / ENTRANCE / COUNTER / SECTION) |
startAt/endAt 需成对提供;startAt 与 endAt 都缺省时回退到 startDate/endDate,两者都未提供则报错。
query { poiMetrics( storeId: 1 startAt: "2026-08-26T00:00:00+08:00" endAt: "2026-08-27T00:00:00+08:00" poiTypes: [COUNTER, ENTRANCE] ) { poi { id poiType name dwellThresholdSeconds serviceThresholdSeconds detectionRange } dwellPeople totalDwellSeconds servedPeople serviceDurationSeconds lingerPeople totalLingerSeconds avgLingerSeconds passByVisits enteringVisits enteringPeople }}peoplePaths
Section titled “peoplePaths”按人返回店内游逛链路(柜台集停留 + 出入口过口事件,按时间合并排序)。字段见 PeoplePath。
| 参数 | 类型 | 说明 |
|---|---|---|
storeId |
Int! |
门店 ID |
startDate |
String! |
起始日期,YYYY-MM-DD |
endDate |
String! |
结束日期,YYYY-MM-DD |
roles |
[PeopleRole!] |
可选。CUSTOMER / STAFF / OTHER;不传返回全部(不做进店过滤) |
query { peoplePaths(storeId: 1, startDate: "2026-07-01", endDate: "2026-07-31", roles: [CUSTOMER]) { peopleId role steps { poi { id poiType name } dwellSeconds enterTime leaveTime } }}flowEvents
Section titled “flowEvents”镜头区域进出事件明细(进店顾客 + 店内员工)。字段见 FlowEvent。
| 参数 | 类型 | 说明 |
|---|---|---|
storeId |
Int! |
门店 ID |
startDate |
String! |
起始日期,YYYY-MM-DD |
endDate |
String! |
结束日期,YYYY-MM-DD |
roles |
[PeopleRole!] |
可选。CUSTOMER / STAFF / OTHER;不传返回全部(顾客限定从入口通道进入) |
query { flowEvents(storeId: 1, startDate: "2026-08-01", endDate: "2026-08-20", roles: [STAFF]) { peopleId eventType eventTime deviceSn zoneId role }}