Skip to content

查询参考(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 时间与类型过滤),见下文。

按日返回客流核心指标。字段见 DailyMetric。

query {
dailyMetrics(storeId: 1, startDate: "2026-07-01", endDate: "2026-07-31") {
date
passByVisits
enteringPeople
enteringVisits
receptionPeople
dwellPeople
servedPeople
serviceDurationSeconds
counterLingerPeople
counterLingerDurationSeconds
counterLingerAvgSeconds
}
}

按小时返回客流核心指标。字段与 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
}
}

按人返回顾客档案:每个顾客的游逛步骤(柜台集进入/离开时间)与店员介入时段(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
}
}
}
}

说明:

  • 返回角色为顾客(role 0)与提袋(role 101)的所有人员,不做进店过滤,与服务人数口径一致;
  • steps 为该柜台集的游逛段(进入/离开时间);staffSegments 是与游逛步时间相交的店员介入时段(店员×顾客×柜台集的重叠窗口),原样返回(不裁剪、不合并、不过滤阈值);
  • 服务秒数 / 累计时长 / 阈值判定由调用方根据 endTime - startTime 自行计算(阈值可参考 poi.serviceThresholdSeconds);
  • 仅当前端请求 staffSegments 字段时才查询服务明细表。

按 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
}
}

按人返回店内游逛链路(柜台集停留 + 出入口过口事件,按时间合并排序)。字段见 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
}
}
}

镜头区域进出事件明细(进店顾客 + 店内员工)。字段见 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
}
}