tsfile-cli
Single pipe-friendly C++ binary to inspect, read, export, and create .tsfile
files. Source cpp/tools/. Result data goes to stdout except export,
sketch -o, and write; diagnostics go to stderr.
Reference files:
references/commands.md: command syntax and result fields.references/errors.md: exit-code and failure-handling rules.references/examples.md: reviewed command recipes.
Scope
Use this skill only for the C++ tsfile-cli binary. Route Java
csv2tsfile/parquet2tsfile/arrow2tsfile and table point-count metadata
checks or backfill to the top-level tsfile skill when it is installed.
The names overlap but the semantics do not: tsfile-cli count is a read-only
per-column report, not the Java table point-count property tool. tsfile-cli write is the C++ binary's narrow one-file/stream, one-table CSV import; it
does not replace the Java batch and format-aware import tools.
Binary
- Name
tsfile-cli(CMake targettsfile_cli). CheckPATH,cpp/build/*/bin/tsfile-cli, orcpp/target/build/bin/tsfile-cli. - Build only if missing:
cd cpp && bash build.sh -t=Debug. - Use
tsfile-cli <command> --helpfor the installed binary's supported syntax and result fields before choosing flags.
Read
tsfile-cli <cmd> [opts] <file.tsfile> · tsfile-cli --help | --version | help
| cmd | output | scans pages |
|---|---|---|
ls |
model,object rows for tree devices or table names |
no |
schema |
model,object,column,category,data_type,encoding,compression |
no |
meta |
size_bytes,format_version,model |
no |
stats |
FIELD statistics with null counts and source | maybe |
count |
object/column counts; no summary row | maybe |
head |
first N rows (default 10, -n) |
yes |
cat |
all matching rows (buffered) | yes |
sketch |
physical layout text from the bound printSketch behavior |
no FIELD decode |
export |
writes one object file or a numbered multi-object directory | yes |
Inspect ls, schema, and meta before querying rows to identify the model,
objects, and columns. stats can scan when statistics are unavailable, and
table-model count scans rows; neither is guaranteed to be metadata-only.
For head and cat, omit -d/-t only when the selected model has exactly one
accessible object. Multi-object files require explicit scope. schema,
stats, and count visit every object when scope is omitted. export always
requires explicit scope.
opts: -f table|ndjson|csv (default table, including pipes)
-d <device> | -t <table> (mutually exclusive)
-m <column> repeat for projection or metadata filtering; no comma lists
-n N · --offset N · --start <int64> · --end <int64> for head/cat/export
--tag-filter C OP [V] where OP=eq|neq|regexp|is-null|not-null
--tag-match all|any when two or more tag filters are present
ndjson=one object per line; INT64/TIMESTAMP strings, NULL/NaN/Inf→null · csv=RFC 4180 with header
exit: 0 ok · 1 usage · 2 file open/corrupt · 3 query/runtime
B=cpp/build/Debug/bin/tsfile-cli
$B meta data.tsfile; $B count -t table1 -f csv data.tsfile
$B cat -t table1 --tag-filter device eq dev_1 -m temp -f ndjson data.tsfile
$B head -t table1 -m temp --start 1700000000000 -n 10 -f csv data.tsfile
Write
tsfile-cli write --table <name> (--tag <name> STRING)* (--field <name> <TYPE>)+ [--encoding <TYPE> <ENC>] [--compression <TYPE> <COMP>] (-i <input.csv>|--stdin) -o <out.tsfile> [-v]
Creates a new single-table, table-model file from strict CSV. The target must not already exist; the command never creates tree-model TsFiles and never modifies an existing TsFile.
TYPE ∈ { BOOLEAN, INT32, INT64, FLOAT, DOUBLE, STRING, TEXT, TIMESTAMP, DATE, BLOB }
ENC ∈ bound TsFile encodings such as PLAIN, TS_2DIFF, GORILLA, DICTIONARY
COMP ∈ UNCOMPRESSED, SNAPPY, GZIP, LZO, LZ4, ZSTD, LZMA2
- CSV must contain a unique header with
timeand exactly the declared TAG/FIELD names; rows are mapped by header name, not physical column order. --encodingand--compressionare keyed by declared data type and apply to all declared columns of that type.- CLI rejects explicit ALP, GORILLA_V1, and BOOLEAN/FLOAT/DOUBLE RLE overrides;
ALP reads work but
schemashowsUNKNOWN. LZMA2 requires an enabled build. - CSV null and backslash rules: see
references/commands.mdbefore preparing input. DATEcells areYYYY-MM-DD;TIMESTAMPand rowtimeuse strict decimal int64.- timestamps must be strictly increasing per device (device = tag-column values); different tags may interleave/reuse timestamps. The CLI has no duplicate-time opt-in; out-of-order input reports its line number.
- A failed import deletes its partial output; success is silent unless
-vis used. -vwrites one post-commit summary to stderr:created model=table object=<table> rows=<n> output=<path>plus one line per column with resolved physical settings.- exit:
1usage/parameter error ·2CSV/input problem ·3target/write/commit failure.
printf 'time,id1,s1\n0,dev,0\n1,dev,10\n' \
| tsfile-cli write --table t1 --tag id1 STRING --field s1 INT64 --stdin -o out.tsfile
tsfile-cli count -f csv out.tsfile
Tree-model / JSON / programmatic writes → C++ SDK cpp/examples/cpp_examples/demo_write.cpp
(TsFileTableWriter/TsFileWriter + Tablet); Java/Python writers under java/, python/.
Caveats
head/cat/exportbuffer complete output in memory, including CSV/NDJSON; use row/time/TAG bounds for large files. Nonzero exit means incomplete results.- Table results always include all TAG columns before selected FIELD columns.
sketchfollows the bound TsFileprintSketchtext and does not support-f.