Skip to content

perf(python): reuse prepared series for repeated single-device table queries - #1082

Merged
ColinLeeo merged 6 commits into
apache:developfrom
ColinLeeo:perf/python-query-table-prepared-cache
Nov 18, 2026
Merged

ColinLeeo merged 6 commits into
apache:developfrom
ColinLeeo:perf/python-query-table-prepared-cache

Conversation

@ColinLeeo

@ColinLeeo ColinLeeo commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

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.
  • block_rows also 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.
  • 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.

Closes #1081. Relates to #1080.

…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.

Closes apache#1081. Relates to apache#1080.
@ColinLeeo
ColinLeeo force-pushed the perf/python-query-table-prepared-cache branch from 285bd62 to 4267cb9 Compare November 10, 2026 08:35
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.
@ColinLeeo
ColinLeeo requested a balanced review from Copilot November 17, 2026 09:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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.

5 open issues
What changed in this PR

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.
cpp/​src/​reader/​tsfile_reader.cc Resolves table fields into prepared series.
cpp/​src/​reader/​tsfile_executor.h Extends prepared-execution declarations.
cpp/​src/​reader/​tsfile_executor.cc Forwards block capacity to prepared readers.
cpp/​src/​reader/​block/​prepared_series_tsblock_reader.h Adds configurable block-capacity state.
cpp/​src/​reader/​block/​prepared_series_tsblock_reader.cc Applies requested capacity when producing blocks.
cpp/​src/​cwrapper/​tsfile_cwrapper.h Declares preparation and extended query APIs.
cpp/​src/​cwrapper/​tsfile_cwrapper.cc Implements new APIs and preserves legacy wrappers.

Review effort: Balanced

Comment thread python/tsfile/tsfile_reader.pyx Resolved
Comment thread python/tsfile/tsfile_reader.pyx Resolved
Comment thread cpp/src/reader/tsfile_reader.cc Resolved
Comment thread python/tsfile/tsfile_reader.pyx Resolved
Comment thread python/tsfile/tsfile_reader.pyx Resolved
…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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Medium severity 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.

Medium severity 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.

5 resolved since last review

Review effort: Balanced

… 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.
@ColinLeeo
ColinLeeo merged commit b20a531 into apache:develop Nov 18, 2026
66 of 69 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Perf][Python] TsFileReader.query_table() does not reuse the dataset-layer prepared/cache machinery

2 participants