You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
perf(python): reuse prepared series for repeated single-device table queries - #1082
Repeated batch queries whose tag filter selects exactly one device rebuilt the device and timeseries-index metadata on every call. query_table now resolves the requested field columns once through a bounded LRU and executes them as prepared queries: one column through query_prepared, several aligned columns through query_prepared_multi. Queries that select a TAG column, use row-by-row mode, or whose filter matches zero or several devices keep the previous path.
TsFileReader::prepare_table_series() resolves (table, column, tag filter) to a PreparedLocator through the existing device index and parses it once.
The prepared query paths accept a TsBlock row capacity (block_rows) instead of always allocating PREPARED_BATCH_ROWS, so cached queries keep the caller's batch_size block boundaries. The existing C entry points keep their signatures; tsfile_reader_query_prepared_ex and tsfile_reader_query_prepared_multi_ex carry the new parameter.
Python exposes prepare_table_series() and caches single-device field queries behind TSFILE_QUERY_CACHE_SIZE (default 1024, 0 disables). close() releases the cached handles.
Only "not cacheable" error codes fall back to the regular path. I/O, short-read, corruption and OOM errors still reach the caller, so the existing read-failure propagation tests pass unchanged.
Measurements
323 devices x 20,000 points, 2,000 point queries per run, warm page cache, alternating cache on/off (measured on the branch's original base):
query
cache off (median)
cache on (median)
1 field column
229 us
54 us
2 field columns
287 us
102 us
The means include one miss per device; steady state is roughly 50 us (one column) and 100 us (two columns) per query.
Re-measured after merging develop (2026-11-17)
On the current develop base the regular path is itself much faster: develop added a deserialized device-index-node cache (#1091) and batched timeseries-index loading (#1095), which serve exactly the repeated lookup this cache used to skip. Same shape of setup, 2,000 x 2,048-point windows, macOS:
query
cache off (median)
cache on (median)
1 field column
56 us
46 us
2 field columns
101 us
88 us
The prepared path itself is unchanged (~46 us / ~88 us). The end-to-end gain over the current regular path is about 1.1-1.2x rather than the 2.8-4.2x above, because the regular path no longer pays the lookup cost this cache was introduced for. Results, fallbacks and error propagation are unchanged.
Scope
The cache applies only when the tag filter selects exactly one device and every requested column is a stored field. TAG columns, row mode and multi-device filters keep the previous code path; non-cacheable results are remembered so they are not retried on every call.
Results are unchanged: the new tests compare cached and uncached output across one and two columns, column order, time ranges containing nulls, compound filters, eviction, TAG-column fallback and row mode. tests/test_reader_sources.py still verifies that every injected read failure propagates.
python/tests/test_query_table_cache.py: 25 cases, including leading/trailing null-only windows, multi-page batch boundaries and bare-name lookups on cached results.
Full suite after merging develop: C++ 1663 tests, Python 667 passed / 16 skipped; ./mvnw -P with-python verify green (spotless, RAT, checkstyle included).
C++ library and Cython extensions built locally; clang-format applied to the touched files.
…queries
Repeated batch queries whose tag filter selects exactly one device rebuilt
the device and timeseries-index metadata on every call. query_table now
resolves the requested field columns once through a bounded LRU and runs
them as prepared queries: one column through query_prepared, several aligned
columns through query_prepared_multi. Queries that select a TAG column, use
row-by-row mode, or whose filter matches zero or several devices keep the
previous path.
- Add TsFileReader::prepare_table_series(), which resolves
(table, column, tag filter) to a PreparedLocator through the existing
device index and parses it once.
- Let the prepared query paths take a TsBlock row capacity (block_rows)
instead of always allocating PREPARED_BATCH_ROWS, so cached queries keep
the caller's batch_size block boundaries. The existing C entry points keep
their signatures; tsfile_reader_query_prepared_ex and
tsfile_reader_query_prepared_multi_ex carry the new parameter.
- Expose prepare_table_series() in Python and cache single-device field
queries behind TSFILE_QUERY_CACHE_SIZE (default 1024, 0 disables). Only
"not cacheable" error codes fall back to the regular path; I/O, short-read,
corruption and OOM errors still reach the caller. close() releases the
cached handles.
Measured locally (323 devices x 20,000 points, 2048-point windows, 2,000
queries, warm cache): one column 229 us -> 54 us median; two columns
287 us -> 102 us median. Full Python suite: 620 passed.
Closesapache#1081. Relates to apache#1080.
Conflicts:
- python/README.md: develop added the writable-file-object paragraph to the
'Seekable binary file objects' section at the same spot as this branch's
'Repeated point queries' section. Kept develop's section intact and moved
the new section after it.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
The cached prepared-query path can omit null-only rows and cause use-after-free during concurrent cache retirement, alongside memory leaks and result-behavior regressions.
This PR reuses prepared-series metadata for repeated single-device Python table queries, extending the existing prepared-query machinery to reduce lookup overhead.
Changes:
Adds a configurable per-reader LRU cache and a public prepare_table_series() API.
Threads block_rows through Python, C and C++ prepared-query APIs while preserving existing C entry points.
Adds cache regression tests and documents usage, configuration and fallbacks.
File
Description
skills/tsfile/references/python.md
Documents caching and prepared-query controls.
python/tsfile/tsfile_reader.pyx
Implements caching, preparation and block-size controls.
python/tsfile/tsfile_py_cpp.pyx
Adds native preparation and query bridges.
python/tsfile/tsfile_py_cpp.pxd
Declares the new bridge functions.
python/tsfile/tsfile_cpp.pxd
Exposes new C APIs to Cython.
python/tsfile/tag_filter.py
Adds structural cache keys for filters.
python/tests/test_query_table_cache.py
Covers cache equivalence, eviction and fallbacks.
python/README.md
Documents repeated-query optimization.
python/README-zh.md
Adds corresponding Chinese documentation.
cpp/src/reader/tsfile_reader.h
Declares table preparation and block-size parameters.
…ip for prepared reads
Copilot review follow-ups for the table prepared-query cache:
- alloc_prepared_ssi() pruned aligned series with the value index's
statistics, which exclude NULL cells; a window covering only null values
(a trailing or leading null run) returned no rows, whereas the regular
table path returns the aligned null rows. Prune on the shared time index,
as alloc_prepared_multi_ssi() and the aligned page/chunk filtering already
do.
- PreparedSeriesTsBlockReader stopped at every page boundary, so cached
queries returned page fragments instead of filling each TsBlock to the
requested block_rows. Keep decoding into the same block across pages and
chunks, matching the regular table reader's batch boundaries.
- prepare_table_series() leaked the node returned by DeviceMetaIterator::next(),
which transfers ownership: the iterator only destroys nodes it still holds
and its arena does not run destructors. Guard it with
MetaIndexNode::self_deleter.
…e name lookup
Copilot review follow-ups for the table prepared-query cache:
- Eviction, fallback, clear_prepared_query_cache() and close() freed the
native handle explicitly. A concurrent query borrows the raw handle with the
GIL released, so the cache's reference is now dropped instead and the handle
is released once the last in-flight call returns.
- Cached results kept the tree-model name lookup of prepared result sets, so
is_null_by_name()/get_value_by_name() searched for '<table>.<column>' and
raised ValueError. Mark the adapted result as a table result.
Regression tests: leading and trailing null-only windows, multi-page batch
boundaries for one and two columns, and bare-name lookups on cached results.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Concurrent fallback can exceed the prepared-query cache’s configured capacity, while wide projections bypass bulk loading and add repeated metadata reads and allocations.
No open issues 🎉
2 previously missed issues
In code that hasn't changed since last review
Wide projections repeatedly load indexes on cache misses
python/tsfile/tsfile_reader.pyx:437
On a cache miss, an N-field projection resolves the device and loads indexes separately for every column, then reloads each value index and the shared time index during preparation. For projections of 16 or more fields, this bypasses the existing bulk-loading path and adds repeated metadata reads and allocations. Keep wide projections on the regular path until group preparation can resolve the device once, batch-load indexes, and share the time index.
Unsupported-query fallback can exceed the cache capacity
python/tsfile/tsfile_reader.pyx:454
After _run_prepared releases the GIL, another thread can evict this key before the unsupported-query fallback reinserts it, exceeding the configured cache capacity. Cache hits do not enforce the bound again, so only replace the entry if it is still cached, or reapply eviction after inserting the negative result.
… on the regular path
Copilot review follow-ups (second round):
- The unsupported-query fallback reinserted its negative entry without
enforcing the configured capacity. After _run_prepared releases the GIL,
another thread may already have evicted that key, so the reinsert could
exceed TSFILE_QUERY_CACHE_SIZE. Insert through a shared trim helper used by
both insertion paths.
- Wide projections prepared one column at a time, reloading the device index
and each value and time index per column; 16 or more field columns also
bypass TsFileIOReader::get_timeseries_indexes()'s bulk load. Keep
projections of 16+ columns on the regular path and document it.
Regression test: a 16-column projection matches the uncached results and
leaves the cache empty.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Repeated batch queries whose tag filter selects exactly one device rebuilt the device and timeseries-index metadata on every call.
query_tablenow resolves the requested field columns once through a bounded LRU and executes them as prepared queries: one column throughquery_prepared, several aligned columns throughquery_prepared_multi. Queries that select a TAG column, use row-by-row mode, or whose filter matches zero or several devices keep the previous path.TsFileReader::prepare_table_series()resolves(table, column, tag filter)to aPreparedLocatorthrough the existing device index and parses it once.block_rows) instead of always allocatingPREPARED_BATCH_ROWS, so cached queries keep the caller'sbatch_sizeblock boundaries. The existing C entry points keep their signatures;tsfile_reader_query_prepared_exandtsfile_reader_query_prepared_multi_excarry the new parameter.prepare_table_series()and caches single-device field queries behindTSFILE_QUERY_CACHE_SIZE(default 1024, 0 disables).close()releases the cached handles.Measurements
323 devices x 20,000 points, 2,000 point queries per run, warm page cache, alternating cache on/off (measured on the branch's original base):
The means include one miss per device; steady state is roughly 50 us (one column) and 100 us (two columns) per query.
Re-measured after merging
develop(2026-11-17)On the current
developbase the regular path is itself much faster: develop added a deserialized device-index-node cache (#1091) and batched timeseries-index loading (#1095), which serve exactly the repeated lookup this cache used to skip. Same shape of setup, 2,000 x 2,048-point windows, macOS:The prepared path itself is unchanged (~46 us / ~88 us). The end-to-end gain over the current regular path is about 1.1-1.2x rather than the 2.8-4.2x above, because the regular path no longer pays the lookup cost this cache was introduced for. Results, fallbacks and error propagation are unchanged.
Scope
tests/test_reader_sources.pystill verifies that every injected read failure propagates.block_rowsalso removes the hard-coded 65,536-row block that prepared queries used when no row limit was given ([Perf][C++] Point queries rebuild index metadata on every call; prepared series queries are ~7x faster but need fixes #1080).Tests
python/tests/test_query_table_cache.py: 25 cases, including leading/trailing null-only windows, multi-page batch boundaries and bare-name lookups on cached results.develop: C++ 1663 tests, Python 667 passed / 16 skipped;./mvnw -P with-python verifygreen (spotless, RAT, checkstyle included).Closes #1081. Relates to #1080.