FreeSql 中使用 ExecuteQuestDbBulkCopy 插入 QuestDB 数据的注意事项

背景介绍

FreeSql 是一个功能强大的 .NET ORM 框架，支持多种数据库操作。其中对于时序数据库 QuestDB 提供了专门的批量插入方法 ExecuteQuestDbBulkCopy，但在实际使用中可能会遇到一些特殊问题。

问题现象

在使用 FreeSql 向 QuestDB 批量插入数据时，开发者发现：

1. 使用 fsql.Insert<Books2>().AppendData(list).ExecuteAffrowsAsync() 方式插入数据成功
2. 但使用 fsql.Insert(list).ExecuteQuestDbBulkCopy() 方式时，虽然不报错，但数据实际上没有插入到数据库中

问题分析

经过深入分析，发现这与 QuestDB 的特殊表结构设计有关。特别是当使用了 [AutoSubtable] 特性进行自动分表时，批量插入操作需要特别注意以下几点：

1. 主键要求：QuestDB 在分表场景下的批量插入操作需要明确指定主键字段
2. 字段映射：批量插入时字段映射规则可能与常规插入有所不同
3. 数据类型：时序数据的时间字段需要特别注意格式和类型

解决方案

要使 ExecuteQuestDbBulkCopy 正常工作，需要对实体类进行适当修改：

public class Books2
{
    [Column(IsPrimary = true)]
    public string Id { get; set; }
    
    public string Name { get; set; }
    public string Sex { get; set; }

    [AutoSubtable(SubtableType.Day)]
    public DateTime? tim1 { get; set; }
}

关键修改点：

1. 添加了 Id 属性作为主键
2. 使用 [Column(IsPrimary = true)] 明确标记主键

最佳实践建议

1. 明确主键：在使用 QuestDB 批量插入时，确保实体类包含明确的主键字段
2. 分批处理：大数据量时仍建议分批处理，避免单次操作数据量过大
3. 字段验证：确保所有字段类型与数据库表结构匹配
4. 性能监控：批量插入后检查实际插入行数，确保操作成功

总结

FreeSql 的 ExecuteQuestDbBulkCopy 方法为 QuestDB 提供了高效的批量数据插入能力，但在使用时需要注意 QuestDB 的特殊要求，特别是分表场景下的主键设置。通过合理设计实体类结构，可以充分发挥批量插入的性能优势。