TSFile.Net

Native C# implementation of Apache TsFile -- a columnar storage file format for time series data.

English | 中文

Features

• Cross-language binary compatibility -- files written by TSFile.Net can be read by Java and C++ implementations, and vice versa.
• Tree and Table dual data models -- supports both the traditional device.measurement tree model and the new table model with tagged schemas.
• Rich encoding support -- PLAIN, TS_2DIFF, RLE, GORILLA, GORILLA_V1, CHIMP, SPRINTZ, RLBE, CAMEL, REGULAR, ZIGZAG, DICTIONARY, BITMAP, FREQ.
• Multiple compression options -- UNCOMPRESSED, GZIP, LZ4, ZSTD, LZMA2, SNAPPY.
• Optional AES-128-CBC encryption -- encrypt pages at rest via a two-level key derivation scheme matching the Java implementation.
• Zero NuGet dependencies -- all third-party code (compression, math) is source-vendored under third_party/.
• Targets .NET 10.0, runs on Windows, Linux, and macOS.

Quick Start

See docs/en/quickstart.md for a 5-minute walkthrough with complete, runnable code examples.

// Write
using var writer = TsFileWriter.Open("example.tsfile");
writer.RegisterTimeseries(new StringArrayDeviceId("root.dev1"),
    [new MeasurementSchema("s1", TSDataType.INT32)]);
// ... write data via Tablet ...
writer.Close();

// Read
using var reader = TsFileReader.Open("example.tsfile");
var rs = reader.Query(["root.dev1.s1"], 0, long.MaxValue);
while (rs.HasNext()) { Console.WriteLine($"{rs.GetTimestamp()}: {rs.GetValue(0)}"); }
reader.Close();

Relationship with Apache TsFile

TSFile.Net is a fully independent C# port of Apache TsFile. It is aligned with our enhanced fork of Apache TsFile 2.4.0, which adds cross-language compatibility fixes, additional encodings (CHIMP/SPRINTZ/RLBE/CAMEL), AES-128-CBC encryption, and ZSTD/LZMA2 compression. TSFile.Net reads and writes the same binary TsFile format as this fork, ensuring full cross-language compatibility.

Key differences from the Java reference:

• Pure C# idioms (PascalCase, Span<T>, IDisposable, record types) — not a line-by-line translation
• Zero NuGet dependencies — all third-party code is source-vendored in third_party/
• Independent versioning and release cycle
• Full cross-language test suite validating binary compatibility with Java/C++

See docs/en/architecture.md for detailed design decisions and differences.

Project Structure

TSFile.Net/
├── src/TSFile.Net/           # C# library source
├── tests/
│   ├── TSFile.Net.Tests/     # Unit tests
│   └── cross-tests/          # Cross-language compatibility tests
├── examples/                 # Usage examples
├── third_party/              # Source-vendored dependencies
├── docs/
│   ├── en/                   # English documentation
│   └── zh/                   # Chinese documentation
└── TSFile.Net.sln            # Solution file

Building

dotnet build TSFile.Net.sln

Running Tests

dotnet test TSFile.Net.sln

Docs

Document	Description
Quick Start	5-minute walkthrough
Architecture	Relationship with Apache TsFile and design decisions
API Guide	Detailed API reference
File Format	TsFile binary format specification
Building	Build from source
Contributing	Contribution guide
中文文档	中文版文档

License

Apache-2.0