TDengine超级表实战：用C#处理百万级传感器数据（附SqlSugar代码）

最近在做一个智慧工厂的项目，遇到了一个挺有意思的挑战。厂区里部署了上千个传感器，温度、湿度、压力、振动数据，每秒钟都在产生海量记录。最初用传统关系型数据库硬扛，没几天就发现写入速度跟不上了，查询更是慢得让人抓狂。更头疼的是，每个设备的数据结构虽然相似，但又有些微差异，比如有的传感器多一个“校准系数”字段。如果给每个设备建一张完全独立的表，管理起来简直是噩梦；如果全塞进一张大表，查询效率低下不说，后期扩展也麻烦。

就在这个时候，我接触到了TDengine。说实话，一开始听到“时序数据库”这个概念，感觉有点距离感。但真正用起来，特别是它的“超级表”设计，让我有种豁然开朗的感觉。它完美地解决了我的痛点：既能用统一的结构模板管理所有设备，又能让每个设备的数据独立存储、高效查询。更重要的是，作为一个C#开发者，我发现通过SqlSugar这个ORM框架来操作TDengine，体验非常顺滑，几乎和操作MySQL没什么两样，学习成本极低。

这篇文章，我就把自己从零搭建环境，到设计超级表结构，再到用C#实现高并发数据写入和复杂聚合查询的完整实战经验分享出来。我会重点讲解在真实的高并发场景下，如何利用TDengine的特性进行性能优化，避开那些我踩过的“坑”。无论你是正在评估时序数据库方案，还是已经决定使用TDengine，希望这些代码和思路都能给你带来实实在在的帮助。

1. 环境搭建与核心概念解析

在开始写代码之前，扎实的基础环境和对核心概念的理解至关重要。TDengine的安装并不复杂，但其设计哲学与传统数据库有显著不同，理解这些差异是高效使用它的前提。

1.1 TDengine服务端部署与关键配置

TDengine支持Windows、Linux等多种平台。对于开发和测试，Windows环境足够；生产环境则强烈推荐Linux。这里以Windows开发环境为例，但配置思路是相通的。

首先，从TDengine官网下载同时包含Server和Client的安装包。安装过程基本是“下一步”到底，但安装后的配置才是关键。配置文件taos.cfg位于安装目录的cfg文件夹下，我们需要关注几个核心参数：

# 首要端点。对于单机版，这里填写本机IP或localhost及端口6030。
firstEp        localhost:6030

# 本地节点的FQDN或IP地址。单机部署时，通常与firstEp的host部分一致。
fqdn           localhost

# 数据文件存储目录。务必指向一个空间充足、IO性能好的磁盘路径。
dataDir        E:/TDengine/data

# 日志文件存储目录。
logDir         E:/TDengine/log

# 单个数据库数据保留的天数。根据业务需求设置，例如只保留30天热数据。
keep           30

# 副本数。单机部署设为1，集群部署可设为2或3以提高数据可靠性。
replica        1

# 时区设置，确保时间戳处理正确。
timezone       Asia/Shanghai

注意：修改taos.cfg后，必须重启taosd服务才能生效。另外，确保防火墙开放了6030（TCP/UDP）、6035（HTTP RESTful接口）等端口。

安装并配置完成后，通过系统服务或直接运行taosd.exe启动服务。然后，使用taos命令行工具连接，执行show dnodes;，如果能看到一个ready状态的节点，说明服务端启动成功。

1.2 理解超级表：物联网数据建模的利器

这是TDengine最精髓的部分。你可以把超级表想象成一个定义了所有设备共同数据特征的“模板”或“类”。而子表则是根据这个模板创建出来的一个个具体设备的“实例”。

举个例子，假设我们监控三种设备：空调、水泵和电机。它们都采集时间戳(ts)、指标名称(key)和指标值(value)。但空调可能有一个运行模式(mode)的标签，水泵有额定功率(power)标签，电机有制造商(manufacturer)标签。

在传统数据库中，你可能需要设计三张不同的表，或者在一张大表中增加许多可为空的字段。在TDengine中，你可以这样设计：

1. 创建一个超级表：定义所有设备都有的采集字段（时间戳和指标）。
2. 定义标签：将设备特有的、不常变的属性（如设备ID、型号、位置、制造商）作为标签。标签用于对设备进行分类、过滤和分组，其值一旦设定通常不随时间变化。
3. 自动创建子表：当插入数据时，通过指定标签值，TDengine会自动或手动创建对应的子表。每个设备对应一张子表。

这种设计带来了巨大优势：

• 高效查询：既可以查询单个设备（子表）的明细数据，速度极快；也可以基于超级表，对所有或部分设备（通过标签过滤）进行聚合分析。
• 易于管理：增加一个新设备类型，只需用新的标签组合插入数据即可，无需修改表结构。
• 存储优化：TDengine在底层会对不同子表的相同时间序列进行压缩存储，大幅节省空间。

下面的表格清晰地对比了传统方案与TDengine超级表方案的区别：

特性	传统方案（单张大表）	TDengine超级表方案
表结构	所有设备字段堆砌，大量NULL值	采集字段统一，设备属性作为标签
写入性能	单点写入，随数据量增长而下降	多子表并行写入，性能线性扩展
查询性能	全表扫描，条件过滤慢	可精准定位子表，或基于标签高效聚合
扩展性	新增设备类型需改表结构	新增设备即新增标签组合，无需改结构
存储效率	较低，存在冗余	高，时序数据压缩比高，标签独立存储

理解了这些，我们在用C#操作时，思路就会非常清晰：我们的代码核心就是与超级表模板和由其衍生的无数子表打交道。

2. C#开发环境配置与SqlSugar集成

对于.NET开发者而言，选择一个顺手的ORM或连接器能极大提升开发效率。TDengine提供了官方的ADO.NET连接器，但这里我强烈推荐结合SqlSugar来使用。SqlSugar是一个国产的高性能、轻量级ORM，它对TDengine的支持做得相当不错，能让我们的代码保持与操作MySQL相似的风格，简洁直观。

2.1 项目配置与依赖安装

首先，创建一个新的.NET Console或ASP.NET Core项目。然后，通过NuGet包管理器安装必要的依赖：

# 安装TDengine的官方ADO.NET驱动，这是底层通信的基础
Install-Package TDengine.Connector

# 安装SqlSugar Core，我们的主要ORM工具
Install-Package SqlSugarCore

# 可选：安装Newtonsoft.Json或System.Text.Json，用于处理查询结果
Install-Package Newtonsoft.Json

安装完成后，我们需要配置数据库连接字符串。建议将其放在appsettings.json中以便管理：

{
  "ConnectionStrings": {
    "TDengine": "Host=你的服务器IP;Port=6030;Username=root;Password=taosdata;Database=iot_data;PoolSize=20"
  }
}

提示：PoolSize设置连接池大小，在高并发写入场景下，适当调大此值（如50-100）有助于提升性能，但需根据服务器资源权衡。

2.2 构建SqlSugar数据库上下文

接下来，我们创建一个单例或依赖注入的数据库上下文类，封装所有数据库操作。

using SqlSugar;
using Microsoft.Extensions.Configuration;

public class TDengineContext
{
    public SqlSugarScope Db { get; private set; }

    // 通过构造函数注入配置（ASP.NET Core风格）
    public TDengineContext(IConfiguration configuration)
    {
        var connStr = configuration.GetConnectionString("TDengine");
        Db = new SqlSugarScope(new ConnectionConfig()
        {
            ConnectionString = connStr,
            DbType = DbType.TDengine, // 指定数据库类型为TDengine
            IsAutoCloseConnection = true, // 自动关闭连接
            InitKeyType = InitKeyType.Attribute // 初始化主键和自增方式（虽然TDengine没有自增主键，但保持设置）
        },
        db => {
            // 这里可以配置AOP事件，比如SQL执行前后打印日志
            db.Aop.OnLogExecuting = (sql, pars) =>
            {
                Console.WriteLine($"执行SQL：{sql}");
                // 如果需要，可以记录到文件
            };
        });
    }

    // 或者提供静态初始化方法（控制台应用等）
    public static void Init(string connectionString)
    {
        // ... 初始化逻辑
    }
}

现在，我们就可以通过TDengineContext.Db来使用SqlSugar的所有功能了。你会发现，其API与操作SQL Server、MySQL时几乎一致，这大大降低了学习成本。

3. 超级表与子表的创建与管理

有了开发环境，我们就可以开始用代码来定义数据模型了。这一步是设计阶段的核心，直接关系到后续数据操作的效率和便利性。

3.1 定义数据模型与创建超级表

假设我们的传感器数据模型如下：

• 采集字段（时序数据）：
  • ts：时间戳（TDengine的主键，每个子表必须且唯一）。
  • temperature：温度值（浮点型）。
  • humidity：湿度值（浮点型）。
  • pressure：压力值（浮点型）。
• 标签字段（设备属性）：
  • device_id：设备唯一标识（字符串）。
  • location：安装位置，如车间A-产线1（字符串）。
  • sensor_type：传感器类型，如温度传感器、三合一传感器（字符串）。
  • model_id：型号ID（整型）。

在C#中，我们可以用两个类来分别表示超级表结构和插入数据时的实体，但更常见的做法是定义一个实体类，并用SqlSugar的特性来区分普通字段和标签字段。不过，SqlSugar对TDengine标签的原生特性支持还在完善中，目前更灵活的方式是直接使用SQL。

让我们先创建超级表：

public class SensorDataService
{
    private readonly SqlSugarScope _db;

    public SensorDataService(TDengineContext context)
    {
        _db = context.Db;
    }

    public void CreateSuperTableIfNotExists()
    {
        // 创建数据库（如果不存在）
        _db.Ado.ExecuteCommand("CREATE DATABASE IF NOT EXISTS iot_sensor_data KEEP 30 DAYS 10 BLOCKS 6;");

        // 切换到目标数据库
        _db.Ado.ExecuteCommand("USE iot_sensor_data;");

        // 创建超级表
        // 注意：TDengine中，超级表名一般以'st'或'_s'开头以示区分
        string createSuperTableSql = @"
CREATE STABLE IF NOT EXISTS st_sensor_data 
(
    ts TIMESTAMP,
    temperature FLOAT,
    humidity FLOAT,
    pressure FLOAT
) 
TAGS 
(
    device_id NCHAR(64),
    location NCHAR(255),
    sensor_type NCHAR(50),
    model_id INT
)";

        _db.Ado.ExecuteCommand(createSuperTableSql);
        Console.WriteLine("超级表 st_sensor_data 创建或已存在。");
    }
}

关键点解析：

• KEEP 30 DAYS 10 BLOCKS 6：这是在数据库级别设置数据保留策略。KEEP 30表示数据保留30天，过期自动删除。DAYS 10和BLOCKS 6是存储参数，一般使用默认值即可。
• TAGS部分定义了设备的元数据。NCHAR用于存储可变长度字符串，需要指定最大长度。
• IF NOT EXISTS语句保证了操作的幂等性，多次执行不会报错。

3.2 动态创建与管理子表

在TDengine中，不需要显式地执行CREATE TABLE来创建子表。这是它的一大便利之处。子表会在你第一次向某个标签组合插入数据时自动创建。

例如，我们要插入一条来自设备SN-001的数据：

public void InsertDataAutoCreateSubtable()
{
    // 这条INSERT语句是关键
    string insertSql = @"
INSERT INTO 
    td_sensor_data_001  -- 子表名，建议包含设备ID便于识别，如 td_设备ID
USING 
    st_sensor_data  -- 指定超级表模板
TAGS 
    ('SN-001', '车间A-产线1', '温度传感器', 1001) -- 对应TAGS定义的顺序和类型
VALUES 
    (NOW, 25.3, NULL, NULL)";

    _db.Ado.ExecuteCommand(insertSql);
    Console.WriteLine("数据插入成功，子表 td_sensor_data_001 已被自动创建。");
}

执行这条语句后，TDengine会：

1. 检查子表td_sensor_data_001是否存在。
2. 如果不存在，则根据超级表st_sensor_data的结构和提供的TAGS值创建该子表。
3. 将数据插入新创建的子表中。

你可以通过SQL查询所有子表：

SHOW TABLES;

或者查询属于某个超级表的子表：

SHOW TABLEs FROM st_sensor_data;

子表命名建议：虽然TDengine不强制，但良好的命名习惯有助于管理。我通常采用{数据前缀}_{设备标识}的格式，例如td_SN001、raw_motor_01。这样在查看表列表时一目了然。

4. 高性能数据写入与查询实战

当面对成千上万个传感器，每秒钟产生数万条数据时，写入性能就是生命线。TDengine为此做了大量优化，而我们的代码也需要遵循最佳实践才能释放其全部潜力。

4.1 批量写入：应对高并发场景的利器

单条插入（INSERT ... VALUES）在数据量面前效率太低。TDengine支持两种高效的批量写入方式：单条SQL多值插入和参数化绑定写入。

方式一：单条SQL插入多条数据 这种方式适合一次性写入一个设备的多个时间点数据。

public void BatchInsertSingleDevice()
{
    // 一次性插入10条模拟数据到同一个子表
    string batchInsertSql = @"
INSERT INTO 
    td_sensor_data_001 
USING 
    st_sensor_data 
TAGS 
    ('SN-001', '车间A-产线1', '温度传感器', 1001) 
VALUES 
    (NOW - 10s, 25.1, NULL, NULL)
    (NOW - 9s,  25.2, NULL, NULL)
    (NOW - 8s,  25.5, NULL, NULL)
    (NOW - 7s,  25.3, NULL, NULL)
    (NOW - 6s,  25.0, NULL, NULL)
    (NOW - 5s,  24.9, NULL, NULL)
    (NOW - 4s,  24.8, NULL, NULL)
    (NOW - 3s,  24.9, NULL, NULL)
    (NOW - 2s,  25.0, NULL, NULL)
    (NOW - 1s,  25.1, NULL, NULL)";

    var affectedRows = _db.Ado.ExecuteCommand(batchInsertSql);
    Console.WriteLine($"批量插入成功，影响行数：{affectedRows}");
}

注意：单条SQL语句的长度受maxSQLLength配置限制（默认约64KB）。虽然这种方式简单，但在写入极大量数据或需要跨设备写入时，有SQL长度限制。

方式二：参数化绑定写入（推荐） 这是TDengine官方推荐的最高效的写入方式，尤其适合从消息队列（如Kafka）或数据采集端持续接收数据流。它通过.NET的TDengineDriver实现。

首先，我们需要定义一个与超级表结构匹配的C#类（用于绑定）：

// 对应超级表的采集字段
public class SensorDataPoint
{
    public DateTime ts { get; set; }
    public float temperature { get; set; }
    public float humidity { get; set; }
    public float pressure { get; set; }
}

// 对应超级表的标签字段
public class SensorTag
{
    public string device_id { get; set; }
    public string location { get; set; }
    public string sensor_type { get; set; }
    public int model_id { get; set; }
}

然后，实现绑定写入的逻辑：

using TDengineDriver;

public class HighPerformanceWriter
{
    private readonly string _connectionString;

    public HighPerformanceWriter(string connectionString)
    {
        _connectionString = connectionString;
    }

    public void ParameterizedBatchInsert(List<SensorDataPoint> dataPoints, SensorTag tag)
    {
        // 1. 建立连接
        using var connection = new TaosConnection(_connectionString);
        connection.Open();

        // 2. 准备SQL模板。@1, @2, @3, @4 是数据参数的占位符。
        //    ? 是标签参数的占位符。注意标签值在绑定后，后续插入同子表数据可复用。
        string sql = @"INSERT INTO ? USING st_sensor_data TAGS(?, ?, ?, ?) VALUES(?, ?, ?, ?)";

        using var command = new TaosCommand(sql, connection);

        // 3. 绑定标签参数（设备属性，不变或很少变）
        command.Parameters.Add(new TaosParameter(TaosType.NCHAR, tag.device_id)); // 子表名，通常用设备ID
        command.Parameters.Add(new TaosParameter(TaosType.NCHAR, tag.device_id)); // TAGS: device_id
        command.Parameters.Add(new TaosParameter(TaosType.NCHAR, tag.location));   // TAGS: location
        command.Parameters.Add(new TaosParameter(TaosType.NCHAR, tag.sensor_type)); // TAGS: sensor_type
        command.Parameters.Add(new TaosParameter(TaosType.INT, tag.model_id));      // TAGS: model_id

        // 4. 绑定数据参数（时序数据，每条都变）
        //    先添加参数占位符，稍后设置值
        command.Parameters.Add(new TaosParameter(TaosType.TIMESTAMP)); // @1: ts
        command.Parameters.Add(new TaosParameter(TaosType.FLOAT));     // @2: temperature
        command.Parameters.Add(new TaosParameter(TaosType.FLOAT));     // @3: humidity
        command.Parameters.Add(new TaosParameter(TaosType.FLOAT));     // @4: pressure

        // 5. 遍历数据点，设置参数值并执行（这里演示逐条，实际可优化为真正的批处理）
        //    对于海量数据，应考虑使用TaosMultiBind API进行更高效的批量绑定，此处为简化示例。
        foreach (var point in dataPoints)
        {
            command.Parameters[5].Value = point.ts; // 索引从0开始，前5个是标签占位符和标签值
            command.Parameters[6].Value = point.temperature;
            command.Parameters[7].Value = point.humidity;
            command.Parameters[8].Value = point.pressure;

            command.ExecuteNonQuery(); // 执行插入
        }

        Console.WriteLine($"参数化绑定插入完成，共{dataPoints.Count}条数据。");
    }
}

性能关键：在实际生产环境中，对于持续流入的数据，应该创建一个长期的连接和命令对象，在循环外部绑定好标签参数，在循环内部只更新数据参数的值并执行。这样可以避免重复解析SQL和建立子表连接的开销。对于极致性能场景，需要研究使用TaosMultiBind接口进行真正的批量参数绑定。

4.2 复杂查询：利用超级表进行聚合分析

超级表的威力在查询时才能真正体现。我们可以轻松地对所有设备、或按特定标签分组后的设备数据进行聚合计算。

场景一：查询单个设备的最新状态

public DataTable GetLatestDeviceData(string deviceId)
{
    string sql = @$"SELECT last(*) FROM st_sensor_data WHERE device_id='{deviceId}'";
    // 使用SqlSugar查询，返回DataTable
    return _db.Ado.GetDataTable(sql);
    // last(*) 是TDengine的内置函数，返回最后一条记录的所有字段值。
}

场景二：统计过去一小时内，每个位置的平均温度

public DataTable GetAvgTempPerLocationLastHour()
{
    string sql = @"
SELECT 
    location, 
    AVG(temperature) as avg_temp 
FROM 
    st_sensor_data 
WHERE 
    ts >= NOW - 1h 
GROUP BY 
    location";

    return _db.Ado.GetDataTable(sql);
    // 这里直接对超级表进行查询，TDengine会自动扫描所有符合WHERE条件的子表，并按location标签分组计算。
}

场景三：查询“车间A”所有温度传感器在过去5分钟内的温度最大值和发生时间

public DataTable GetMaxTempInWorkshopA()
{
    string sql = @"
SELECT 
    device_id, 
    MAX(temperature) as max_temp,
    _wstart as interval_start,
    _wend as interval_end 
FROM 
    st_sensor_data 
WHERE 
    ts >= NOW - 5m 
    AND location LIKE '车间A%' 
    AND sensor_type = '温度传感器'
INTERVAL(1m) 
GROUP BY 
    device_id";

    return _db.Ado.GetDataTable(sql);
    // INTERVAL(1m) 是TDengine强大的时间窗口聚合功能，将数据按1分钟分段，在每个分段内进行聚合。
    // _wstart和_wend是时间窗口的起止时间。
}

场景四：使用SqlSugar的查询语法（Lambda表达式）

虽然复杂查询直接写SQL更灵活，但简单的查询可以用SqlSugar的Lambda方式，更符合C#开发者的习惯。

public List<dynamic> GetDeviceList()
{
    // 查询所有设备ID及其位置（从超级表的标签中获取）
    // 注意：SqlSugar对TDengine标签查询的支持可能需要通过自定义SQL或特定方法，这里演示一种思路
    var query = _db.Queryable<object>()
                 .AS("st_sensor_data") // 指定表名
                 .Select("device_id, location, sensor_type") // 直接Select标签字段
                 .Distinct() // 去重
                 .ToList();

    return query;
}

注意：由于TDengine的超级表查询语义特殊，SqlSugar的Lambda表达式在某些复杂场景（尤其是涉及TAGS和普通字段混合查询、时间窗口函数）可能受限。我的经验是，复杂的聚合分析查询直接使用原生SQL字符串通过_db.Ado.GetDataTable或_db.Ado.SqlQuery<T>执行，这样最清晰、最可控。 简单的按标签过滤和字段选择可以考虑使用SqlSugar的语法糖。

通过以上四个部分的详细拆解，我们从环境搭建、概念理解、模型创建，到最终的高性能写入和复杂查询，完成了一个完整的TDengine超级表实战闭环。在实际项目中，你可能还需要考虑数据备份、集群部署、监控告警等更多运维层面的问题，但掌握了这些核心开发技能，你已经能够驾驭TDengine来处理海量的物联网传感器数据了。