TsFile-CLI

tsfile-cli 是一个单一、对管道友好的 C++ 命令行工具，用于在 shell 中检视 并 导入 Apache
TsFile（.tsfile）文件。读取类命令将数据打印到
stdout、诊断信息打印到 stderr，因此可与 awk、jq、sort 等组合使用；write 命令
将 CSV/TSV 导入为新的 .tsfile。

从源码构建

CLI 是 C++ 模块的一部分。用 Maven 包装器构建即可——它会下载固定版本的 CMake，为你编译整个
C++ 模块（libtsfile 共享库 + tsfile-cli 可执行文件）。

前置条件：用于运行 Maven 的 JDK（8+），以及 C++11 编译器（GCC / Clang）。

在仓库根目录执行：

./mvnw clean package -P with-cpp

会在 cpp/target/build/ 下生成：

产物	路径
CLI 可执行文件	cpp/target/build/bin/tsfile-cli
共享库	cpp/target/build/lib/libtsfile.so（Linux）——macOS 为 libtsfile.dylib

若只想用 CMake 构建 CLI 而不经过 Maven（需 C++11 编译器与 CMake ≥ 3.11），改在 cpp/ 下执行：

mkdir -p build/Release && cd build/Release
cmake ../.. -DCMAKE_BUILD_TYPE=Release
make -j tsfile_cli      # -> cpp/build/Release/bin/tsfile-cli

libtsfile 会一并构建在 cpp/build/Release/lib/ 下。

tsfile-cli 动态链接 libtsfile。用完整路径 就地 运行即可自动找到该库：

cpp/target/build/bin/tsfile-cli --version    # -> tsfile-cli (Apache TsFile C++) <version>
cpp/target/build/bin/tsfile-cli --help

若要在 别处 运行该二进制（例如把它从构建目录拷出来后），动态加载器必须能找到 libtsfile.so。
要么让加载器指向构建目录下的 lib/，要么把该库拷到标准位置：

# 让加载器指向构建目录的 lib（Linux；macOS 用 DYLD_LIBRARY_PATH）
export LD_LIBRARY_PATH=/path/to/cpp/target/build/lib:$LD_LIBRARY_PATH

# —— 或者 —— 把库拷到系统库路径
sudo cp cpp/target/build/lib/libtsfile.so /usr/local/lib/ && sudo ldconfig

使用方式

tsfile-cli <command> [options] <file.tsfile>
tsfile-cli --help | --version | help

退出码：0 成功，1 用法/参数错误，2 文件打开/损坏，3 查询/运行时错误。

读取

命令	说明
ls	列出设备（树模型）或表（表模型），每行一个名称
schema	每序列的 target, measurement, datatype, encoding, compression
meta	文件概要：模型、设备/表/序列数、时间范围、文件大小
stats	每序列的 count, start_time, end_time, min, max, first, last, sum
count	每序列行数及一行 total（来自统计信息，不扫描 page）
head	前 N 行（默认 10；用 -n）
cat	所有匹配行，流式输出（table 格式会缓冲以对齐列）
sample	可复现的蓄水池抽样（默认 10；-n、--seed）

元数据类命令（ls / schema / meta / stats / count）无需解码数据即可回答大多数问题。

通用选项：

选项	含义
-f, --format csv|tsv|json|table	输出格式；TTY 下默认 table，管道下默认 tsv
-d, --device <id> / -t, --table <name>	限定到一个设备 / 表（互斥）
-m, --measurements a,b,c	列投影（schema、stats、count、head、cat、sample）
-n, --limit N / --offset N	最大行数 / 跳过行数（head、cat；--offset 不适用于 sample）
--start <ms> / --end <ms>	闭区间的毫秒时间范围（head、cat、sample）
--seed N	可复现抽样种子（仅 sample）
--tag-filter C OP V / --tag-between C L U / --tag-not-between C L U	head、cat、sample 的表标签谓词；OP 为 eq、neq、lt、lteq、gt、gteq、regexp、not-regexp
--no-header	不输出表头行
--model tree|table	强制指定模型（否则自动检测）

json 输出为 NDJSON（每行一个 JSON 对象，对应一行数据；数字/布尔裸输出，其他值加引号，空值为 null；非有限浮点数
——NaN/Inf——变为 null）。CSV 输出遵循 RFC 4180。时间戳为原始毫秒时间戳。table 格式会在内存中
缓冲所有行以对齐列，因此导出大文件时优先用 csv/tsv/json。

BIN=cpp/build/Debug/bin/tsfile-cli
$BIN ls -f tsv data.tsfile                          # 列出表 / 设备
$BIN meta data.tsfile                               # 快速文件概览
$BIN count -t table1 -f tsv data.tsfile             # 行数，不扫描 page
$BIN cat -t table1 --tag-filter device eq dev_1 -m temp -f tsv data.tsfile
$BIN cat -m temp,humidity --start 1700000000000 -f csv data.tsfile | head
$BIN sample -m temp -n 20 --seed 42 -f json data.tsfile | jq .

对于表模型文件，行命令（head / cat / sample）在不指定 -t <table> 时只查询 第一个 表；
count 覆盖所有表。

写入（导入）

tsfile-cli write 将 CSV/TSV 行导入为一个 新的表模型 .tsfile（输出会被覆盖）。输入的第一列是
时间戳（毫秒）；其余列通过 --columns 显式声明——不做类型推断。

时间戳必须 按设备严格递增，设备由其 tag 列取值标识（共享相同标签的行构成同一设备的时间线）。
不同标签组合的行可自由交错并复用时间戳。乱序输入会被拒绝并报出错行号，导入失败不会留下输出文件。
--output 必须与输入文件不同。

tsfile-cli write --table <name> --columns <spec> -o <out.tsfile> \
                 [-f csv|tsv] [--no-header] [--header-match] [-v] [<input> | -]

--columns 是逗号分隔的 name:TYPE:category 列表，其中 category（不区分大小写）为 tag 或
field，TYPE（不区分大小写）为 BOOLEAN, INT32, INT64, FLOAT, DOUBLE, STRING, TEXT, TIMESTAMP, DATE, BLOB 之一——例如 --columns "id1:STRING:tag,s1:INT64:field"。DATE 单元格写作
YYYY-MM-DD，TIMESTAMP 单元格为毫秒。每列按其类型的引擎默认编码与压缩存储。

选项	含义
--table <name>	输出表名（会转小写）
--columns <spec>	有序数据列（不含开头的时间戳列）
-o, --output <path>	输出 .tsfile（必填；会被覆盖）
<input> / -	输入文件，或 - / 省略表示 stdin
-f csv|tsv	输入分隔符（默认 csv；json / table 被拒绝）
--no-header	输入无表头行（默认首行为表头并跳过）
--header-match	校验表头名是否与 --columns 一致
-v, --verbose	向 stderr 打印 wrote N rows to <out>（否则成功时静默）

空单元格写为 null。成功时静默（Unix 风格），用 -v 打印一行摘要。

# 通过管道往返
printf 'time,id1,s1\n0,dev,0\n1,dev,10\n' \
  | tsfile-cli write --table t1 --columns "id1:STRING:tag,s1:INT64:field" -o out.tsfile -
tsfile-cli count -f tsv out.tsfile          # -> t1.dev  s1  2

与 AI 助手配合使用 skill

cpp/tools/skills/tsfile-cli/SKILL.md 是一份机器可读的参考，描述了如何
正确驱动 tsfile-cli。支持 skill 的 AI 编码助手可以加载它，从而辅助检视与导入 .tsfile
文件。