首页
>
资源
>

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

2026-07-31

无需编写脚本，在浏览器中即可查看 TsFile 元数据与明细数据、绘制趋势图，并完成文件健康扫描。TsFile Viewer，让 TsFile 数据查看与问题定位更简单。

首图20260731-zxcf.PNG

拿到一个 Apache TsFile 文件，如何快速确认它是否健康？

文件中包含哪些设备和测点？采用了什么数据类型、编码方式和压缩方式？某一时间范围内的数据是否符合预期？

过去，回答这些问题往往需要准备命令行工具或编写脚本。现在，通过 TsFile Viewer，在浏览器中即可完成从文件查看、元数据解析、数据预览到健康扫描的一站式操作。

0120260731.PNG

01 什么是 TsFile Viewer？

TsFile 是 Apache IoTDB 生态中的重要底层文件格式，面向时序数据的高效写入、存储和传输。

TsFile Viewer 是一款面向 TsFile 的可视化查看与分析工具。用户可以选择已有文件，也可以拖拽或点击上传 .tsfile 文件，直观查看文件结构和数据内容，并对文件健康状态进行扫描。

从“拿到文件”到“读懂文件”，操作路径被简化为：选择文件—查看结构—筛选数据—分析或导出。

此外，TsFile Viewer 提供中英文双语界面。用户可通过左下角的语言切换器一键切换，页面文案以及日期、分页等通用组件会同步完成本地化适配；语言偏好也会保存在浏览器中，下次访问自动沿用。无论是本地开发、跨团队协作还是国际化项目，都能获得一致、顺畅的使用体验。

0220260731.PNG

02 树表双模型，文件结构一目了然

TsFile Viewer 支持树模型和表模型文件，并根据文件模型展示对应的元数据信息。

对于树模型文件，可以查看：

  • 文件版本与时间范围

  • 设备数量、测点数量和 Chunk 数量

  • 设备及测点明细

  • 各设备的数据时间范围

0320260731.png

对于表模型文件，可以查看：

  • 文件版本与时间范围

  • 表、设备及测点数量

  • Tag 列和 Field 列

  • 字段的数据类型、编码方式与压缩方式

无需逐层解析文件，即可快速掌握数据组织方式，为开发调试、数据验收和问题排查提供清晰依据。

0420260731.png

03 多维筛选，快速找到目标数据

面对包含大量设备、测点或字段的 TsFile，TsFile Viewer 提供了灵活的数据预览能力。

用户可以按照表、设备、测点或字段进行选择，也可以使用“最近 1 小时”“最近 6 小时”“最近 24 小时”“最近 7 天”“最近 30 天”等快捷时间范围，或自定义开始与结束时间。

结合高级筛选、字段列搜索、分页浏览等功能，即使面对字段较多的文件，也能更快聚焦目标数据。

筛选结果还可导出为 CSV 或 JSON，便于进一步分析、共享或留档。

0520260731.png

04 趋势可视化，让时序变化更直观

比起逐行查看数据，趋势图往往更容易发现波动、突变和异常。

TsFile Viewer 可将选定设备、测点或字段的数据绘制为多序列趋势图，并支持按时间范围筛选和缩放查看。不同序列的变化趋势集中呈现，帮助用户快速建立对数据分布和变化规律的直观认识。

面对大数据量曲线，TsFile Viewer 会在数据点超过 1000 个时自动启用 LTTB（Largest Triangle Three Buckets）降采样。它在减少绘制点数、提升缩放和平移流畅度的同时，尽可能保留峰值、拐点与整体变化趋势，即使长时间范围内的数据十分密集，也能快速看清关键波动。

无论是检查采集结果、对比多个测点，还是定位某一时间段的数据变化，都能更加高效。

0620260731.png

05 单文件或目录扫描，快速判断文件健康状态

除了“看数据”，TsFile Viewer 还提供文件扫描能力，支持 单文件扫描 和 目录扫描 两种模式。

扫描过程中，可以实时查看任务进度与扫描日志；扫描完成后，报告会集中展示文件路径、文件大小、健康状态、错误摘要和扫描耗时等信息。

扫描结果分为 HEALTHY（健康）、WARNING（警告）和 ERROR（错误）三个等级：未发现异常即为健康；仅出现非致命读取异常时给出警告；一旦发现结构性或关键错误，则标记为错误。不同等级配合错误摘要，让文件是否可用、是否需要进一步排查一目了然。

健康检查采用与 IoTDB 一致的 marker-based 顺序遍历，从文件结构一路深入到页面级数据，按“文件完整性—Chunk 偏移一致性—页内时间戳顺序—页间时间范围—页头与实际数据一致性”逐层校验，可识别文件截断或格式不兼容、结构损坏、数据读取异常、时间戳重复或乱序、页面时间重叠以及页头时间不一致等问题。

当需要批量检查 TsFile，或快速判断某个文件能否被正常解析时，扫描报告可以提供直接、清晰的参考。

0720260731.png

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。

温馨提示：请仅上传已获授权处理的数据，并遵守所在组织的数据安全与保密要求。