Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
7654cf7
[feature](be) Add linear file range coalescing
bobhan1 Aug 28, 2026
90cf5b6
[feature](be) Add cache-aware file range planning
bobhan1 Aug 28, 2026
85894d0
[feature](be) Add file range read scheduler
bobhan1 Aug 28, 2026
c64e719
[feature](be) Reuse remote-only reads for no-write ranges
bobhan1 Aug 28, 2026
563b5ba
[feature](be) Add query read-ahead runtime ownership
bobhan1 Aug 28, 2026
e2a4012
[improvement](be) Add opt-in file range IO tracing
bobhan1 Sep 22, 2026
8a08ae1
[fix](be) Scope filesystem error-code imports to their functions
bobhan1 Oct 15, 2026
4271da9
[feature](be) Add page-driven column read-ahead windows
bobhan1 Aug 28, 2026
e7dbfa1
[feature](be) Add segment range read-ahead coordination
bobhan1 Oct 29, 2026
00fa56b
[feature](be) Connect scalar column readers to range read-ahead
bobhan1 Sep 2, 2026
8190e0f
[feature](be) Initialize scan read-ahead once after pruning
bobhan1 Oct 29, 2026
d03f274
[feature](be) Add complete-block cache write handoff and admission
bobhan1 Aug 28, 2026
a547700
[feature](be) Split consumed ranges for cache writeback
bobhan1 Aug 28, 2026
7cfe76c
[feature](be) Add cache block hole-fill planning
bobhan1 Aug 28, 2026
a7e3899
[feature](be) Add background partial block writeback
bobhan1 Aug 28, 2026
999f5c6
[feature](be) Initialize background hole fill
bobhan1 Aug 28, 2026
6fd7bb6
[feature](be) Route consumed ranges to cache writeback
bobhan1 Aug 28, 2026
1ae1272
[feature](be) Connect read-ahead range writeback
bobhan1 Aug 28, 2026
fd6df2c
[feature](be) Extend range read-ahead to point queries
bobhan1 Sep 2, 2026
a881473
[fix](be) Validate S3 upload buffer alignment on config updates
bobhan1 Oct 29, 2026
b237ebc
[fix](be) Handle irregular cache blocks in writeback coverage checks
bobhan1 Oct 29, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
[feature](be) Connect scalar column readers to range read-ahead
### What problem does this PR solve?

Issue Number: Part of #67611

Related PR: #67579, #67292

Problem Summary: Prepare eligible top-level scalar pages once after pruning and advance scan windows at the data-page read entry before Page Cache lookup. Scalar point reads retain exact-row preparation. Report initialization and page-advancement time, then let ColumnReadAheadPlan accumulate its maintenance sub-timers. Preserve existing page decoding, cache hits and synchronous fallback. ARRAY/MAP/STRUCT, including offsets, null maps and nested children, keep the upstream reader implementation. Their children may have independent predicate/lazy ordinals, so this component adds no dependent-item preparation or cursor-equality assertion. Cover the nested STRUCT/MAP lazy-read crash and complex-column preparation boundary.

### Release note

Connect top-level scalar data-page reads to byte-window read-ahead.

### Check List (For Author)

- Test: Unit Test — 134 tests from 4 suites passed on the integrated #67579 tree with ./run-be-ut.sh -j100 --run (ASAN/PCH, no clean). Repository clang-format 16, header hygiene and git diff --check passed. No cluster or clang-tidy run. This intermediate component commit was not built separately.
- Behavior changed: Yes — introduces opt-in scalar read-ahead while preserving complex-column behavior.
- Does this need documentation: Yes — scope and synchronization are recorded in #67611 and the related PR descriptions.
  • Loading branch information
bobhan1 committed Oct 29, 2026
commit 00fa56b67a25acac9ac6151699b76e61856ccd16
134 changes: 128 additions & 6 deletions be/src/storage/segment/column_reader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@
#include "core/value/decimalv2_value.h"
#include "core/value/vdatetime_value.h" //for VecDateTime
#include "io/fs/file_reader.h"
#include "io/fs/read_ahead_metrics.h"
#include "storage/cache/page_cache.h"
#include "storage/index/ann/ann_index_reader.h"
#include "storage/index/bloom_filter/bloom_filter.h"
#include "storage/index/bloom_filter/bloom_filter_index_reader.h"
Expand All @@ -70,6 +72,7 @@
#include "storage/segment/binary_dict_page.h" // for BinaryDictPageDecoder
#include "storage/segment/binary_plain_page.h"
#include "storage/segment/column_meta_accessor.h"
#include "storage/segment/column_read_ahead.h"
#include "storage/segment/encoding_info.h" // for EncodingInfo
#include "storage/segment/page_decoder.h"
#include "storage/segment/page_handle.h" // for PageHandle
Expand All @@ -78,6 +81,7 @@
#include "storage/segment/row_ranges.h"
#include "storage/segment/segment.h"
#include "storage/segment/segment_prefetcher.h"
#include "storage/segment/segment_read_ahead.h"
#include "storage/segment/variant/variant_column_reader.h"
#include "storage/tablet/tablet_schema.h"
#include "storage/types.h" // for TypeInfo
Expand Down Expand Up @@ -2854,6 +2858,83 @@ Status FileColumnIterator::init(const ColumnIteratorOptions& opts) {

FileColumnIterator::~FileColumnIterator() = default;

Status FileColumnIterator::_init_read_ahead(const ColumnReadAheadRequest& request) {
request.sanity_check();
if (_read_ahead != nullptr) {
DORIS_CHECK(_read_ahead->options() == request.options());
DORIS_CHECK(_read_ahead->reverse() == request.reverse);
return Status::OK();
}

OrdinalIndexReader* ordinal_index = nullptr;
RETURN_IF_ERROR(_reader->get_ordinal_index_reader(ordinal_index, _opts.stats));
DORIS_CHECK(ordinal_index != nullptr);
std::vector<ColumnReadAheadPage> pages;
pages.reserve(ordinal_index->num_data_pages());

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.

[P2] Track the retained read-ahead page metadata

Enabling read-ahead copies every physical page in each scalar column into this plain std::vector, retained as ColumnReadAhead::_pages; dense scans also retain _candidate_pages and window-map nodes. These allocations have neither a tracked allocator nor manual MemTracker accounting, and happen before scheduler admission, so they survive even when every range is rejected. On 64-bit targets the two page arrays alone require at least 44 bytes per selected page: wide segments and concurrent scanners can retain substantial memory that query limits never see. Use tracked containers or balanced accounting/reservation for the planning metadata, preferably sharing immutable ordinal metadata, and cover the budget-rejection case.

for (auto page = ordinal_index->begin(); page.valid(); page.next()) {
pages.push_back(ColumnReadAheadPage {
.page_index = page.page_index(),
.first_ordinal = page.first_ordinal(),
.last_ordinal = page.last_ordinal(),
.range = {.offset = page.page().offset, .size = page.page().size},
});
}
return ColumnReadAhead::create(std::move(pages), request.options(), request.reverse,
&_read_ahead);
}

Status FileColumnIterator::prepare_read_ahead(const ColumnReadAheadRequest& request,
std::vector<ColumnReadAheadPlan>* plans) {
DORIS_CHECK(plans != nullptr);
if (!need_to_read()) {
return Status::OK();
}
if (_read_ahead_segment != nullptr) {
DORIS_CHECK(request.page_driven);
DORIS_CHECK(_read_ahead_segment == request.context->segment);
DORIS_CHECK(_read_ahead->options() == request.options());
DORIS_CHECK(_read_ahead->reverse() == request.reverse);
return Status::OK();
}
auto* statistics = _opts.stats->read_ahead_stats.get();
SCOPED_TIMER(statistics != nullptr ? &statistics->column_plan_time : nullptr);
ColumnReadAheadPlan plan;
{
SCOPED_TIMER(statistics != nullptr ? &statistics->column_init_time : nullptr);
RETURN_IF_ERROR(_init_read_ahead(request));
if (request.page_driven) {
DORIS_CHECK(request.context->segment != nullptr);
_read_ahead->start(*request.scan_rowids, &plan);
_read_ahead_segment = request.context->segment;
}
}
if (!request.page_driven) {
_read_ahead->plan(request.current_rowids, request.current_rowid_count, *request.scan_rowids,
&plan);
}
plan.update_statistics(statistics);
if (!plan.empty()) {
plans->push_back(std::move(plan));
}
return Status::OK();
}

void FileColumnIterator::_advance_read_ahead(int32_t page_index) {
ColumnReadAheadPlan plan;
{
auto* statistics = _opts.stats->read_ahead_stats.get();
SCOPED_TIMER(statistics != nullptr ? &statistics->column_plan_time : nullptr);
SCOPED_TIMER(statistics != nullptr ? &statistics->page_advance_time : nullptr);
_read_ahead->advance(page_index, &plan);
plan.update_statistics(statistics);
}
if (!plan.empty()) {
std::vector<ColumnReadAheadPlan> plans;
plans.push_back(std::move(plan));
static_cast<void>(_read_ahead_segment->apply_plans(std::move(plans)));
}
}

void FileColumnIterator::_trigger_prefetch_if_eligible(ordinal_t ord) {
std::vector<BlockRange> ranges;
if (_prefetcher->need_prefetch(cast_set<uint32_t>(ord), &ranges)) {
Expand Down Expand Up @@ -3248,18 +3329,59 @@ Status FileColumnIterator::_load_next_page(bool* eos) {
}

Status FileColumnIterator::_read_data_page(const OrdinalPageIndexIterator& iter) {
if (_read_ahead_segment != nullptr) {
_advance_read_ahead(iter.page_index());
}
PageHandle handle;
Slice page_body;
PageFooterPB footer;
_opts.type = DATA_PAGE;
PageDecoderOptions decoder_opts;
decoder_opts.only_read_offsets = _opts.only_read_offsets;
RETURN_IF_ERROR(
_reader->read_page(_opts, iter.page(), &handle, &page_body, &footer, _compress_codec));
// parse data page
auto st = ParsedPage::create(std::move(handle), page_body, footer.data_page_footer(),
_reader->encoding_info(), iter.page(), iter.page_index(), &_page,
decoder_opts);
auto* read_ahead_reader = dynamic_cast<SegmentReadAheadFileReader*>(_opts.file_reader);
auto read_page = [&](const ColumnIteratorOptions& options) {
return _reader->read_page(options, iter.page(), &handle, &page_body, &footer,
_compress_codec);
};
auto retry_original = [&](const Status& status) {
if (read_ahead_reader == nullptr) {
return status;
}
LOG(WARNING) << "failed to decode read-ahead page, falling back to original reader, file="
<< _opts.file_reader->path().native() << ", page_offset=" << iter.page().offset
<< ", page_size=" << iter.page().size << ", page_index=" << iter.page_index()
<< ", error=" << status;
if (auto* cache = StoragePageCache::instance(); cache != nullptr) {
StoragePageCache::CacheKey key(_opts.file_reader->path().native(),
_opts.file_reader->size(), iter.page().offset);
cache->erase(key, DATA_PAGE);
}
handle = PageHandle {};
page_body = Slice {};
footer.Clear();
ColumnIteratorOptions fallback_options = _opts;
fallback_options.file_reader = read_ahead_reader->inner_reader().get();
fallback_options.use_page_cache = false;
return read_page(fallback_options);
};

auto st = read_page(_opts);
if (!st.ok()) {
st = retry_original(st);
}
RETURN_IF_ERROR(st);

st = ParsedPage::create(std::move(handle), page_body, footer.data_page_footer(),
_reader->encoding_info(), iter.page(), iter.page_index(), &_page,
decoder_opts);
if (!st.ok() && read_ahead_reader != nullptr) {
st = retry_original(st);
if (st.ok()) {
st = ParsedPage::create(std::move(handle), page_body, footer.data_page_footer(),
_reader->encoding_info(), iter.page(), iter.page_index(),
&_page, decoder_opts);
}
}
if (!st.ok()) {
LOG(WARNING) << "failed to create ParsedPage, file=" << _opts.file_reader->path().native()
<< ", page_offset=" << iter.page().offset << ", page_size=" << iter.page().size
Expand Down
21 changes: 21 additions & 0 deletions be/src/storage/segment/column_reader.h
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,11 @@ class RowRanges;
class ZoneMapIndexReader;
class IndexIterator;
class ColumnMetaAccessor;
class ColumnReadAhead;
class SegmentReadAhead;
struct ColumnReadAheadContext;
struct ColumnReadAheadRequest;
struct ColumnReadAheadPlan;

struct ColumnReaderOptions {
// whether verify checksum when read page
Expand Down Expand Up @@ -414,6 +419,12 @@ class ColumnIterator {

virtual Status init_prefetcher(const SegmentPrefetchParams& params) { return Status::OK(); }

/// Appends data-page plans for scalar columns. Complex iterators keep the original read path.
virtual Status prepare_read_ahead(const ColumnReadAheadRequest& request,
std::vector<ColumnReadAheadPlan>* plans) {
return Status::OK();
}

virtual void collect_prefetchers(
std::map<PrefetcherInitMethod, std::vector<SegmentPrefetcher*>>& prefetchers,
PrefetcherInitMethod init_method) {}
Expand Down Expand Up @@ -597,6 +608,8 @@ class FileColumnIterator : public ColumnIterator {
bool is_all_dict_encoding() const override { return _is_all_dict_encoding; }

Status init_prefetcher(const SegmentPrefetchParams& params) override;
Status prepare_read_ahead(const ColumnReadAheadRequest& request,
std::vector<ColumnReadAheadPlan>* plans) override;
void collect_prefetchers(
std::map<PrefetcherInitMethod, std::vector<SegmentPrefetcher*>>& prefetchers,
PrefetcherInitMethod init_method) override;
Expand All @@ -611,6 +624,11 @@ class FileColumnIterator : public ColumnIterator {
Status _load_next_page(bool* eos);
Status _read_data_page(const OrdinalPageIndexIterator& iter);
Status _read_dict_data();
// Materialize compressed data-page ranges from the ordinal index once. Later calls must keep
// the same window options and scan direction for this iterator.
Status _init_read_ahead(const ColumnReadAheadRequest& request);
// Run before PageIO so both buffered reads and Page Cache hits advance the scan window.
void _advance_read_ahead(int32_t page_index);
void _trigger_prefetch_if_eligible(ordinal_t ord);

std::shared_ptr<ColumnReader> _reader = nullptr;
Expand Down Expand Up @@ -642,6 +660,9 @@ class FileColumnIterator : public ColumnIterator {
bool _enable_prefetch {false};
std::unique_ptr<SegmentPrefetcher> _prefetcher;
std::shared_ptr<io::CachedRemoteFileReader> _cached_remote_file_reader {nullptr};
std::unique_ptr<ColumnReadAhead> _read_ahead;
// Set only for page-driven scans; owned by the enclosing SegmentIterator.
SegmentReadAhead* _read_ahead_segment {nullptr};
};

class EmptyFileColumnIterator final : public ColumnIterator {
Expand Down
Loading