Skip to main content

Apache TsFile

Apache TsFile is a columnar file format (time-series data

storage) designed by the Apache IoTDB project for efficient storage, compression, and query of time-series data on disk.

  • Columnar file format optimized for time-series workloads (data storage)
  • Supports time-aligned storage of timestamps and multiple measurement columns (time-series management)
  • Applies compression and encoding schemes for reduced storage footprint and I/O overhead (data compression)
  • Provides on-disk file organization for sequential and random access queries over time ranges (data access)
  • Serves as the underlying storage format used by Apache IoTDB for sensor and Internet of Things (IoT) data (IoT data infrastructure)

More About Apache TsFile

Apache TsFile is a columnar on-disk file format (time-series data storage) originally developed within the Apache IoTDB ecosystem to store and manage time-series data, such as sensor readings, metrics, and device telemetry. It targets workloads where large volumes of timestamped records from many measurements must be written, compressed, and queried efficiently. In this context, TsFile acts as the persistent storage layer that organizes data for time-series databases and related applications.

The format structures data around time and measurement dimensions (time-series management). Each TsFile stores a sequence of time-series, where each time-series corresponds to a device or measurement path with associated timestamps and values. By organizing data in a columnar layout, TsFile enables compression and vectorized access patterns, which are useful for analytical queries that scan large ranges of data over selected measurements or time intervals.

Apache TsFile incorporates encoding and compression schemes (data compression) tailored to time-series characteristics, such as monotonic or near-monotonic timestamps and numerically correlated value sequences. These encodings reduce disk usage and I/O while preserving query capabilities. The file structure includes metadata that indexes time-series, chunks, and pages, so query engines can locate and read only relevant segments, reducing unnecessary disk reads and improving query latency for range scans and aggregation operations.

In enterprise environments, TsFile is used primarily as the storage format underneath Apache IoTDB (IoT data infrastructure), which targets industrial IoT, monitoring, and operational telemetry scenarios. Deployments ingest data from sensors, control systems, and monitoring agents, and TsFile files are written to local or distributed file systems. The format supports append-oriented workloads, enabling continuous ingestion while maintaining organized metadata for downstream querying, retention, and backup workflows.

Architecturally, TsFile defines a layout of headers, metadata blocks, and data chunks (file format specification) that can be parsed by compatible engines. This includes support for multiple data types, such as numeric and boolean values, and a schema-aware organization of measurement definitions. Its design aligns with Time-Series Database (TSDB) architectures that separate logical schema management from physical file layout, allowing higher-level services to manage devices, measurements, and queries while delegating low-level I/O and compression to the TsFile layer.

For interoperability, TsFile is positioned as an independent storage format within the Apache ecosystem (file format ecosystem). While it is tightly associated with Apache IoTDB, the project documents TsFile as a reusable format that other tools can adopt to read and write time-series data using the same on-disk structure. This makes TsFile relevant in directories and taxonomies under categories such as time-series databases, columnar storage formats, IoT data storage, and on-disk data encoding frameworks.