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 read-ahead range writeback
### What problem does this PR solve?

Issue Number: Part of #67611

Related PR: #67292, #67579

Problem Summary: Centralize query read-ahead construction so regular scans and exact-row callers share range planning, byte windows, cache probes, scheduler ownership and writeback setup. Merge per-read IO statistics into caller accounting and publish each consumed range once. Submit writeback only for consumed ranges that read remote bytes, preserving no-write policy and avoiding redundant hole filling for File Cache or inflight hits. Carry the read identity through the consumed-range callback so offline traces can attribute background work to its foreground source.

Require both query read-ahead and asynchronous cache writes so disabling the writer preserves synchronous cache filling. Handle a switch changing during scan initialization through the original reader. Keep delayed hole-fill sources open with an aliasing shared_ptr that retains the cached wrapper; regression tests release both the foreground reader and writeback context before completing the queued fill.

### Release note

None

### Check List (For Author)

- Test: Unit Test
    - Component tests are included with the implementation; rebase and synchronization validation is recorded in the related PRs and tracking issue.
    - Repository clang-format 16, header hygiene and git diff --check passed before folding.
    - No cluster, external-object-store benchmark or clang-tidy run during synchronization.
- Behavior changed: Yes, includes final component behavior and applicable diagnostic instrumentation; default enable switches remain off.
- Does this need documentation: Yes, tools/read_io_trace/README.md and related PR/tracking descriptions.
  • Loading branch information
bobhan1 committed Oct 29, 2026
commit 1ae1272fe26a5a29c0b4729d81b646fb18516771
29 changes: 29 additions & 0 deletions be/src/io/cache/cached_remote_file_reader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@
#include "io/cache/file_block.h"
#include "io/cache/inflight_write_buffer_index.h"
#include "io/cache/peer_file_cache_reader.h"
#include "io/cache/range_cache_writeback.h"
#include "io/cache/remote_scan_cache_write_limiter.h"
#include "io/fs/file_reader.h"
#include "io/fs/local_file_system.h"
Expand Down Expand Up @@ -135,6 +136,34 @@ CachedRemoteFileReader::CachedRemoteFileReader(FileReaderSPtr remote_file_reader
}
}

std::shared_ptr<RangeCacheWriteback> CachedRemoteFileReader::make_range_cache_writeback(
const IOContext& io_context, PartialBlockWritebackManager* partial_block_manager) const {
DORIS_CHECK(_cache != nullptr);
DORIS_CHECK(partial_block_manager != nullptr);
if (_resolve_cache_write_mode(&io_context) == CacheWriteMode::NO_WRITE ||
use_remote_only_on_cache_miss(&io_context)) {
return nullptr;
}
auto* write_manager = _cache->async_write_manager();
DORIS_CHECK(write_manager != nullptr);
CacheContext cache_context(&io_context);
return std::make_shared<RangeCacheWriteback>(RangeCacheWritebackOptions {
.write_manager = write_manager,
.partial_block_manager = partial_block_manager,
.inflight_index = config::enable_async_file_cache_write_inflight_write_buffer_index
? _cache->inflight_write_buffer_index()
: nullptr,
// The wrapper closes the inner reader on destruction. Keep the wrapper as the owner
// while background hole fills still read directly through the inner reader.
.source_reader = FileReaderSPtr(shared_from_this(), _remote_file_reader.get()),
.cache_hash = _cache_hash,
.file_size = size(),
.block_size = static_cast<size_t>(config::file_cache_each_block_size),
.admission_ctx = CacheAdmissionContext::from_cache_context(cache_context, _tablet_id),

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] Preserve the query cache-write budget for consumed ranges

For a native cloud query with peer reads enabled and a positive file_cache_query_limit_bytes, the original reader selects synchronous writes and charges new blocks through split_range_into_cells()->try_admit_cache_write(), even when async writes are enabled globally. Read-ahead instead fetches with NO_WRITE, then submits through this admission snapshot, which drops the limiter and its admission flag; neither complete-block nor hole-fill writeback charges it. If the limiter has not tripped before this context is created, a long scalar scan can populate File Cache beyond its query budget. Preserve that admission policy with ownership safe for deferred work.

.io_context = FileRangeReadIOContext::from_caller(io_context),
});
}

void CachedRemoteFileReader::_init_doris_table_cache() {
_cache_hash = BlockFileCache::hash(path().filename().native());
_cache = FileCacheFactory::instance()->get_by_path(_cache_hash);
Expand Down
9 changes: 9 additions & 0 deletions be/src/io/cache/cached_remote_file_reader.h
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ struct AsyncCacheWriteEpoch;
struct IOContext;
struct FileCacheStatistics;
struct PeerFetchResult;
class PartialBlockWritebackManager;
class RangeCacheWriteback;

} // namespace doris::io

Expand Down Expand Up @@ -87,6 +89,13 @@ class CachedRemoteFileReader final : public FileReader,
/// @return Raw pointer to the underlying reader owned by this object.
FileReader* get_remote_reader() { return _remote_file_reader.get(); }

/// Build the immutable cache metadata used to write back consumed query read-ahead ranges.
/// The returned object reads directly from the inner reader while retaining this wrapper,
/// keeping its destructor from closing the source before background hole fills finish.
/// A no-write request returns nullptr.
std::shared_ptr<RangeCacheWriteback> make_range_cache_writeback(
const IOContext& io_context, PartialBlockWritebackManager* partial_block_manager) const;

/// Align a read range to file-cache block boundaries.
/// @param[in] offset Requested read offset in bytes.
/// @param[in] size Requested read size in bytes.
Expand Down
7 changes: 7 additions & 0 deletions be/src/io/io_common.h
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,13 @@ struct FileReaderStats {
size_t read_bytes = 0;
int64_t read_time_ns = 0;
size_t read_rows = 0;

void merge_from(const FileReaderStats& other) {
read_calls += other.read_calls;
read_bytes += other.read_bytes;
read_time_ns += other.read_time_ns;
read_rows += other.read_rows;
}
};

struct FileCacheStatistics {
Expand Down
53 changes: 14 additions & 39 deletions be/src/storage/segment/segment_iterator.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,6 @@
#include "exprs/vliteral.h"
#include "exprs/vmatch_predicate.h"
#include "exprs/vslot_ref.h"
#include "io/cache/cached_remote_file_reader.h"
#include "io/fs/file_reader.h"
#include "io/io_common.h"
#include "runtime/exec_env.h"
Expand Down Expand Up @@ -387,8 +386,7 @@ Status SegmentIterator::init(const StorageReadOptions& opts) {
}

Status SegmentIterator::_init_query_read_ahead() {
if (!config::enable_query_read_ahead || !config::is_cloud_mode() ||
_opts.io_ctx.reader_type != ReaderType::READER_QUERY) {
if (!SegmentReadAhead::enabled() || _opts.io_ctx.reader_type != ReaderType::READER_QUERY) {
return Status::OK();
}

Expand All @@ -399,44 +397,21 @@ Status SegmentIterator::_init_query_read_ahead() {
DORIS_CHECK(scheduler != nullptr);
auto* query_context = _opts.runtime_state->get_query_ctx();
DORIS_CHECK(query_context != nullptr);

ColumnReadAheadOptions eager_options {
.window_bytes = cast_set<size_t>(config::read_ahead_eager_window_bytes),
};
ColumnReadAheadOptions lazy_options {
.window_bytes = cast_set<size_t>(config::read_ahead_lazy_window_bytes),
};
const auto eager_status = eager_options.validate();
const auto lazy_status = lazy_options.validate();
if (!eager_status.ok() || !lazy_status.ok()) {
LOG_EVERY_N(WARNING, 100) << "invalid query read-ahead byte windows; feature disabled for "
"this segment: eager="
<< eager_status << ", lazy=" << lazy_status;
auto read_context = query_context->get_or_create_file_range_read_context(scheduler);
const auto status = SegmentReadAhead::create_for_query(
_file_reader, exec_env, std::move(read_context), _opts, &_segment_read_ahead);
if (!status.ok()) {
LOG_EVERY_N(WARNING, 100)
<< "failed to initialize query read-ahead; use the original read path: " << status;
return Status::OK();
}
SegmentReadAheadOptions options {
.range_plan = {.coalesce_options =
{.max_gap_bytes =
cast_set<size_t>(config::read_ahead_max_gap_bytes),
.max_range_bytes =
cast_set<size_t>(config::read_ahead_max_range_bytes),
.max_read_amplification_ratio =
config::read_ahead_max_read_amplification_ratio},
.cache_block_size = cast_set<size_t>(config::file_cache_each_block_size),
.block_fill_min_coverage = config::read_ahead_block_fill_min_coverage},
.page_cache_probe = _opts.use_page_cache ? make_storage_page_cache_probe(_file_reader)
: ReadAheadPageCacheProbe {},
.range_consumer_factory = {},
};
auto read_context = query_context->get_or_create_file_range_read_context(scheduler);
_segment_read_ahead = std::make_unique<SegmentReadAhead>(
_file_reader, scheduler, std::move(read_context),
io::FileRangeReadIOContext::from_caller(_opts.io_ctx), std::move(options));
_column_read_ahead_context = std::make_unique<ColumnReadAheadContext>(ColumnReadAheadContext {
.eager_options = eager_options,
.lazy_options = lazy_options,
.segment = _segment_read_ahead.get(),
});
// Both enable switches are mutable. If one was disabled after the entry check,
// create_for_query() leaves the context empty and the original reader remains in use.
if (_segment_read_ahead == nullptr) {
return Status::OK();
}
_column_read_ahead_context =
std::make_unique<ColumnReadAheadContext>(_segment_read_ahead->column_context());
return Status::OK();
}

Expand Down
117 changes: 114 additions & 3 deletions be/src/storage/segment/segment_read_ahead.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,16 @@
#include <cstring>
#include <utility>

#include "common/cast_set.h"
#include "common/config.h"
#include "common/logging.h"
#include "io/cache/cached_remote_file_reader.h"
#include "io/cache/range_cache_writeback.h"
#include "io/fs/read_ahead_metrics.h"
#include "runtime/exec_env.h"
#include "storage/cache/page_cache.h"
#include "storage/iterators.h"
#include "storage/segment/column_reader.h"

namespace doris::segment_v2 {
namespace {
Expand Down Expand Up @@ -156,7 +163,7 @@ void SegmentReadAheadFileReader::_finish_page(const PageKey& key, bool consumed)
}
if (consumed_range != nullptr && consumed_range->consumer) {
auto consumer = std::move(consumed_range->consumer);
consumer(consumed_range->read->range(), consumed_range->read->data());
consumer(*consumed_range->read);
}
}

Expand All @@ -182,7 +189,9 @@ SegmentReadAhead::SegmentReadAhead(io::FileReaderSPtr source_reader,
io::FileRangeReadScheduler* scheduler,
std::shared_ptr<io::FileRangeReadContext> context,
io::FileRangeReadIOContext io_context,
SegmentReadAheadOptions options)
SegmentReadAheadOptions options,
ColumnReadAheadOptions eager_options,
ColumnReadAheadOptions lazy_options)
: _source_reader(std::move(source_reader)),
_scheduler(scheduler),
_context(std::move(context)),
Expand All @@ -192,13 +201,115 @@ SegmentReadAhead::SegmentReadAhead(io::FileReaderSPtr source_reader,
? _io_context.statistics
: std::make_shared<io::ReadAheadStatistics>()),
_reader(std::shared_ptr<SegmentReadAheadFileReader>(
new SegmentReadAheadFileReader(_source_reader, _statistics))) {
new SegmentReadAheadFileReader(_source_reader, _statistics))),
_column_context {
.eager_options = eager_options, .lazy_options = lazy_options, .segment = this} {
DORIS_CHECK(_source_reader != nullptr);
DORIS_CHECK(_scheduler != nullptr);
DORIS_CHECK(_context != nullptr);
_io_context.statistics = _statistics;
}

bool SegmentReadAhead::enabled() {
// Read-ahead fetches with NO_WRITE and relies on the async writer after consumption.
// With only read-ahead enabled, retain the original reader so cold pages still fill cache.
return config::enable_query_read_ahead && config::enable_async_file_cache_write &&
config::is_cloud_mode();
}

Status SegmentReadAhead::create_for_query(io::FileReaderSPtr source_reader, ExecEnv* exec_env,
std::shared_ptr<io::FileRangeReadContext> context,
const StorageReadOptions& read_options,
std::unique_ptr<SegmentReadAhead>* output) {
DORIS_CHECK(source_reader != nullptr);
DORIS_CHECK(exec_env != nullptr);
DORIS_CHECK(output != nullptr);
output->reset();
if (!enabled() || read_options.io_ctx.reader_type != ReaderType::READER_QUERY) {
return Status::OK();
}
DORIS_CHECK(context != nullptr);

ColumnReadAheadOptions eager_options {
.window_bytes = cast_set<size_t>(config::read_ahead_eager_window_bytes),
};
ColumnReadAheadOptions lazy_options {
.window_bytes = cast_set<size_t>(config::read_ahead_lazy_window_bytes),
};
RETURN_IF_ERROR(eager_options.validate());
RETURN_IF_ERROR(lazy_options.validate());

auto statistics =
read_options.stats != nullptr ? read_options.stats->read_ahead_stats : nullptr;
if (statistics == nullptr) {
statistics = std::make_shared<io::ReadAheadStatistics>();
if (read_options.stats != nullptr) {
read_options.stats->read_ahead_stats = statistics;
}
}

auto* file_cache_stats = read_options.io_ctx.file_cache_stats;
auto* file_reader_stats = read_options.io_ctx.file_reader_stats;
std::shared_ptr<io::RangeCacheWriteback> range_writeback;
auto cached_reader = std::dynamic_pointer_cast<io::CachedRemoteFileReader>(source_reader);
if (cached_reader != nullptr) {
auto* partial_block_manager = exec_env->partial_block_writeback_manager();
DORIS_CHECK(partial_block_manager != nullptr);
range_writeback = cached_reader->make_range_cache_writeback(read_options.io_ctx,
partial_block_manager);
}
ReadAheadRangeConsumerFactory range_consumer_factory;
if (file_cache_stats != nullptr || file_reader_stats != nullptr || range_writeback != nullptr) {
range_consumer_factory = [file_cache_stats, file_reader_stats, statistics,
range_writeback]() -> ReadAheadRangeConsumer {
std::optional<io::AsyncCacheWriteEpoch> write_epoch;
if (range_writeback != nullptr) {
write_epoch = range_writeback->capture_write_epoch();
}
return [file_cache_stats, file_reader_stats, range_writeback, statistics,
write_epoch = std::move(write_epoch)](const io::FileRangeRead& read) {
const auto stats = read.stats();
if (file_cache_stats != nullptr) {
file_cache_stats->merge_from(stats.file_cache);
}
if (file_reader_stats != nullptr) {
file_reader_stats->merge_from(stats.file_reader);
}
// Cache and inflight-buffer hits already have a complete cache-block owner.
if (write_epoch.has_value() && stats.file_cache.bytes_read_from_remote > 0) {
static_cast<void>(range_writeback->submit_consumed_range(
read.range(), read.data(), *write_epoch, statistics.get(),
read.trace_id()));
}
};
};
}

SegmentReadAheadOptions options {
.range_plan = {.coalesce_options =
{.max_gap_bytes =
cast_set<size_t>(config::read_ahead_max_gap_bytes),
.max_range_bytes =
cast_set<size_t>(config::read_ahead_max_range_bytes),
.max_read_amplification_ratio =
config::read_ahead_max_read_amplification_ratio},
.cache_block_size = cast_set<size_t>(config::file_cache_each_block_size),
.block_fill_min_coverage = config::read_ahead_block_fill_min_coverage},
.page_cache_probe = read_options.use_page_cache
? make_storage_page_cache_probe(source_reader)
: ReadAheadPageCacheProbe {},
.range_consumer_factory = std::move(range_consumer_factory),
};
auto* scheduler = exec_env->file_range_read_scheduler();
DORIS_CHECK(scheduler != nullptr);
auto io_context = io::FileRangeReadIOContext::from_caller(read_options.io_ctx);
io_context.statistics = std::move(statistics);
output->reset(new SegmentReadAhead(std::move(source_reader), scheduler, std::move(context),
std::move(io_context), std::move(options), eager_options,
lazy_options));
return Status::OK();
}

SegmentReadAheadResult SegmentReadAhead::apply_plans(std::vector<ColumnReadAheadPlan> plans) {
COUNTER_UPDATE(&_statistics->plan_calls, 1);
SCOPED_TIMER(&_statistics->plan_time);
Expand Down
31 changes: 27 additions & 4 deletions be/src/storage/segment/segment_read_ahead.h
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,18 @@
#include "io/fs/file_reader.h"
#include "storage/segment/column_read_ahead.h"

namespace doris::segment_v2 {
namespace doris {

class ExecEnv;
class StorageReadOptions;

namespace segment_v2 {

class ColumnIterator;

/// Invoked with the whole physical range at most once, when any registered page successfully
/// consumes bytes from it.
using ReadAheadRangeConsumer = std::function<void(const io::FileRange&, Slice)>;
using ReadAheadRangeConsumer = std::function<void(const io::FileRangeRead&)>;
/// Creates submission-scoped state immediately before asynchronous range tasks are admitted.
using ReadAheadRangeConsumerFactory = std::function<ReadAheadRangeConsumer()>;
/// Returns true when the exact compressed data-page range is already in StoragePageCache.
Expand Down Expand Up @@ -149,7 +156,19 @@ class SegmentReadAhead final {
public:
SegmentReadAhead(io::FileReaderSPtr source_reader, io::FileRangeReadScheduler* scheduler,
std::shared_ptr<io::FileRangeReadContext> context,
io::FileRangeReadIOContext io_context, SegmentReadAheadOptions options);
io::FileRangeReadIOContext io_context, SegmentReadAheadOptions options,
ColumnReadAheadOptions eager_options = {},
ColumnReadAheadOptions lazy_options = {});

/// Read the dynamic query read-ahead switch and cloud-mode requirement.
static bool enabled();

/// Create query read-ahead state when enabled for a query reader. On an inapplicable request,
/// return OK with `output` cleared so callers continue with the original reader.
static Status create_for_query(io::FileReaderSPtr source_reader, ExecEnv* exec_env,
std::shared_ptr<io::FileRangeReadContext> context,
const StorageReadOptions& read_options,
std::unique_ptr<SegmentReadAhead>* output);

SegmentReadAhead(const SegmentReadAhead&) = delete;
SegmentReadAhead& operator=(const SegmentReadAhead&) = delete;
Expand All @@ -161,6 +180,8 @@ class SegmentReadAhead final {

const std::shared_ptr<SegmentReadAheadFileReader>& file_reader() const { return _reader; }

const ColumnReadAheadContext& column_context() const { return _column_context; }

private:
const io::FileReaderSPtr _source_reader;
io::FileRangeReadScheduler* const _scheduler;
Expand All @@ -169,8 +190,10 @@ class SegmentReadAhead final {
const SegmentReadAheadOptions _options;
const std::shared_ptr<io::ReadAheadStatistics> _statistics;
const std::shared_ptr<SegmentReadAheadFileReader> _reader;
const ColumnReadAheadContext _column_context;
};

ReadAheadPageCacheProbe make_storage_page_cache_probe(const io::FileReaderSPtr& file_reader);

} // namespace doris::segment_v2
} // namespace segment_v2
} // namespace doris
Loading