[UUID 8/8] UUID integration tests, benchmarks and docs

[xiangfu0]

What

End-to-end verification and documentation.

Changes

• UuidTypeTest, UuidTypeRealtimeTest, UuidUpsertRealtimeTest (extend CustomDataQueryClusterIntegrationTest)
• JMH BenchmarkUuidGroupingAndLookup, BenchmarkUuidQueryExecution
• README usage / limitations / migration

Enables

Offline + realtime + upsert integration coverage and performance benchmarks. The top of the stack — its cumulative diff equals the original #18140.

Depends on

#18869, #18871 and #18874 (benchmarks import multi-stage runtime classes).

About this PR / how to review

This is part 8 of 8 splitting #18140 (first-class logical UUID type) into layered PRs, as requested there.

The split is enabled by the v1 design: DataType.UUID has stored type BYTES, so most paths handle it automatically; each PR adds explicit UUID semantics to one subsystem. Head branch lives on xiangfu0/pinot.

This PR is stacked on #18875 (branch uuid-split/07-udfs-partitioning). Because GitHub PRs to apache must base on master, the Files-changed tab is cumulative (it includes layers 1–8) until the PRs below it merge. Review the commit titled [UUID 8/8] UUID integration tests, benchmarks and docs — that is this layer's change. Each parent merge shrinks this diff after a rebase.

Full stack (merge bottom → top)

1. [UUID 1/8] Add logical UUID type foundation (pinot-spi) #18869 — [UUID 1/8] logical UUID type foundation (pinot-spi)
2. [UUID 2/8] UUID ingest and segment storage #18870 — [UUID 2/8] UUID ingest and segment storage
3. [UUID 3/8] UUID result rendering (DataSchema, Arrow/JSON encoders) #18871 — [UUID 3/8] UUID result rendering (DataSchema, Arrow/JSON encoders)
4. [UUID 4/8] UUID server-side predicates, CAST and transforms #18872 — [UUID 4/8] UUID server-side predicates, CAST and transforms
5. [UUID 5/8] UUID aggregation, group-by and distinct #18873 — [UUID 5/8] UUID aggregation, group-by and distinct
6. [UUID 6/8] UUID multi-stage engine (planner + runtime) #18874 — [UUID 6/8] UUID multi-stage engine (planner + runtime)
7. [UUID 7/8] UUID scalar UDFs and partitioning #18875 — [UUID 7/8] UUID scalar UDFs and partitioning
8. [UUID 8/8] UUID integration tests, benchmarks and docs #18876 — [UUID 8/8] UUID integration tests, benchmarks and docs

After #18869 lands, PRs 2/4/7 (#18870, #18872, #18875) only depend on it and can be reviewed in parallel; PRs 5/6 (#18873, #18874) also need #18871; PR 8 (#18876) needs #18874.

Full feature description, v1 design contract, scope exclusions, and benchmark numbers: #18140.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 51.84049% with 628 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.79%. Comparing base (19897c5) to head (ce33dae).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
...ot/common/request/context/RequestContextUtils.java	55.30%	48 Missing and 11 partials ⚠️
...java/org/apache/pinot/common/utils/DataSchema.java	55.55%	36 Missing and 8 partials ⚠️
...ator/transform/function/CastTransformFunction.java	34.92%	40 Missing and 1 partial ⚠️
...sform/function/ScalarTransformFunctionWrapper.java	17.07%	34 Missing ⚠️
...pby/NoDictionarySingleColumnGroupKeyGenerator.java	42.00%	23 Missing and 6 partials ⚠️
.../function/DistinctCountULLAggregationFunction.java	0.00%	26 Missing ⚠️
...perator/query/NonScanBasedAggregationOperator.java	20.00%	22 Missing and 2 partials ⚠️
...ion/DistinctCountCPCSketchAggregationFunction.java	0.00%	24 Missing ⚠️
...upby/NoDictionaryMultiColumnGroupKeyGenerator.java	26.66%	19 Missing and 3 partials ⚠️
...e/operator/groupby/OneUuidKeyGroupIdGenerator.java	0.00%	20 Missing ⚠️
... and 50 more

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #18876      +/-   ##
============================================
- Coverage     64.80%   64.79%   -0.02%     
  Complexity     1347     1347              
============================================
  Files          3392     3413      +21     
  Lines        211769   213632    +1863     
  Branches      33345    33707     +362     
============================================
+ Hits         137232   138414    +1182     
- Misses        63451    63994     +543     
- Partials      11086    11224     +138     

Flag	Coverage Δ
custom-integration1	100.00% <ø> (ø)
integration	100.00% <ø> (ø)
integration1	100.00% <ø> (ø)
integration2	0.00% <ø> (ø)
java-21	64.79% <51.84%> (-0.02%)	⬇️
temurin	64.79% <51.84%> (-0.02%)	⬇️
unittests	64.78% <51.84%> (-0.02%)	⬇️
unittests1	56.73% <41.79%> (-0.22%)	⬇️
unittests2	37.17% <19.09%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[xiangfu0]

Found critical mixed-version compatibility issues inherited in this stack head; see inline comments.

[xiangfu0]

This makes UUID a new broker/server wire-visible ColumnDataType. DataSchema.toBytes() emits the enum name, and older peers still throw in parseColumnDataType(...) once they see UUID, so rolling upgrades and rollback are unsafe as soon as UUID-typed results are in flight. Please keep the wire representation on an existing type until all peers are upgraded, or add an explicit mixed-version compatibility path plus coverage.

[xiangfu0]

This introduces new UUID / UUID_ARRAY proto enum values with no compatibility path for older MSQ peers. Older brokers/servers decode them as UNRECOGNIZED and throw in convertColumnDataType(...), so a UUID literal can break mixed-version planning before execution even starts. Please encode UUID literals using an existing wire type until the cluster is homogeneous, or add version-gated dual-read/dual-write behavior with mixed-version tests.