Cosmos DB中ts字段在C#中的使用困惑及字段选择咨询

先搞懂 _ts 是什么 #

_ts 是Cosmos DB自动维护的系统字段，存储的是Unix时间戳（秒级精度，UTC时区），文档创建或更新时会自动刷新，属于只读字段，无法手动修改。它默认被索引，查询性能优异。

要不要用自定义字段替代 _ts？ #

没必要直接替代，而是根据场景选择：如果_ts的特性满足需求，就用它；如果不满足，再新增自定义日期字段（甚至可以同时保留两者）。

什么时候优先用 _ts #

• 仅需记录文档最后修改/创建时间：不需要业务特定时间逻辑，依赖系统自动维护即可，不用自己写代码更新时间
• 追求开发效率：不用手动处理时间字段的赋值、更新逻辑，系统自动搞定
• 秒级精度足够：如果业务对时间精度没有毫秒级以上要求，_ts的秒级完全够用
• 基于修改时间做查询/排序：_ts默认被索引，过滤、排序性能比自定义未索引字段好很多

什么时候需要自定义日期时间字段 #

• 需要业务专属时间：比如订单创建时间、用户注册时间、支付完成时间，这些时间和文档修改时间无关，必须单独存储
• 更高精度需求：_ts只有秒级精度，如果需要毫秒/微秒级时间戳，必须自定义字段
• 需要手动控制时间值：比如批量导入历史数据时要指定过去的时间，或者回溯修改数据时不想更新时间，_ts是系统自动更新的，做不到这点
• 避免类型转换麻烦：如果你的C#实体类想直接用DateTime/DateTimeOffset类型，不想每次都把long类型的_ts转成日期，自定义字段可以直接映射为对应类型，序列化时自动处理
• 时区相关需求：_ts是UTC时间，如果需要存储用户本地时区的时间，自定义字段可以直接存储带时区信息的时间值

C# 中处理 _ts 的实用技巧 #

如果只是觉得_ts的类型转换麻烦，可以在实体类里封装转换逻辑，避免重复代码：

public class ProductDocument
{
    public string Id { get; set; }
    public string Name { get; set; }
    
    // 映射Cosmos DB的_ts字段
    [JsonPropertyName("_ts")]
    public long SystemTimestamp { get; set; }

    // 只读属性，自动转换为UTC DateTime
    public DateTime LastModifiedUtc => DateTimeOffset.FromUnixTimeSeconds(SystemTimestamp).UtcDateTime;
}

这样查询文档后，直接通过LastModifiedUtc就能拿到标准的DateTime类型，不用每次手动转换。

内容的提问来源于stack exchange，提问作者user911