Repository navigation
Conversation
### What problem does this PR solve? Issue Number: N/A Related PR: apache/doris#68791 Problem Summary: Document the external scan spreading variable in the current English and Chinese session-variable reference. Explain the preserved default scheduling, explicit automatic mode, bounded hash candidates, locality and cache tradeoffs, and persisted global values. ### Release note None ### Check List (For Author) - Test: git diff --check and targeted front matter, code fence, navigation and content checks; full site build not run. - Behavior changed: No - Does this need documentation: Yes; this is the documentation change.
5 of 16 tasks
Gabriel39
pushed a commit
to apache/doris
that referenced
this pull request
Oct 15, 2026
#68791) ### What problem does this PR solve? Issue Number: N/A Related PR: #68726 Problem Summary: Repeated independently planned queries for a single remotely accessible external file split can select the same backend under consistent hashing. The candidate order is stable, each query starts with zero assigned weight, and the existing minimum-weight tie rule repeatedly selects the same candidate. Increasing the configured candidate count alone does not remove this hotspot. Add the session variable `external_scan_consistent_hash_spread_num` with default **1**, preserving existing scheduling: | Value | Behavior | | --- | --- | | `1` (default) | Preserve the original strategy, configured candidate counts, tie rule and global redistribution. This is a mode, not a one-backend limit. | | `0` | Enable automatic spreading across all eligible BEs in the query's compute group. Use the hash strategy when file cache or consistent hashing is enabled; otherwise use the random strategy. | | `N > 1` | Spread within at most N distinct hash candidates when file cache or consistent hashing is enabled; otherwise retain original round-robin scheduling. | In spread mode, select the candidate with the least query-local assigned split weight and break ties uniformly at random. Assign each split once, retain weight history across batches, and honor compute-group eligibility, local preference and mandatory Host constraints. Candidate counts are capped by the eligible BE count; the implementation is not specific to three BEs. Disable global split redistribution only in spread mode so it cannot move a split outside its candidate or locality constraints. Do not allocate unused alternative-host lists in this mode. With many splits, balancing is limited to each split's candidates and can be less even than the original global redistribution. This PR adds no live CPU monitoring, shared query counter, COUNT pushdown, DOP adjustment or BE cache protocol. It is independent of #68726 and does not include that PR's commits. The existing round-robin path remains available; when #68726 is merged, its round-robin fix also remains in effect for original-mode callers. The variable does not enable file caching. With caching enabled, automatic mode can warm copies on every eligible BE and increase remote warmup reads and cache storage. Persisted global values survive upgrades; restoring the compiled default to 1 does not reset an already saved global 0. `UNSET VARIABLE` restores the compiled session default 1. Manual performance evidence, collected on scheduling revision `7e4fb1c549d` before this final default-value adjustment: the same independent FE binary, three unchanged BEs on one shared physical host with distinct logical Hosts and disjoint nonexclusive four-core affinities; one million-row single-file CSV SUM; file cache and consistent hashing enabled; all candidate caches warmed; concurrency 64; 10-second warmup and 60-second measurement window; three alternating pairs changing only `spread=1` versus `spread=0`. | Mode | Mean successful QPS | | --- | ---: | | Original (`1`) | 13.3944 | | Automatic (`0`) | 39.2778 | The pooled ratio was **2.9324x**, with paired ratios 2.8782x–2.9603x. All six groups had zero query errors. QPS counts correct completions within the fixed window; late completions are excluded, all workers are joined, and latency includes the tail of queries started within the window. The original hot BE used 97.5%–98.7% of its four-core capacity; automatic mode used 87.2%–97.7% across the three BEs. Whole-invocation remote and peer read increments were zero. This evidence applies to the measured warm-cache shared-host workload. It is not a new benchmark of final revision `813826a7feb`, a cold-start result, a strict >=3x guarantee, a three-physical-host acceptance result or customer validation. The final adjustment changes the default and documentation, not the explicit spread-selection algorithm; spreading must now be explicitly enabled to seek this benefit. No throughput from the related COUNT optimization is attributed to this PR. ### Release note Add opt-in spreading for remote external file scan splits. `external_scan_consistent_hash_spread_num` defaults to 1 and preserves original scheduling. Set it to 0 to spread across all eligible BEs, or a value above 1 to bound hash candidates when file cache or consistent hashing is enabled. Spreading can increase cache copies and warmup costs. Persisted global values are retained on upgrade. ### Check List (For Author) - Test - [x] Regression test - [x] Unit Test - [x] Manual test (add detailed scripts or steps below) - [ ] No need to test or manual test. Explain why: - [ ] This is a refactor/code format and no logic has been changed. - [ ] Previous test can cover this change. - [ ] No code files have been changed. - [ ] Other reason Validation performed on the final revision: - Standard `run-fe-ut.sh --run 'FederationBackendPolicySpreadTest,VariableMgrTest#testExternalScanConsistentHashSpreadVariable,FederationBackendPolicyTest'`: 33 tests passed, zero failed/error/skipped. Coverage includes 1/2/3/5 BEs, random ties, multiple batches, locality, bounds, forwarding, original-mode compatibility, default 1 and explicit 0 strategy selection. - Standard `build.sh --fe --clean -j16` and integrated Checkstyle passed. An earlier production build failed with incomplete class/type errors; its evidence was retained and the clean build succeeded without unrelated source edits. - Standard `run-regression-test.sh` with an isolated personal configuration: - `-g p0 -d query_p0/ddl/set_and_unset_commands -s test_external_scan_consistent_hash_spread_variable`; output generated by the framework using `-forceGenOut`, then verified normally. - `-g external -d external_table_p0/tvf -s test_external_scan_consistent_hash_spread`; explicitly enables 0 for automatic-path coverage. - Both suites passed with zero failed/fatal/skipped suites. The fixture is generated by the suite in personal MinIO. - Isolated FE/BE health checks passed; BE process IDs and binary hashes were unchanged. No environment configuration or work log is included. - Separate manual warm-cache experiment on revision `7e4fb1c549d`, described above. Each mode was also certified by 100 query-owned profiles: correct result, one source split/range, one positive execution target, one million rows read, local-cache reads and no remote reads. Original mode selected one BE; automatic mode selected all three. - Standards and specification reviews of the implementation and final default adjustment found no remaining actionable issues. - Targeted local validation does not claim full TeamCity success on the updated head. No BE source changed, so no new BE build or BE UT run was required for this adjustment. - Behavior changed: - [ ] No. - [x] Yes, when explicitly enabled. Default 1 preserves the existing strategy. Values 0 and N>1 enable random minimum-weight ties and disable global redistribution in their applicable paths; caching can require more copies. - Does this need documentation? - [ ] No. - [x] Yes. apache/doris-website#4199 ### Check List (For Reviewer who merge this PR) - [ ] Confirm the release note - [ ] Confirm test cases - [ ] Confirm document - [ ] Add branch pick label
This branch has not been deployed
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Versions
Languages
Docs Checklist
Summary
Related implementation: apache/doris#68791
Document
external_scan_consistent_hash_spread_numin the existing English and Chinese session-variable reference:1preserves original scheduling; it does not mean a single backend.0enables automatic spreading across eligible compute-group backends.1bound hash candidates when file caching or consistent hashing is enabled.Only the current development documentation is updated because this feature is proposed for master and has not been released or backported. Existing page paths, front matter, sidebar entries and released-version documentation are unchanged.
Validation
scripts/check_md_links_single.py --no-externalpasses for both changed pages.