TsFile
Scope
Use this skill for SDK code, Java import and point-count tools, Tree/Table model
decisions, schema design, compatibility, and cross-language integration. Use
the sibling ../tsfile-cli/SKILL.md for the C++ tsfile-cli binary: file
inspection, preview, export, and its explicit single-table CSV
write operation.
Operating Rules
- Before giving a dependency version or version-sensitive API, run
scripts/resolve-version.sh. Pass --root <checkout> when the target is not
the repository that bundles this skill. When no checkout is present, the
script returns the current skill baseline. Inspect external dependency
metadata only when the user targets a different project or release. Do not
treat latest as a release number. Read references/source-policy.md only
when the authority remains ambiguous, sources conflict, or a
freshness/published-release claim matters.
- Use
references/docs-map.yaml only when an official online page, release,
download, or repository link is needed.
- Choose Tree or Table model, then choose one language binding. Do not load all
language references by default.
- Close writers, readers, and result sets so file footers and native resources
are finalized. Validate files with every language that must consume them.
Offline Reference Routing
Read only the files required by the current task:
- Source authority, version conflicts, offline/online selection, and update
rules:
references/source-policy.md
- Official website, download, release, and repository URL registry:
references/docs-map.yaml
- Model selection, schema, data types, and generic read/write workflow:
references/core-concepts.md
- Java SDK code and API guardrails:
references/java.md
- Java CSV/Parquet/Arrow import and table point-count tools:
references/java-tools.md
- Python DataFrame datasets, persistent indexes, resource limits, pandas
conversion, and Arrow batch I/O:
references/dataframe-arrow.md
- File-level properties, timestamp-policy metadata, and Table-model TAG
filters across bindings:
references/properties-filters.md
- C++ static/shared and installed SDK linking, plus parallel read/write
configuration:
references/cpp-build-write.md
- Current Java and C++ encoding/compression factory matrices:
references/encoding-compression.md
- Query-by-row, timestamp ordering, timeseries metadata, C++ random-access
sources/sinks and incomplete-file recovery, Java TsBlock writes,
custom/buffered input, and Tablet object/size APIs:
references/advanced-apis.md
- Python SDK code, seekable sources, local read backends, and parallel controls:
references/python.md
- C++ SDK code and resource management:
references/cpp.md
- C wrapper entry points and lifecycle:
references/c.md
- Version resolution, build requirements, and cross-version checks:
references/compatibility.md
- Encoding, compression, throughput, memory, or storage tuning:
references/performance.md
Do not read references/performance.md for ordinary API questions. Do not read
multiple language references unless the task explicitly crosses languages.
Workflow
For writes, select the model and schema, prefer tablet/batch APIs, write data,
flush where required, close the writer, and reopen the result for validation.
For reads, identify the model and schema, select only needed columns, bound the
time range when possible, consume the result incrementally, and close all
resources.
For compatibility questions, report the local source version and the requested
release separately. Never silently combine signatures from different versions
or language bindings.
Current Baseline Routing
- Use
references/dataframe-arrow.md for TsFileDataFrame, pandas conversion,
persistent indexes and resource limits, PyArrow Table/RecordBatch, or
Arrow C Data batch paths.
- Use
references/properties-filters.md for binary file properties or
Table-model TAG predicate construction and composition.
- Use
references/cpp-build-write.md for C++ library linkage or read/write
concurrency. Configure the current source APIs; do not emit legacy aliases.
- Use
references/encoding-compression.md before naming a factory or claiming
that an encoding/type or compressor combination is constructible.
- Use
references/advanced-apis.md for C++ crash recovery and append through
RestorableTsFileIOWriter, plus the remaining current advanced read and write
surfaces listed in Offline Reference Routing.
Treat these as baseline capabilities. Do not add alternate calls, degraded
results, or compatibility branches for earlier TsFile source lines unless the
user explicitly targets a different checkout or release.
Java Tools
- Route
csv2tsfile, parquet2tsfile, arrow2tsfile, schema-driven import,
import auto-inference, directory import, and failed-file handling to the Java
tools in java/tools/. Read references/java-tools.md before constructing or
running a command.
- Route requests to inspect or backfill the persisted table-level point-count
property to the Java
tsfile-table-point-count tool. This operation can
replace the input file when metadata is missing, so follow the mutation
checks in references/java-tools.md.
- Do not substitute C++
tsfile-cli count for the Java point-count tool. The
former reports per-series counts without changing the file; the latter
validates and may backfill table-level metadata.
Bundled Resources
- Run
scripts/resolve-version.sh [--root <checkout>] to obtain Maven, C++,
Python, and Git version metadata without loading or copying source files. Its
output schema remains stable when no checkout is discovered and then reports
the baseline shipped with this skill.
- When a compatible checkout is available, use maintained examples from the
same commit:
java/examples/, python/examples/example.py, or
cpp/examples/. Do not copy an assets/ template merely to answer an API
question.
- When no compatible checkout is available and the user requests a starter
project, copy only the needed files from
assets/. Supply the target Java
dependency as -Dtsfile.version=<version>; the template intentionally
contains no default TsFile version.
- Run
scripts/validate-assets.sh [--root <checkout>] after changing a
template. It automatically uses a compatible checkout when found and always
performs dependency-free checks. Explicitly select an external dependency
with either --tsfile-version <version> or --java-jar <path> for Java,
--cpp-include <dir> for C++, or --python-runtime for Python.
- Use
scripts/build_tsfile.sh for repository language build checks.
- Use
scripts/example.py only for Python API metadata or writer examples.
1---2# Licensed to the Apache Software Foundation (ASF) under one3# or more contributor license agreements. See the NOTICE file4# distributed with this work for additional information5# regarding copyright ownership. The ASF licenses this file6# to you under the Apache License, Version 2.0 (the7# "License"); you may not use this file except in compliance8# with the License. You may obtain a copy of the License at9#10# http://www.apache.org/licenses/LICENSE-2.011#12# Unless required by applicable law or agreed to in writing,13# software distributed under the License is distributed on an14# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY15# KIND, either express or implied. See the License for the16# specific language governing permissions and limitations17# under the License.18name: tsfile19description: >-20 Work with the current Apache TsFile SDKs, tools, and file format. Use for21 Java, Python, C++, or C reads and writes; Python DataFrame and Arrow batches;22 Java CSV/Parquet/Arrow import; file properties; TAG filters; query-by-row and23 metadata APIs; C++ incomplete-writer recovery and append; static/shared C++24 builds; parallel and TsBlock writes; encoding/compression factories; schema25 design; performance; and cross-language integration. Route operations26 specific to the C++ tsfile-cli binary to the sibling tsfile-cli skill.27metadata:28 source: https://skillmd.com/skills/apache/tsfile29---3031# TsFile3233## Scope3435Use this skill for SDK code, Java import and point-count tools, Tree/Table model36decisions, schema design, compatibility, and cross-language integration. Use37the sibling `../tsfile-cli/SKILL.md` for the C++ `tsfile-cli` binary: file38inspection, preview, export, and its explicit single-table CSV39`write` operation.4041## Operating Rules42431. Before giving a dependency version or version-sensitive API, run44 `scripts/resolve-version.sh`. Pass `--root <checkout>` when the target is not45 the repository that bundles this skill. When no checkout is present, the46 script returns the current skill baseline. Inspect external dependency47 metadata only when the user targets a different project or release. Do not48 treat `latest` as a release number. Read `references/source-policy.md` only49 when the authority remains ambiguous, sources conflict, or a50 freshness/published-release claim matters.512. Use `references/docs-map.yaml` only when an official online page, release,52 download, or repository link is needed.533. Choose Tree or Table model, then choose one language binding. Do not load all54 language references by default.554. Close writers, readers, and result sets so file footers and native resources56 are finalized. Validate files with every language that must consume them.5758## Offline Reference Routing5960Read only the files required by the current task:6162- Source authority, version conflicts, offline/online selection, and update63 rules: `references/source-policy.md`64- Official website, download, release, and repository URL registry:65 `references/docs-map.yaml`66- Model selection, schema, data types, and generic read/write workflow:67 `references/core-concepts.md`68- Java SDK code and API guardrails: `references/java.md`69- Java CSV/Parquet/Arrow import and table point-count tools:70 `references/java-tools.md`71- Python DataFrame datasets, persistent indexes, resource limits, pandas72 conversion, and Arrow batch I/O:73 `references/dataframe-arrow.md`74- File-level properties, timestamp-policy metadata, and Table-model TAG75 filters across bindings:76 `references/properties-filters.md`77- C++ static/shared and installed SDK linking, plus parallel read/write78 configuration:79 `references/cpp-build-write.md`80- Current Java and C++ encoding/compression factory matrices:81 `references/encoding-compression.md`82- Query-by-row, timestamp ordering, timeseries metadata, C++ random-access83 sources/sinks and incomplete-file recovery, Java TsBlock writes,84 custom/buffered input, and Tablet object/size APIs:85 `references/advanced-apis.md`86- Python SDK code, seekable sources, local read backends, and parallel controls:87 `references/python.md`88- C++ SDK code and resource management: `references/cpp.md`89- C wrapper entry points and lifecycle: `references/c.md`90- Version resolution, build requirements, and cross-version checks:91 `references/compatibility.md`92- Encoding, compression, throughput, memory, or storage tuning:93 `references/performance.md`9495Do not read `references/performance.md` for ordinary API questions. Do not read96multiple language references unless the task explicitly crosses languages.9798## Workflow99100For writes, select the model and schema, prefer tablet/batch APIs, write data,101flush where required, close the writer, and reopen the result for validation.102103For reads, identify the model and schema, select only needed columns, bound the104time range when possible, consume the result incrementally, and close all105resources.106107For compatibility questions, report the local source version and the requested108release separately. Never silently combine signatures from different versions109or language bindings.110111## Current Baseline Routing112113- Use `references/dataframe-arrow.md` for `TsFileDataFrame`, pandas conversion,114 persistent indexes and resource limits, PyArrow `Table`/`RecordBatch`, or115 Arrow C Data batch paths.116- Use `references/properties-filters.md` for binary file properties or117 Table-model TAG predicate construction and composition.118- Use `references/cpp-build-write.md` for C++ library linkage or read/write119 concurrency. Configure the current source APIs; do not emit legacy aliases.120- Use `references/encoding-compression.md` before naming a factory or claiming121 that an encoding/type or compressor combination is constructible.122- Use `references/advanced-apis.md` for C++ crash recovery and append through123 `RestorableTsFileIOWriter`, plus the remaining current advanced read and write124 surfaces listed in Offline Reference Routing.125126Treat these as baseline capabilities. Do not add alternate calls, degraded127results, or compatibility branches for earlier TsFile source lines unless the128user explicitly targets a different checkout or release.129130## Java Tools131132- Route `csv2tsfile`, `parquet2tsfile`, `arrow2tsfile`, schema-driven import,133 import auto-inference, directory import, and failed-file handling to the Java134 tools in `java/tools/`. Read `references/java-tools.md` before constructing or135 running a command.136- Route requests to inspect or backfill the persisted table-level point-count137 property to the Java `tsfile-table-point-count` tool. This operation can138 replace the input file when metadata is missing, so follow the mutation139 checks in `references/java-tools.md`.140- Do not substitute C++ `tsfile-cli count` for the Java point-count tool. The141 former reports per-series counts without changing the file; the latter142 validates and may backfill table-level metadata.143144## Bundled Resources145146- Run `scripts/resolve-version.sh [--root <checkout>]` to obtain Maven, C++,147 Python, and Git version metadata without loading or copying source files. Its148 output schema remains stable when no checkout is discovered and then reports149 the baseline shipped with this skill.150- When a compatible checkout is available, use maintained examples from the151 same commit: `java/examples/`, `python/examples/example.py`, or152 `cpp/examples/`. Do not copy an `assets/` template merely to answer an API153 question.154- When no compatible checkout is available and the user requests a starter155 project, copy only the needed files from `assets/`. Supply the target Java156 dependency as `-Dtsfile.version=<version>`; the template intentionally157 contains no default TsFile version.158- Run `scripts/validate-assets.sh [--root <checkout>]` after changing a159 template. It automatically uses a compatible checkout when found and always160 performs dependency-free checks. Explicitly select an external dependency161 with either `--tsfile-version <version>` or `--java-jar <path>` for Java,162 `--cpp-include <dir>` for C++, or `--python-runtime` for Python.163- Use `scripts/build_tsfile.sh` for repository language build checks.164- Use `scripts/example.py` only for Python API metadata or writer examples.