企业官网建设流程全解析

TDengine 零代码数据接入：通过 taosExplorer 将 CSV 文件导入 TDengine 集群实战指南

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

CSV（逗号分隔值）是最常见的数据交换格式之一，广泛存在于各类业务系统、工控设备与历史数据导出中。TDengine 内置的零代码数据接入平台（taosExplorer）提供了开箱即用的 CSV 数据源，用户无需编写一行代码，即可在浏览器中通过表单配置把本地 CSV 文件或服务器目录中的 CSV 文件持续导入 TDengine 集群。本文基于官方文档 CSV File，系统讲解任务创建、CSV 解析选项、文件监听、字段提取/拆分/过滤/映射以及异常处理策略等完整流程，帮助读者快速搭建从 CSV 到 TDengine 的稳定数据管道。

说明：CSV 数据源属于零代码接入的 taosX 数据同步能力之一，该能力适用于 TDengine 企业版（Enterprise）环境，社区版用户请以实际发布版本为准。

功能概述

通过 taosExplorer 的数据写入（Data Writing）界面，可以将一个或多个 CSV 文件的数据导入 TDengine。整个过程完全可视化、零编码：TDengine 会自动完成 CSV 的解析、字段提取与拆分、数据过滤、字段映射与类型转换，最终将数据写入目标超级表（Supertable）的子表中，从而省去部署独立 ETL 工具的环节，简化整体架构。

在零代码接入体系中，CSV 与 MQTT、Kafka、MySQL、Oracle、PostgreSQL 等数据源并列（完整清单见 数据连接器总览）。与流式数据源不同的是，CSV 属于文件型数据源，其数据接入天然具备“任务驱动 + 文件级断点续传”的特性：任务会根据配置从文件读取并处理数据，并在处理过程中持久化“文件名 + 已消费行数”，任务中断后可据此从下一行继续（详见后文“断点续传”一节）。

创建任务

创建 CSV 接入任务共分为五步：新增数据源 → 配置基本信息 → 配置 CSV 选项 → 配置解析与映射 → 提交任务。下面按顺序展开。

新增数据源

登录 taosExplorer 后，进入左侧导航栏的数据写入（Data Writing）任务列表页面，点击+Add Data Source（新增数据源）按钮，进入新建任务页面。

配置基本信息

在新任务页面中完成以下三项基础配置：

1. Name（名称）：输入任务名称，例如test_csv，用于在任务列表中标识该任务。
2. Type（类型）：从下拉列表中选择CSV。
3. Target Database（目标数据库）：从下拉列表中选择一个目标数据库；如果尚未创建数据库，也可以点击右侧的+Create Database按钮现场创建。

配置 CSV 选项

CSV 选项用于定义 CSV 文件的解析规则，决定文件内容如何被切分为字段和行，共包含五项配置：

其中“忽略前 N 行”与“包含表头”常组合使用：例如文件前几行为说明文字、随后紧跟表头时，可先忽略前 N 行再开启表头识别；而“字段引用符”是正确处理包含逗号、换行等特殊字符的字段内容（如"Beijing, Chaoyang"）的关键配置，务必与实际导出 CSV 的格式保持一致，否则会出现字段错位。

配置解析 CSV 文件

CSV 文件的来源有两种模式：上传 CSV 文件与监听文件目录。配置好数据源后，即可进入“解析 → 提取/拆分 → 过滤 → 映射”的完整数据处理链路。

配置数据源：上传 CSV 文件

在“上传 CSV 文件”标签页中：

• 点击Select File（选取文件）按钮，选择一个或多个本地文件，通过浏览器上传到 taosX 所在服务器作为数据源；
• 在Keep Processed Files（保留已处理文件）区域开启或关闭：开启时文件处理完成后仍保留在服务器上，关闭时处理完成后文件会被删除。

配置数据源：监听文件目录

在“监听文件目录”标签页中，适合数据文件持续落盘的自动化场景：

• File Monitor Directory（文件监听目录）：输入一个 taosX 所在服务器上的绝对路径，该路径下的文件及子目录文件将作为数据源；
• Match Pattern（匹配模式）：输入一个正则表达式，用于筛选过滤目录中的文件（例如.*\.csv$仅匹配 CSV 文件）；
• Watch New Files（监听新文件）：开启后任务永不停止，持续处理目录中新增的文件；关闭后不处理新增文件，初始文件处理结束后任务进入完成状态；
• Monitor Interval（监听间隔）：输入数字，配置监听新文件的时间间隔；
• File Processing Order（文件处理顺序）：选择“正序”或“倒序”。正序按文件名字典序从前到后处理，倒序从后到前；程序始终遵循先处理文件、后处理同级子目录的顺序。

解析

上传文件或配置监听目录后，点击Parse（解析）按钮，页面会读取文件中的示例数据，并展示识别出的列与示例数据的解析结果，便于确认 CSV 选项配置是否正确。

从列中提取或拆分（Extract or Split from Column）

解析得到的字段可能仍不满足目标表的要求。例如原始message字段值为abc-def，希望按-拆分为message_0与message_1两个字段，可在Extract or Split from Column（从列中提取或拆分）中配置一条拆分规则：

• 选择split（拆分）提取器；
• separator（分隔符）填写-；
• number（数量）填写2，表示拆分为 2 个字段。

拆分后字段的命名规则为{原字段名}_{序号}，即message_0、message_1。规则支持多条：点击Add（新增）添加更多提取规则，点击Delete（删除）移除当前规则，点击放大镜图标可预览提取或拆分结果。

关于提取/拆分的通用原理，在 数据连接器总览 中有更完整的说明：除 split 规则外，还可以使用**正则表达式（Regex）**规则，通过命名捕获组(?<field_name>...)从字段中提取多个字段；split 规则与 regex 规则提取出的字段类型均为字符串。

过滤（Filter）

过滤用于设定写入条件，只有满足条件的数据行才会被写入 TDengine。在Filter（过滤）中填写过滤表达式，例如填写id != 1，则只有id不等于 1 的数据才会被处理。支持多条过滤规则：点击Delete删除当前规则，点击Add（新增）添加更多规则，点击放大镜图标预览过滤结果。

说明：过滤表达式的求值结果必须是布尔类型，可用的比较运算符包括>、>=、<=、<、==、!=，多个条件可用逻辑运算符&&、||、!组合。以字符串类型字段为例，还支持is_empty()、contains()、starts_with()、ends_with()等函数，例如location.starts_with("beijing") && voltage > 200。若解析字段类型与预期不符，可使用类型转换函数parse_int(...)（字符串转整型）与parse_float(...)（字符串转浮点型）。

表映射（Table Mapping）

映射用于建立“源字段 → 目标超级表字段”的对应关系：

1. Target Supertable（目标超级表）：从下拉列表中选择目标超级表，也可以点击右侧的Create Supertable（创建超级表）按钮现场创建。由于普通表并非典型应用场景，CSV 数据源当前不支持导入到普通表，仅支持写入超级表的子表。
2. Mapping（映射）：填写目标超级表的子表名称，例如t_${groupid}（其中${groupid}为源字段占位符，运行时会替换为对应字段值）；同时配置各源字段到超级表列（含标签列）的映射关系。
3. 点击Preview（预览）查看映射结果，确认子表名称与列数据正确后进入下一步。

零代码平台支持的通用映射规则（详见 数据连接器总览）包括：mapping（直接映射）、value（常量）、generator（生成器，目前支持 now 时间戳生成器）、join（字符串拼接）、format（字符串格式化，${}占位符）、sum（多字段求和）与expr（数值运算表达式，支持+ - * /及sin/cos/sqrt/exp/ln/floor/round等数学函数）。子表名称本身也可用format表达式动态生成，${groupid}即属此类用法。

配置高级选项

Advanced Options（高级选项）区域默认折叠，点击>展开。不同数据源的字段略有差异，CSV 数据源常见选项如下：

• Maximum Read Concurrency（最大读取并发）：限制源端连接数或读取线程数，默认0表示由连接器自动配置。当源端响应较慢且适合增加并发时，可适当调大。
• Batch Size（批量大小）：单次发送的最大消息数或行数，默认值依数据源而定，常见取值为1000或10000。
• Write Concurrency（写入并发）：部分数据源提供，指定可并发写入 TDengine 的任务数。

此外，自 v3.3.5.0 起，任务列表会展示每个运行任务的健康状态，可在高级选项中配置健康监控参数：Health Check Duration（健康检查时长，计算任务状态的最近时间段）、Busy State Threshold（繁忙状态阈值，队列中待写入项占写队列容量的比例，默认100%）、Max Write Queue Length（最大写队列长度）、Write Error Threshold（健康检查周期内允许的写错误数，超出即上报错误）。健康状态取值包括 Ready、Idle、Active、Pending、Busy、Bounce、SourceError、SinkError、Fatal 等，具体含义可参考 健康状态。

配置异常处理策略

Exception Handling Strategy（异常处理策略）区域默认折叠，点击>展开。当写入过程中出现异常数据时，可按条件配置处理方式，共四种通用策略：

• Archive（归档）：将无效数据写入归档文件，默认存放于${data_dir}/tasks/<id>/<datetime>目录下，不写入目标数据库；
• Discard（丢弃）：忽略无效数据；
• Error（报错）：上报错误；
• Cache（缓存）：当目标连接失败或资源不足时，将数据写入缓存文件，待目标恢复后继续写入。

可针对以下条件分别配置处理策略：

配套的附加设置包括：

• Connection Timeout（连接超时）：目标连接超时秒数，取值范围1~600；
• Temporary Storage Location（临时存储位置）：相对${data_dir}/tasks/<id>/的路径；
• Archive Retention Days（归档保留天数）：非负整数，0表示不限制；
• Archive Available Space（归档可用空间）：取值范围0~65535，0表示不限制；
• Archive Location（归档位置）：相对${data_dir}/tasks/<id>/的路径；
• Archive Write Failure Strategy（归档写入失败策略）：删除旧文件 / 丢弃数据 / 报错并停止任务。

创建完成

确认所有配置无误后，点击Submit（提交）按钮，即可完成 CSV 到 TDengine 数据同步任务的创建，页面自动返回数据写入任务列表。若提交成功，任务状态会切换为Running（运行中）；若提交失败，可通过任务的活动日志查看错误原因。

查看运行指标

在任务列表中点击View（查看）按钮，可查看任务的运行指标。指标弹窗通常分为多个标签页，展示任务多次运行的累计指标与本次运行的指标；同时可以查看任务中所有文件的处理情况，包括每个文件的处理进度与结果，便于定位数据处理瓶颈或异常文件。

任务管理

在数据写入任务列表页，可以对已创建的任务执行启动 / 停止操作，以及查看 / 编辑 / 删除 / 复制操作。运行中的任务会实时展示写入记录数、流量等运行状态信息；通过健康状态列可以快速判断任务当前处于 Ready、Active、Busy 或异常等何种状态，从而及时进行参数或资源调优。

断点续传：CSV 任务的进度恢复机制

taosX 的大部分数据源都支持从上次持久化的检查点（checkpoint）恢复任务（详见 数据连接器总览）。对于CSV 数据源，任务在处理过程中会持久化当前文件名与已消费的行数；当任务中断（如进程重启、网络抖动或手动停止）后再次启动时，会自动定位到上次处理到的文件与下一行，从断点继续导入，而无需重新读取整个文件。这一机制配合“监听文件目录”模式，可保障文件持续落盘场景下的数据导入不重复、不遗漏。

总结

从 CSV 到 TDengine 的数据接入无需任何编码：只需在 taosExplorer 的数据写入页面依次完成“新增数据源 → 配置基本信息 → 配置 CSV 选项（表头 / 忽略前 N 行 / 分隔符 / 引用符 / 注释前缀）→ 配置数据源（上传文件或监听目录）→ 解析 / 提取拆分 / 过滤 / 映射 → 提交任务”即可。通过高级选项可调优读写并发与健康监控阈值，通过异常处理策略可针对各类写入异常实现归档、丢弃、报错或缓存恢复，配合文件级断点续传机制，足以构建稳健可靠的 CSV 批式/准实时数据管道。更多底层机制与通用数据处理规则（正则提取、类型转换、映射规则、健康状态定义等）可继续参阅 零代码数据接入总览。

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine