Add UUID scalar functions and multi-stage UDF wrappers

[xiangfu0]

Parent tracking issue: #16619

What

Adds UUID scalar functions and their multi-stage UDF wrappers, including a shared polymorphic input contract for UUID semantic operations.

Changes

• IS_UUID, TO_UUID, UUID_TO_STRING, UUID_TO_BYTES, UUID_VERSION, and UUID_TIMESTAMP accept STRING, BYTES, or logical UUID
• UUID_TO_STRING always returns canonical lowercase dashed UUID text for all three input representations
• BYTES_TO_UUID remains a strict BYTES conversion function
• UUID_V4 / UUID_V7 generators remain zero-argument and non-deterministic, preventing compile-time folding
• UUID Java/Pinot/Calcite type bridges and byte-backed single-stage UUID dispatch are included so this PR is standalone
• Multi-stage planner/protobuf bridges preserve logical UUID and UUID_ARRAY types
• Matching custom Udf wrappers expose the polymorphic contract to the multi-stage registry
• Nulls are propagated by the engine; IS_UUID returns false only for non-null invalid inputs
• The UDF example harness now supports UUID schemas, canonical wire-value comparison, and generated snapshots for all UUID UDFs

Function	STRING	BYTES	UUID
IS_UUID	yes	yes	yes
TO_UUID	yes	yes	yes
UUID_TO_STRING	yes	yes	yes
UUID_TO_BYTES	yes	yes	yes
UUID_VERSION	yes	yes	yes
UUID_TIMESTAMP	yes	yes	yes

Generic BYTES rendering is unchanged and remains hexadecimal. Canonical UUID decoding occurs only inside UUID-aware functions.

How to reproduce the fixed behavior

Before the UUID type bridge and wrapper dispatch were included, direct unit calls could pass while ingestion, single-stage, or multi-stage evaluation failed to resolve or render byte-backed logical UUID values correctly.

The following expressions now plan and execute through the polymorphic contract:

SELECT
  UUID_TO_STRING('550E8400-E29B-41D4-A716-446655440000'),
  UUID_TO_STRING(UUID_TO_BYTES('550e8400-e29b-41d4-a716-446655440000')),
  UUID_TO_STRING(TO_UUID('550e8400-e29b-41d4-a716-446655440000'));

All three results are:

550e8400-e29b-41d4-a716-446655440000

Why this is a standalone PR

Split out of #18875 ([UUID 7/8]) so the scalar function surface can be reviewed independently from UUID partitioning.

This branch is based directly on master. It contains the UUID scalar plumbing required by these functions, rather than relying on unmerged UUID branches. The remaining #18875 scope is UuidPartitionFunction, PartitionerFactory / TableConfigPartitioner wiring, and UUID_ARRAY support in array scalar functions.

Testing

• UuidUtilsTest, UuidConversionFunctionsTest, and ScalarTransformFunctionWrapperTest: canonical rendering, all input types, byte-backed dispatch, invalid inputs, timestamps/versions, and null propagation
• QueryCompilationTest, both plan-node converter tests, and RexExpressionSerDeTest: polymorphic type inference plus UUID/UUID_ARRAY planner and protobuf round trips
• UuidUdfTest and PinotFunctionEnvGeneratorTest: wrapper metadata/examples and UUID schema generation
• Generated UDF integration snapshots for all nine UUID functions; no unsupported UUID type or wire-value mismatches
• 133 focused UUID/scalar/UDF tests passed
• 259 focused planner/serde/query compilation tests passed
• Full 63-module test-compile reactor passed with JDK 25 and -Xlint:all
• Required Spotless, Checkstyle, license-format, and license-check gates passed for all affected modules

Full feature description and design contract: #18140.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.49123% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.62%. Comparing base (779210b) to head (8474f67).

Files with missing lines	Patch %	Lines
...unction/scalar/uuid/AbstractUuidInputFunction.java	78.78%	4 Missing and 3 partials ⚠️
...rg/apache/pinot/common/function/FunctionUtils.java	66.66%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master   #19091      +/-   ##
============================================
+ Coverage     65.53%   65.62%   +0.09%     
  Complexity     1423     1423              
============================================
  Files          3432     3450      +18     
  Lines        218151   218378     +227     
  Branches      34664    34670       +6     
============================================
+ Hits         142964   143318     +354     
+ Misses        63627    63498     -129     
- Partials      11560    11562       +2     

Flag	Coverage Δ
custom-integration1	100.00% <ø> (ø)
integration	100.00% <ø> (ø)
integration1	100.00% <ø> (ø)
integration2	?
java-25	65.62% <96.49%> (+0.09%)	⬆️
temurin	65.62% <96.49%> (+0.09%)	⬆️
unittests	65.62% <96.49%> (+0.09%)	⬆️
unittests1	57.03% <96.49%> (+0.13%)	⬆️
unittests2	37.91% <18.85%> (+<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.

[Copilot]

Pull request overview

Adds UUID-focused scalar functions to pinot-common and registers corresponding multi-stage UDF wrappers in pinot-query-runtime, enabling UUID validation, conversion, accessors, and v4/v7 generation through Pinot’s function/UDF surfaces.

Changes:

• Introduces polymorphic IS_UUID / TO_UUID scalar functions (STRING or BYTES) via a shared dispatch base class.
• Adds UUID conversion/accessor/generator scalar functions (UUID_TO_BYTES, BYTES_TO_UUID, UUID_TO_STRING, UUID_VERSION, UUID_TIMESTAMP, UUID_V4, UUID_V7).
• Adds multi-stage UDF wrapper classes and unit tests covering conversions, null handling, and v4/v7 properties.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/BytesToUuidUdf.java	Multi-stage UDF wrapper for BYTES_TO_UUID.
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/IsUuidUdf.java	Multi-stage UDF wrapper for IS_UUID, including example signatures.
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/ToUuidUdf.java	Multi-stage UDF wrapper for TO_UUID.
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/UuidTimestampUdf.java	Multi-stage UDF wrapper for UUID_TIMESTAMP.
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/UuidToBytesUdf.java	Multi-stage UDF wrapper for UUID_TO_BYTES.
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/UuidToStringUdf.java	Multi-stage UDF wrapper for UUID_TO_STRING.
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/UuidV4Udf.java	Multi-stage UDF wrapper for UUID_V4.
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/UuidV7Udf.java	Multi-stage UDF wrapper for UUID_V7.
pinot-query-runtime/src/main/java/org/apache/pinot/query/runtime/function/UuidVersionUdf.java	Multi-stage UDF wrapper for UUID_VERSION.
pinot-common/src/main/java/org/apache/pinot/common/function/scalar/uuid/AbstractStringOrBytesUuidFunction.java	Shared dispatch helper for STRING/BYTES UUID scalar functions.
pinot-common/src/main/java/org/apache/pinot/common/function/scalar/uuid/IsUuidScalarFunction.java	Implements polymorphic IS_UUID.
pinot-common/src/main/java/org/apache/pinot/common/function/scalar/uuid/ToUuidScalarFunction.java	Implements polymorphic TO_UUID with Calcite UUID return typing.
pinot-common/src/main/java/org/apache/pinot/common/function/scalar/uuid/UuidConversionFunctions.java	Adds UUID conversion/accessor/generator scalar functions (incl. non-deterministic v4/v7).
pinot-common/src/test/java/org/apache/pinot/common/function/scalar/StringFunctionsTest.java	Adds mixed-case UUID round-trip coverage via toUUIDBytes/fromUUIDBytes.
pinot-common/src/test/java/org/apache/pinot/common/function/scalar/uuid/UuidConversionFunctionsTest.java	New unit tests for conversions, accessors, generators, and null handling.

Comments suppressed due to low confidence (1)

pinot-common/src/main/java/org/apache/pinot/common/function/scalar/uuid/IsUuidScalarFunction.java:50

• Same null-handling issue as the STRING overload: marking the BYTES overload as nullableParameters=true forces evaluation on null inputs and returns false instead of propagating null. This also diverges from the IsUuidUdf examples which expect null when null handling is enabled.

      BYTES_FUNCTION_INFO =
          new FunctionInfo(IsUuidScalarFunction.class.getMethod("isUuid", byte[].class), IsUuidScalarFunction.class,
              true);

[xiangfu0]

Now disjoint from #18875

#18875 has been updated to drop these files, so the two PRs no longer overlap and can be reviewed and merged in either order:

• Add UUID scalar functions and multi-stage UDF wrappers #19091 (this PR) — UUID scalar functions + multi-stage UDF wrappers. Based on master, 15 files.
• [UUID 7/8] UUID partitioning #18875 — UUID partitioning (UuidPartitionFunction, PartitionerFactory / TableConfigPartitioner wiring, UUID_ARRAY array-function entries), retitled [UUID 7/8] UUID partitioning.

Doc comments here were also converted to /// markdown Javadoc to match the surrounding UUID code (UuidPartitionFunction, TableConfigPartitioner, DataSchema).

Re-verified on the current master base: pinot-query-runtime -am test-compile succeeds, UuidConversionFunctionsTest + StringFunctionsTest pass 191/191, and spotless / checkstyle / license are clean.

[xiangfu0]

Documentation follow-up: pinot-contrib/pinot-docs#952