<!--

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

-->

# Apache TsFile 2.5.0

## New Features

- [Go] Added table-model read and write APIs backed by the C++ library, with Tablet and Arrow batch writes, time-range and TAG filtering, pagination, and Arrow batch reads. (#929, #949)
- [Python] Added opt-in persistent dataset indexes and a native query runtime for `TsFileDataFrame`, supporting indexed row slicing and time-range queries across multiple TsFile files. (#911)
- [Java/C++/Python] Added read and write support for binary file-level properties. (#882, #897)
- [Java] Added optional table point counting and a tool to inspect and repair stored table point counts. (#882)
- [C++/Python] Added seekable random-access data sources, including Python binary file objects and remote files opened through libraries such as `fsspec`. (#939)
- [C++/Python] Added an optional memory-mapped local file read backend with `PREAD`, `MMAP`, and `AUTO` modes. (#920)
- [C++] Added CHIMP, RLBE, and CAMEL encodings, Zstandard compression, and optional LZMA2 compression, with Java/C++ compatibility coverage. (#905)
- [C++] Added `tsfile-cli`, a command-line tool for tree-model and table-model inspection, filtered reads, CSV/NDJSON export, CSV import, and physical file layout inspection with `sketch`. (#829, #838, #915, #994, #996, #997, #1002)
- [Tools] Added reusable agent skills for TsFile development and `tsfile-cli` workflows. (#907)

## Improvements

- [Python] Accelerated dataset-index metadata lookups with Cython and descriptor caching, added configurable read-cache and concurrency limits, and added an index-trust option for immutable datasets. (#959, #1004)
- [Python] Aligned Python exceptions and error codes with the native library for consistent error reporting. (#870)
- [C++] Improved batch read throughput with faster Gorilla decoding, bulk column output, and aligned row-offset pushdown. (#873, #898, #863)
- [C++] Added static-library builds and configurable system or verified source-archive dependency sourcing, including offline builds from cached archives. (#894, #905)
- [Java] Added buffered input and configurable `TsFileInput` construction for readers. (#868, #869)
- [Java] Streamlined data-type handling, cached page-reader type services, and moved type dispatch outside batch read and write loops. (#872, #955, #963)
- [Java] Reduced query merge overhead and boxing allocations with primitive long heaps and sets. (#906)
- [Java] Optimized small bitmaps with a long-backed implementation and added range-query APIs. (#871, #884)
- [Java] Added batched null writes and independent bitmap offsets to `ValuePageWriter` for efficient nullable-column writes. (#948)

## Bug Fixes

- [Java] Propagated `IOException` from table-writer `close()` so flush and file-finalization failures are reported to callers instead of being swallowed. (#899)
- [C++] Fixed loss of buffered data when closing writers by flushing pending rows before finalizing the file. (#969)
- [C++/Python] Fixed silent data loss from table-read failures by propagating metadata, decoding, and I/O errors to callers. (#970)
- [C++] Fixed scans ending prematurely when a decoded page contains no rows matching the filter, allowing later matching pages and chunks to be read. (#975)
- [C++] Fixed value/timestamp misalignment when aligned records or Tablets omit measurements, including null padding and synchronized page sealing across columns. (#968)
- [C++] Fixed empty aligned value-page headers and page advancement so leading, intermediate, and consecutive all-null pages do not hide or corrupt subsequent data. (#976, #1001)
- [C++/Python] Fixed residual row-offset handling in non-aligned page decoding, correcting indexed dataset slices across page and chunk boundaries. (#1007)
- [C++] Stopped writing empty chunks for registered but unwritten non-aligned measurements, preventing Java readers from rejecting otherwise valid files as crashed. (#909)
- [C++] Fixed UTF-8 file paths on Windows for reads, writes, and recovery, and prevented existing output files from being overwritten. (#927)
- [C++] Fixed TS_2DIFF FLOAT/DOUBLE page decoding, wide INT64 decoding, SIMD min/max statistics, and Gorilla sentinel-value handling. (#901, #947, #883)
- [Java/C++] Fixed RLBE decoding of malformed blocks by validating block sizes, segment widths, and run lengths. (#913)
- [C++] Fixed reader schema reporting and append recovery to use the encoding and compression stored in the latest chunk instead of library defaults or stale chunk settings. (#926)
- [C++] Preserved shared time statistics in filtered table metadata so FIELD null counts can be calculated correctly. (#989)
- [Java] Fixed `VectorMeasurementSchema` stream deserialization for per-column compressors and partial stream reads. (#941)
- [Java] Fixed dictionary primitive-value lookup through dictionary IDs, corrected `TimeColumn` position counts, and completed its typed accessors. (#961)
- [Python] Fixed omitted BOOLEAN and TIMESTAMP dataset fields and preserved null field values during Arrow-to-NumPy conversion. (#935, #942)
- [Python] Fixed DataFrame subsets closing shared readers and guarded dataset-index access after close to prevent invalid reads and crashes. (#946, #999)
- [C++] Fixed double-free, memory-leak, and null-dereference paths in readers, compressors, Tablets, containers, and C API string getters. (#879, #881)
- [Java] Strengthened encryption metadata length and implementation-type validation while preserving compatibility with custom encryption implementations. (#925, #956)

# Apache TsFile 2.4.0

## New Features

- [Python] Extended `TsFileDataFrame` to support tree-model TsFile files. (#816)
- [Java] Added `Tablet.serializedSize()` for exact serialized-size calculation and pre-allocation of serialization buffers. (#824)

## Improvements

- [C++] Improved read and write throughput with batch codec APIs, single-pass TsBlock decoding, AVX2/NEON SIMD paths, chunk-level parallel reads, and column-parallel writes. (#823)
- [C++] Optimized timeseries metadata loading by eliminating repeated index traversal and I/O, and accelerated exact TAG lookups for single-TAG tables with direct B-tree lookup. (#815)
- [Java] Optimized timeseries metadata reads by reusing device metadata offsets and reduced redundant metadata-index work. (#840)

## Bug Fixes

- [Java/C++] Fixed cross-language compatibility for FLOAT and DOUBLE data encoded with TS_2DIFF, including overflow-page handling and time-decoder selection. (#796)
- [C++] Fixed writer flush-offset handling for multi-gigabyte TsFile files, with tree-model and table-model regression coverage beyond 4 GB. (#839)
- [C++/Python] Fixed crashes and ambiguous device paths involving null TAG values. Python now exposes structured `SeriesPath` values and uses `\N` as the unambiguous null-TAG path marker. (#848)
- [C++] Fixed aligned table null handling, null-TAG metadata-cache collisions, and memory leaks in reader teardown paths. (#823)
- [Java] Fixed table-size accounting when writing metadata for the first table. (#840)


# Apache TsFile 2.3.1

## New Features

- Added scripts to convert CSV, Parquet and Arrow formats to TsFile.
- Adapted TsFile for the MSVC compiler.

## Bugs

- Fixed the issue that the format conversion scripts did not support date and timestamp data types.
- Fixed garbled characters when using Chinese table names in the conversion scripts.
- Fixed the issue where TsFile displayed empty when converting with uppercase column names.

# Apache TsFile 2.3.0

## New Features

- Added C++ interfaces to obtain the start timestamp, end timestamp and record count of each series-level data in TSFile files.
- Added a C++ interface to sequentially read processed data from corrupted TSFile files.
- Added row number-based data query capability for TSFile, supporting pagination with limit and offset.
- Added the capability to read massive TSFile files in DataFrame format.
- Extended TSFile DataFrame reading to support traversal and reading of nested directories.
- Optimized the performance of the Python TSFile interface: TsFile-Cpp returns Arrow-compatible query results, enabling TsFile-Python to directly provide Arrow-backed DataFrame.

## Bugs

- Implemented synchronized sealing of time pages and value pages under the aligned model in C++ interfaces to ensure consistent behavior with the Java side.
- Fixed null value handling defects in the write and read paths of TSFile.

# Apache TsFile 2.2.1

## New Feature

- [Java] Support modifying schema during the write process.
- [Java] Support memory usage estimation for Tablet and related classes.
- [Java] Support I/O size recording during file reading.
- [Java] Support encryption configuration for read and write operations.
- [Python] Support converting DataFrame to TsFile.
- [Python] Support DATE, TIMESTAMP and other new data types.

## Improvement

- [Java] Optimize memory usage calculation for aligned data.
- [Java] Support JDK-25.
- [C++] Upgrade zlib to latest version.

## Bugfix

- [Java] Fixed incorrect query results when reading DATE type in table model.
- [Java] Fixed data corruption when rewriting chunks with time deletion.
- [Java] Fixed chunk metadata loss when deserializing from temporary files.
- [C++] Fixed inability to read files exceeding 2GB.
- [C++] Fixed aligned chunk reader producing wrong output.
- [Python] Fixed DataFrame validation and column name handling issues.

# Apache TsFile 2.2.0

## New Feature

- TsFile-Python fully supports TEXT and STRING data types.
- The Python interface supports the to_dataframe method.
- C++ TsFile supports encoding formats such as RLE.
- Both C++ TsFile and Java TsFile table models support tag filtering.
- C++ TsFile supports writing data of the TEXT type.
- Added the CAMEL encoding method.
- ...

## Improvement/Bugfix

- Fixed the issue where the CppTsFile write and query interfaces had various exceptions when handling null values.
- Fixed the issue where Cpp TsFile failed to write data when TAG and FIELD columns were all empty (only timestamps existed with no actual data).
- Fixed the issue where column names were all converted to lowercase when constructing a Tablet in Cpp TsFile, resulting in the failure to add values to Tablets constructed with uppercase column names.
- Fixed the issue where queries would throw errors when the values of TEXT-type columns in the CPP TsFile table model were partially empty.
- Fixed security vulnerabilities CVE-2025-12183, CVE-2025-66566 and CVE-2025-11226.
- ...

# Apache TsFile 2.1.1

## Improvement/Bugfix
* [JAVA] AbstractAlignedTimeSeriesMetadata.typeMatch always return true in #538
* [JAVA] Ignore the null value passed in the Tablet.addValue method in #540
* [JAVA] Implement extract time filters in #539
* [JAVA] Init all series writer for AlignedChunkGroupWriter in #545
* [JAVA] Check max tsfile version in #548
* [JAVA] Include common classes in tsfile.jar to fix #501 in #510
* [JAVA] Implement extract value filters in #554
* [JAVA] Fix wrong Private-Package declaration (related to #551) in #556
* [JAVA] Avoid repeated calculation of shallow size of map in #559
* [JAVA] Refactor UnknownType to extend AbstractType in #561
* [JAVA] Add Tablet.append in #562

# Apache TsFile 2.1.0

## New Feature
- [Java] Support setting default compression by datatype(#523).
- [Java] Support using environment variables to generate main encrypt key(#512).
- [Java] Support estimating ram usage of measurement schema(#508).
- [Java] Add TsFileLastReader to retrieve the last points in a TsFile(#498).
- [Cpp/C/Python] Support TsFile Table reader and writer.

## Improvement/Bugfix
- [Java] Fix memory calculation of BinaryColumnBuilder(#530).
- [Java] Resolved case sensitivity issue when reading column names(#518).
- [Java] Fix npe when closing the last reader that has not been used(#513).
- [Java] Fix float RLBE encoding loss of precision(#484).

# Apache TsFile 2.0.3

## Improvement/Bugfix
* move ColumnCategory to an outer class in (#461)
* restrict encrypt key length to 16 in (#467)
* Cache hash code of StringArrayDeviceID in (#453)
* Skip time column when generating TableSchema in (#414)
* Check blank column name or table name in (#471)
* Optimizations regarding chunk metadata sort & timeseries metadata serialization in (#470)
* Remove redundant conversion in TableResultSet in (#473)
* Add switch to disable native lz4 in (#480)

# Apache TsFile 2.0.2

## Improvement/Bugfix
- Correct the retained size calculation for BinaryColumn and BinaryColumnBuilder
- Don't print exception log when thread is interrupted (#386)
- Fix float encoder overflow when float value itself over int range (#412)
- Fix date string parse error (#413)
- compaction adapting new type when table alter column type (#415)
- primitive type compatible (#437)
- Fixed the empty string ser/de bug & null string[] array calculation bug
- add getter for encryptParam (#447)


# Apache TsFile 2.0.1

## Improvement/Bugfix
- Modify tablet usage (#358)
- Add column builder compatibility (#367)
- add cache table schema map option (#369)
- fix getVisibleMetadataList
- TimeColumn.reset() throws UnsupportedOperationException (#379)
- Add statistic compatibility (#382)

# Apache TsFile 2.0.0

## New Feature
- TsFile V4 for Table Model by @jt2594838 in #196
- Support dictionary encoding for STRING data type. by @jt2594838 in #238
- Modify default timestamp encoding by @shuwenwei in #309
- Tsfile java interfaces v4 by @shuwenwei in #307
- Convert column name and table name to lower case by @shuwenwei in #322
- Add type cast interfaces in TsDataType by @jt2594838 in #332

## Improvement/Bugfix
- Fix allSatisfy bug in InFilter by @JackieTien97 in #219
- Fix bug in the conversion of int types to timestamp. by @FearfulTomcat27 in #223
- Fix getValue method in Tablet doesn't support Date and Timestamp type by @HTHou in #243
- Fix error when write aligned tablet with null date by @HTHou in #250
- Fix tablet isNull method not correct by @HTHou in #255
- Fixed the issue that the time of the first data item written to TSFile by measurement cannot be a negative number by @luoluoyuyu in #297
- Fix float encoder overflow by @HTHou in #342

# Apache TsFile 1.1.3

* perf: Optimize aligned object memory size calculation
* feat: add markRange / unmarkRange / merge for high-performance bit manipulation
* Modify the TsFileSequenceReaderTimeseriesMetadataIterator next function to return a LinkedHashMap
* fix GroupByMonthFilter.getTimeRanges
* Fix bug in PaginationController
* change config not found log to debug
* Init all series writer for AlignedChunkGroupWriter
* Added memory calculation for tablet
* Dont print exception log when thread is interrupted
* Bump lz4-java version to 1.10.1

# Apache TsFile 1.1.2

## Improvement/Bugfix

* Fix the bug in parse date to int when year out of range by @HTHou in #500
* Add TsFileLastReader for retrieving last points in a TsFile by @jt2594838 in #506
* Added accountable function to measurementSchema by @Caideyipi in #509
* Correct the retained size calculation for BinaryColumn and BinaryColumnBuilder by @JackieTien97 in #514
* add switch to disable native lz4 (#480) by @jt2594838 in #515
* Correct the memory calculation of BinaryColumnBuilder by @JackieTien97 in #530
* Fetch max tsblock line number each time from TSFileConfig by @JackieTien97 in #535
* Support set default compression by data type & Bump org.apache.commons:commons-lang3 from 3.15.0 to 3.18.0 by @jt2594838 in #547
* Avoid calculating shallow size of map by @shuwenwei in #566
* Add methods for RamUsageEstimator by @shuwenwei in #570

# Apache TsFile 1.1.1

## Improvement/Bugfix
* Fixed the issue that the time of the first data item written to TSFile by measurement cannot be a negative number (#297)
* Add LongConsumer ioSizeRecorder in TsFileSequenceReader for IoTDB scan (#301)
* Add readItimeseriesMetadata method (#312)
* Tablet.serialize() may throw an exception due to null values in the Date column (#330)
* Add FlushChunkMetadataListener (#328)
* Add final for readData methods (#347)
* Bump logback to 1.3.15 (#362)
* Fix example compile issue (#400)
* Fixed the empty string ser/de bug & null string[] array calculation bug (#449)

# Apache TsFile 1.1.0

## New Feature
- Support new data types: STRING, BLOB, TIMESTAMP, DATE by @Cpaulyz in #76
- Add an equivalent .getLongs() method to .getTimes() in TimeColumn. by @Sh-Zh-7 in #61
- Return all columns in TsBlock class by @Sh-Zh-7 in #80

## Improvement/Bugfix

- Fix value filter allSatisfy bug by @liuminghui233 in #41
- Fix error log caused by ClosedByInterruptException by @shuwenwei in #47
- Fix the mistaken argument in LZ4 Uncompressor by @jt2594838 in #57
- Remove duplicate lookups in dictionary encoder by @MrQuansy in #54
- Optimize SeriesScanUtil by memorizing the order time and satisfied information for each Seq and Unseq Resource by @JackieTien97 in #58
- Fix TsBlockBuilder bug in AlignedPageReader and PageReader. by @JackieTien97 in #77
- Fix ZstdUncompressor by @lancelly in #132
- fix RLBE Encoding for float and double by @gzh23 in #143
- Fix uncompress page data by @shuwenwei in #161
- Fix encoder and decoder construction of RLBE by @jt2594838 in #162
- Fix aligned TimeValuePair npe by @shuwenwei in #173
- Fix StringStatistics data type by @shuwenwei in #177
- Fix bug in the conversion of int types to timestamp. by @FearfulTomcat27 in #224
- Fix error when write aligned tablet with null date by @HTHou in #251

# Apache TsFile 1.0.0

## New Features

- Support registering devices
- Support registering measurements
- Support adding additional measurements
- Support writing timeseries data without pre-defined schema
- Support writing timeseries data with pre-defined schema
- Support writing with tsRecord
- Support writing with Tablet
- Support writing data into a closed TsFile
- Support query timeseries data without any filter
- Support query timeseries data with time filter
- Support query timeseries data with value filter
- Support BOOLEAN, INT32, INT64, FLOAT, DOUBLE, TEXT data types
- Support PLAIN, DICTIONARY, RLE, TS_2DIFF, GORILLA, ZIGZAG, CHIMP, SPRINTZ, RLBE encoding algorithm
- Support UNCOMPRESSED, SNAPPY, GZIP, LZ4, ZSTD, LZMA2 compression algorithm