[docs](session-variables) Document opt-in external split spreading - #4199

#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