时间戳(timestamp)
基本说明
时间戳表示事件发生的主时间,是事件表的必需字段,也是问答的默认时间维度。例如订单表可以选择下单时间,支付表可以选择支付时间。
实体快照也使用时间戳表达观测时间,例如每天记录一次的库存。普通实体的其他时间属性可以使用日期时间。
数据要求
映射后的时间格式
映射后应能得到可供筛选和统计的日期时间值,常用格式为 YYYY-MM-DD HH:mm:ss。
原始数据可以是日期时间、整数时间戳或其他格式的字符串,通过数据映射转换即可,无需修改原始存储格式。具体配置方式见字段高级设置。
配置与问答
事件表中只配置一个主时间戳,其余时间字段按业务含义选择日期时间等类型。提问「今年的销售额」时,系统会使用主时间戳;提问「今年发货的订单」时,则需要模型中有对应的发货时间字段。
可通过 granularity 设置时间粒度,并确保粒度与源数据一致。例如只有月度汇总的数据,不能因为补齐了日期格式就解释为真实的每日明细。
快照模型需要在 Schema 上配置 temporalSemantics: 'snapshot',并且恰好有一个时间戳。配置示例见 Snapshot 时间语义。
使用示例
默认时间筛选
订单表包含「下单时间」和「发货时间」,把下单时间设为时间戳,发货时间设为日期时间。「2025 年 6 月的订单」默认按下单时间筛选;「2025 年 6 月发货的订单」按发货时间筛选。
非标准格式的转换
系统在做时间聚合(如按日、按月、按年汇总)时,需要识别字段中的时间。原始数据不是标准日期时间时,可以通过映射中的 SQL 表达式转换,数据库中的原始值保持不变。
常见的非标准情况包括:
- 用字符串
202010表示「2020 年 10 月」(年月连写、无分隔符、无日) - 将「年」「月」分别存成两个字段,例如
year = 2020、month = 10 - 用整数存储 Unix 时间戳(秒/毫秒)等
转换时,需要使用所接入数据源自身的 SQL 语法。配置入口为:字段配置 → 高级 → 字段映射,在框中填入对应表达式(示例中的字段名请替换为实际字段名)。转换的目标是 YYYY-MM-DD HH:mm:ss 的日期时间类型,因此应使用返回日期时间的函数(如 toDateTime、to_timestamp),而非只返回日期的函数(如 toDate、to_date)。
案例一:字符串 202010 表示年月
假设字段 pay_month 存的是 202010 这样的字符串,表示 2020 年 10 月,需转成时间戳格式。
案例二:年、月分成两个字段
假设 year_col 字段存年份(如 2020),month_col 字段存月份(如 10)。
转换结果应尽量补足到 YYYY-MM-DD HH:mm:ss,缺失的日、时、分、秒统一补为 01 或 00(如 202010 → 2020-10-01 00:00:00),用于按月、按年聚合已足够;如需精确到某一天,请在转换时补足对应精度。
常见问题
字段名叫 timestamp,数据就应该存 Unix 整数吗?
这里的时间戳是业务语义类型。数据源如果使用 Unix 秒数或毫秒数,仍需通过 SQL 转换为日期时间,并确认秒/毫秒单位与时区。
为什么问「今年销售额」筛选的时间不符合预期?
检查主时间戳选的是下单时间、支付时间还是其他时间。模型中的默认时间口径应与业务一致;需要其他口径时,应在问题中明确相应动作或字段。

