工具介绍｜TsFile Viewer：让 TsFile 数据看得见、查得清

无需编写脚本在浏览器中即可查看 TsFile 元数据与明细数据、绘制趋势图并完成文件健康扫描。TsFile Viewer让 TsFile 数据查看与问题定位更简单。拿到一个Apache TsFile 文件如何快速确认它是否健康文件中包含哪些设备和测点采用了什么数据类型、编码方式和压缩方式某一时间范围内的数据是否符合预期过去回答这些问题往往需要准备命令行工具或编写脚本。现在通过 TsFile Viewer在浏览器中即可完成从文件查看、元数据解析、数据预览到健康扫描的一站式操作。01 什么是 TsFile ViewerTsFile 是 Apache IoTDB 生态中的重要底层文件格式面向时序数据的高效写入、存储和传输。TsFile Viewer 是一款面向 TsFile 的可视化查看与分析工具。用户可以选择已有文件也可以拖拽或点击上传.tsfile文件直观查看文件结构和数据内容并对文件健康状态进行扫描。从“拿到文件”到“读懂文件”操作路径被简化为选择文件—查看结构—筛选数据—分析或导出。此外TsFile Viewer 提供中英文双语界面。用户可通过左下角的语言切换器一键切换页面文案以及日期、分页等通用组件会同步完成本地化适配语言偏好也会保存在浏览器中下次访问自动沿用。无论是本地开发、跨团队协作还是国际化项目都能获得一致、顺畅的使用体验。02 树表双模型文件结构一目了然TsFile Viewer 支持树模型和表模型文件并根据文件模型展示对应的元数据信息。对于树模型文件可以查看文件版本与时间范围设备数量、测点数量和 Chunk 数量设备及测点明细各设备的数据时间范围对于表模型文件可以查看文件版本与时间范围表、设备及测点数量Tag 列和 Field 列字段的数据类型、编码方式与压缩方式无需逐层解析文件即可快速掌握数据组织方式为开发调试、数据验收和问题排查提供清晰依据。03 多维筛选快速找到目标数据面对包含大量设备、测点或字段的 TsFileTsFile Viewer 提供了灵活的数据预览能力。用户可以按照表、设备、测点或字段进行选择也可以使用“最近 1 小时”“最近 6 小时”“最近 24 小时”“最近 7 天”“最近 30 天”等快捷时间范围或自定义开始与结束时间。结合高级筛选、字段列搜索、分页浏览等功能即使面对字段较多的文件也能更快聚焦目标数据。筛选结果还可导出为CSV或JSON便于进一步分析、共享或留档。04 趋势可视化让时序变化更直观比起逐行查看数据趋势图往往更容易发现波动、突变和异常。TsFile Viewer 可将选定设备、测点或字段的数据绘制为多序列趋势图并支持按时间范围筛选和缩放查看。不同序列的变化趋势集中呈现帮助用户快速建立对数据分布和变化规律的直观认识。面对大数据量曲线TsFile Viewer 会在数据点超过 1000 个时自动启用 LTTBLargest Triangle Three Buckets降采样。它在减少绘制点数、提升缩放和平移流畅度的同时尽可能保留峰值、拐点与整体变化趋势即使长时间范围内的数据十分密集也能快速看清关键波动。无论是检查采集结果、对比多个测点还是定位某一时间段的数据变化都能更加高效。05 单文件或目录扫描快速判断文件健康状态除了“看数据”TsFile Viewer 还提供文件扫描能力支持单文件扫描和目录扫描两种模式。扫描过程中可以实时查看任务进度与扫描日志扫描完成后报告会集中展示文件路径、文件大小、健康状态、错误摘要和扫描耗时等信息。扫描结果分为 HEALTHY健康、WARNING警告和 ERROR错误三个等级未发现异常即为健康仅出现非致命读取异常时给出警告一旦发现结构性或关键错误则标记为错误。不同等级配合错误摘要让文件是否可用、是否需要进一步排查一目了然。健康检查采用与 IoTDB 一致的 marker-based 顺序遍历从文件结构一路深入到页面级数据按“文件完整性—Chunk 偏移一致性—页内时间戳顺序—页间时间范围—页头与实际数据一致性”逐层校验可识别文件截断或格式不兼容、结构损坏、数据读取异常、时间戳重复或乱序、页面时间重叠以及页头时间不一致等问题。当需要批量检查 TsFile或快速判断某个文件能否被正常解析时扫描报告可以提供直接、清晰的参考。06 这些场景都可以用 TsFile Viewer研发调试快速核对程序生成的 TsFile确认设备、测点、字段及数据内容是否符合预期。测试与质量检查查看元数据和数据明细扫描文件健康状态辅助定位文件结构或数据问题。运维排查通过时间筛选、趋势图和扫描报告缩小问题范围减少重复编写临时脚本的工作。数据交付与交流以可视化方式展示文件内容并将目标数据导出为 CSV 或 JSON便于进一步处理。07 三步快速上手第一步获取并启动 TsFile Viewer。进入 Apache TsFile Viewer GitHub 项目按照中文 README 完成环境准备与应用启动。开发模式下分别启动后端和前端后访问http://localhost:5173/view/采用生产构建方式启动 JAR 包后访问http://localhost:8080/view/即可进入 TsFile Viewer。第二步选择已有 TsFile或拖拽、点击上传需要查看的.tsfile文件。第三步根据需要进入元数据、数据预览、图表可视化或文件扫描页面开始查看与分析。从文件结构到数据内容从趋势展示到健康扫描TsFile Viewer 让 TsFile 的查看、分析与排查更加直观。现在就打开 TsFile Viewer快速读懂你的 TsFile。温馨提示请仅上传已获授权处理的数据并遵守所在组织的数据安全与保密要求。