Skip to content

perf(cpp): push down multi-value aligned offsets - #863

Merged
ColinLeeo merged 5 commits into
apache:developfrom
ColinLeeo:perf/multi-aligned-offset-pushdown
Jul 21, 2026
Merged

ColinLeeo merged 5 commits into
apache:developfrom
ColinLeeo:perf/multi-aligned-offset-pushdown

Conversation

@ColinLeeo

Copy link
Copy Markdown
Contributor

Motivation

Multi-value aligned reads accepted row offsets at the upper query layer, but the offset was not pushed down into the chunk/page read path. As a result, rows before the requested offset could still force unnecessary page decompression and decoding.

Changes

  • Add chunk-level offset skipping for multi-value aligned series scans when the time chunk and all value chunks have matching row counts.
  • Allow multi-value aligned page reads to accept row_offset.
  • Add page-level offset skipping in the serial multi-value aligned page loop using the time page statistic count.
  • Preserve partial-page residual offsets so the row reader can consume the remaining in-page offset correctly.
  • Push dense aligned/no-filter table row offsets into the shared multi-value SSI.
  • Synchronize residual SSI offset back to the row reader to avoid double skipping.
  • Add targeted tests for partial-page residual offsets, whole-page offset skipping, and whole-chunk offset skipping.

Performance

Tested on a 6-file time-series dataset with 264 logical series and about 996 million points. The benchmark repeatedly reads fixed 2880-point windows with randomized offsets.

Before this change:

  • ~34 ms/read
  • ~29 reads/s

After this change:

  • ~0.65 ms/read
  • ~1538 reads/s

Overall speedup is about 52x for this offset-heavy random window read workload.

For high-offset reads on the longest series, the 90% offset probe improved from about 410 ms to about 0.99 ms.

Validation

cmake --build cpp/build/test-noantlr --target TsFile_Test -j 8

cpp/build/test-noantlr/test/lib/TsFile_Test \
  --gtest_filter='TsFileReaderTest.*'

cpp/build/test-noantlr/test/lib/TsFile_Test \
  --gtest_filter='TableQueryByRowTest.*Offset*:TableQueryByRowTest.DenseSingleDeviceSsiLevelPushdown:TableQueryByRowTest.DenseAlignedNullsMustUseTimeRowCount'

Results:

- TsFileReaderTest.*: 14 passed, 1 disabled
- table row offset related tests: 15 passed

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.

Pull request overview

This PR improves C++ TsFile read performance for offset-heavy queries by pushing row_offset down into aligned multi-value chunk/page decoding, enabling whole-chunk and whole-page skipping (and partial-page trimming) before expensive decompression/decoding work.

Changes:

  • Add chunk-level offset skipping for multi-value aligned reads when chunk statistics prove dense row-count alignment across time + all value chunks.
  • Extend multi-value aligned page reading to accept/consume row_offset, including whole-page skipping and partial-page trimming via a page plan.
  • Push dense aligned/no-filter table-row offsets into the shared multi-value SSI and synchronize residual offset consumption back to the row reader; add targeted tests.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
cpp/test/reader/tsfile_reader_test.cc Adds/updates tests covering partial-page residual offset trimming, whole-page skipping, whole-chunk skipping, and filtered-stream offset semantics.
cpp/src/reader/tsfile_series_scan_iterator.h Adds a helper to consume row offsets on the iterator as underlying readers skip rows.
cpp/src/reader/tsfile_series_scan_iterator.cc Introduces multi-value aligned chunk-level offset skipping gated by “fully satisfies filter” checks and count consistency across columns.
cpp/src/reader/chunk_reader.h Splits page-statistics filter checks into “may satisfy” vs “fully satisfies” to gate safe count-based offset skipping.
cpp/src/reader/chunk_reader.cc Applies the new “may/fully satisfy” distinction so offset-by-count skipping only happens when the filter fully covers the page.
cpp/src/reader/block/single_device_tsblock_reader.h Tracks whether row offset was pushed into a shared SSI and adds a hook to consume SSI offsets when the row reader skips.
cpp/src/reader/block/single_device_tsblock_reader.cc Pushes offsets into SSI for dense aligned/no-filter reads and synchronizes residual offset back to the reader while advancing/skip-rows.
cpp/src/reader/aligned_chunk_reader.h Extends multi-value aligned page APIs to accept row_offset and updates page-plan build to consume offsets.
cpp/src/reader/aligned_chunk_reader.cc Implements page-plan-based offset consumption (including boundary-page holes), plus serial-path whole-page skipping when safe.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines +85 to +87
void consume_row_offset(int count) {
row_offset_ = std::max(0, row_offset_ - count);
}
Comment on lines 186 to +193
dense_row_count_ = compute_dense_row_count(time_series_indexs);
if (time_filter == nullptr && field_filter == nullptr &&
dense_row_count_ >= 0 && remaining_offset_ >= dense_row_count_) {
remaining_offset_ -= dense_row_count_;
delete current_block_;
current_block_ = nullptr;
return common::E_OK;
}

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.

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Comment on lines 43 to +47
using namespace common;

TEST(TsFileSeriesScanIteratorTest, ConsumeRowOffsetSaturates) {
storage::TsFileSeriesScanIterator ssi;
ssi.set_row_range(/*offset=*/10, /*limit=*/-1);
Comment on lines +1509 to +1513
const int32_t page_row_count =
page_info.row_end - page_info.row_begin;
const int32_t rows_to_skip =
std::min(page_row_count, row_offset);
page_info.row_begin += rows_to_skip;

@jt2594838 jt2594838 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.

LGTM

@ColinLeeo
ColinLeeo merged commit 7a7d7f9 into apache:develop Jul 21, 2026
29 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.

4 participants