tsfile-converter-tool 0.1.0

Backend Python API and CLI for converting CSV, Parquet, and Arrow data to TsFile.

TsFile Dataset

本项目是一个基于 TsFile 的时序数据集管理与可视化演示，包含：

• 基于 Flask 的 Web 界面（管理、可视化、文件操作）。
• 简单的客户端示例与脚本（在 examples/ 下）。

功能模块（按项目菜单结构）

1. 首页

• 系统概览：展示系统的主要功能模块和快速导航入口
• 功能导航：提供各个功能模块的快速访问入口
• 统计信息：显示系统中的数据集数量、文件数量等关键指标

2. 数据接入 (Data Ingestion)

支持多种数据源的接入，方便将外部数据导入系统：

TsFile 接入

• TsFile 上传：支持上传单个或批量 TsFile 文件到服务端，上传后自动刷新文件列表。
• TsFile 导入：从本地文件系统导入 TsFile 文件，支持批量操作。
• 文件管理：上传的 TsFile 文件会自动添加到文件管理模块，支持后续操作。

CSV 接入

• CSV 上传：支持上传单个或批量 CSV 文件到服务端。
• CSV 导入：从本地文件系统导入 CSV 文件，支持批量操作。
• 数据转换：上传的 CSV 文件可转换为 TsFile 格式，保留原始数据。

Parquet 接入

• Parquet 上传：支持上传单个或批量 Parquet 文件到服务端。
• Parquet 导入：从本地文件系统导入 Parquet 文件，支持批量操作。
• 数据转换：上传的 Parquet 文件可转换为 TsFile 格式，保留原始数据。

IoTDB 接入

• IoTDB 连接：支持连接到 IoTDB 数据库，导入时序数据。
• 数据同步：从 IoTDB 同步数据到本地 TsFile 文件。
• 实时采集：支持实时采集 IoTDB 数据并写入 TsFile。

3. 数据集管理 (Dataset Management)

用于对多个 TsFile 文件进行逻辑分组、层级组织与血缘管理，包含以下主要模块：

数据集列表

• 层级管理：支持创建父子数据集，形成树形层级结构，支持折叠/展开。
• 血缘管理 (Lineage)：记录数据集之间的衍生关系（Source → Derived），注册数据集时可通过 parent_path 指定父数据集，Web 界面展示血缘路径。
• 数据集列表：在管理界面查看所有数据集的摘要信息（名称、描述、关联文件数、统计信息等），支持搜索与分页。
• 文件关联：将多个 TsFile 文件关联到某一数据集，支持批量添加/移除和快捷跳转到可视化页面。
• 智能删除与 Re-parenting：删除父数据集时，子节点自动挂载到被删除节点的父节点，避免数据丢失。

TsFile 可视化

• 数据表格：以表格形式展示 TsFile 中的时序数据，支持分页和排序。
• 时序图表：使用 ECharts 绘制时序数据折线图，支持多系列对比和时间范围筛选。
• 列选择：可选择要显示的物理量（FIELD）列，支持多列同时展示。
• 时间筛选：支持按时间范围筛选数据，可设置开始时间和结束时间。
• 数据导出：支持将表格数据导出为 CSV 格式，方便后续分析。
• 设备筛选：支持按设备（TAG 值）筛选数据，查看特定设备的时序数据。

4. 数据质量评估 (Data Quality Assessment)

对数据集下的文件自动或手动触发质量检查，例如空值比例、时间戳连续性、异常点检测，结果以报告/指标形式展示并可导出。

质量维度

• 完整性：检测数据是否存在缺失值，计算缺失比例。
• 一致性：检测同一时间点是否存在重复数据。
• 有效性：检测数据值是否在合理范围内，识别异常值。
• 时效性：检测数据是否按时入库，识别延迟数据。

质量报告

• 总体评分：对四个维度进行综合评分，给出整体质量等级。
• 雷达图：以雷达图形式展示四个维度的得分情况。
• 详细统计：显示总数据点数、缺失点数、冗余点数、异常点数、延迟点数等。
• 异常数据：列出检测到的异常数据，支持点击查看详情。
• 导出功能：支持将质量报告导出为 CSV 或 PDF 格式。

5. 数据标注 (Data Annotation)

支持对时序数据进行标注和标签管理：

标注列表

• 标注浏览：查看所有标注任务的列表，显示任务状态、标注数量等。
• 标注创建：创建新的标注任务，支持选择数据集和时间范围。
• 标注编辑：对已有标注进行编辑，支持添加、修改和删除标注。
• 标注导出：支持将标注数据导出为标准格式，方便后续使用。

标注功能

• 数据预览：在标注时预览原始时序数据，辅助标注决策。
• 快捷标注：提供常用标注快捷键，提高标注效率。
• 标注验证：支持标注数据的验证和质量检查，确保标注准确性。

仓库结构（摘要）

.
├── data/                   # 服务端数据存储（datasets.json, datasets/...）
├── examples/               # 示例脚本与示例数据
├── src/
│   ├── tsfiledataset/      # 客户端 SDK（注册/管理数据集）
│   ├── web/                # Flask Web 应用
│   │   └── app.py          # Flask 主程序
│   └── utils/              # 工具脚本（inspect, debug 等）
├── tests/                  # pytest 测试
├── requirements.txt        # 推荐依赖（用于开发/运行）
└── README.md               # 本文件

快速导航：查看 src/web/app.py 启动 Web 服务；示例脚本在 examples/ 下。

安装 Python 依赖

方法一：使用虚拟环境（推荐）

创建并激活虚拟环境：

Windows PowerShell：

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
.venv\Scripts\Activate.ps1

# 安装依赖
pip install -r requirements.txt

Linux/Mac：

# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

方法二：直接安装（不推荐，可能影响系统环境）

# Windows
pip install -r requirements.txt

# Linux/Mac
pip3 install -r requirements.txt

依赖说明

主要依赖已列在 requirements.txt 中。关键依赖包括：

• Flask：Web 框架，用于提供 HTTP 服务
• pandas：数据处理库，用于数据操作和分析
• tsfile：TsFile 格式支持库（若需操作 TsFile 格式）
• pytest：测试框架，用于运行单元测试和集成测试

常见安装问题

1. 找不到包 (ModuleNotFoundError)：

• 请确认已激活虚拟环境
• 在该环境中安装了依赖
• 检查 Python 版本是否兼容（推荐 Python 3.8+）

2. Windows DLL 加载失败：

• 请确保已安装 Visual C++ Redistributable
• 或将包含 DLL 的目录加入系统 PATH
• src/web/app.py 已尝试自动修复，但部分环境仍需手动处理

3. 权限问题：

• Windows：可能需要以管理员身份运行
• Linux/Mac：可能需要使用 sudo 或 --user 参数

4. 网络问题：

• 如果安装速度慢，可以使用国内镜像源：

  pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  

验证安装

安装完成后，可以验证依赖是否正确安装：

# 查看已安装的包
pip list

# 检查特定包
pip show flask
pip show pandas

运行应用

环境清理（可选）

在启动服务前，如果需要清理之前的 Python/Flask 进程，可运行：

# Windows
taskkill /F /IM python.exe

# Linux/Mac
pkill -9 python

启动服务

在项目根目录运行：

python src/web/app.py

默认服务地址： http://127.0.0.1:5000

示例脚本

注册示例数据集（不启动 Web）：

python examples/user_demo.py

注册示例数据集并带血缘关系：

python examples/lineage_demo.py

在运行这些脚本后，打开 Web 界面可以看到新注册的数据集与血缘关系。

转换性能测试

项目内置了 Arrow/Parquet -> TsFile 转换 benchmark 脚本，可自动生成样本、执行转换、输出 CSV、绘制曲线并生成 Markdown 报告：

python3 scripts/benchmark_conversion.py --sizes 4M 20M 100M --repeats 3

更完整的说明见：docs/conversion_benchmark.md

无界面转换工具包

仓库已抽出独立后端包 tsfile_converter，用于将 CSV/Parquet/Arrow 转为 TsFile，可作为 Python API、CLI 或可选 HTTP API 发布到 PyPI：

python3 -m pip install -e ".[api,dev]"
tsfile-convert input.parquet output.tsfile --format parquet --overwrite --json
tsfile-converter-api --host 127.0.0.1 --port 8000 --output-dir converted_tsfiles

Python API 示例：

from tsfile_converter import ConversionOptions, convert_parquet_to_tsfile

result = convert_parquet_to_tsfile(
    "input.parquet",
    "output.tsfile",
    options=ConversionOptions(time_column="time", table_name="metrics", tablet_rows=262_144, overwrite=True),
)
print(result.to_dict())

运行报告见：docs/tsfile_converter_run_report.md

发布说明见：docs/pypi_conversion_tool.md

运行测试

项目包含若干基于 pytest 的测试。运行：

pytest -q

如果希望只运行单个测试文件，例如：

pytest tests/test_app_utils.py -q

更多测试用例与执行说明见：docs/testcases.md

快速运行测试：

# 运行所有测试并生成 junit + coverage
pytest --junitxml=reports/junit-result.xml --cov=src --cov-report=xml -q

依赖

主要依赖已列在 requirements.txt 中。关键依赖包括：

• Flask
• pandas
• tsfile（若需操作 TsFile 格式）
• pytest（测试）

常见问题（FAQ）

• 找不到包 (ModuleNotFoundError)：请确认已激活虚拟环境，并在该环境中安装了依赖。
• Windows DLL 加载失败：请确保已安装 Visual C++ Redistributable，或将包含 DLL 的目录加入系统 PATH。src/web/app.py 已尝试自动修复，但部分环境仍需手动处理。

开发与贡献

欢迎提交 issue 或 PR：

• 若想添加新特性，请先打开 issue 讨论。
• 测试和文档改进尤为受欢迎。

许可证与联系方式

本仓库未指定特定开源许可证（请在需要时添加 LICENSE 文件）。如需沟通，请在仓库 issue 中留言。