[SPARK-57718][SQL][TESTS] Add JOIN correctness tests for nanosecond-precision timestamp types

[stevomitric]

What changes were proposed in this pull request?

Tests-only coverage for equi-JOINs over the nanosecond-precision timestamp types TIMESTAMP_NTZ(p) / TIMESTAMP_LTZ(p) (p in [7, 9]). One new suite, TimestampNanosJoinSuiteBase, with AnsiOn / AnsiOff subclasses.

The headline assertion is sub-microsecond join-key correctness: every key in the test relations shares the same epochMicros and differs only in nanosWithinMicro, so a correct join must be driven by the full nanos value —

• a fully-equal key (incl. the sub-microsecond remainder) must join,
• an epochMicros-equal-but-nanosWithinMicro-distinct key must not join,
• NULL keys must not match.

Why are the changes needed?

Joins over the nanosecond types already work (they ride on the hashing / ordering / UnsafeRow primitives), but there was no join coverage — Spark's join suites are organized by join type/strategy, not by column type. This locks the behaviour in, mirroring the MIN/MAX follow-up which was likewise tests-only.

Does this PR introduce any user-facing change?

No, tests only.

How was this patch tested?

New suites in this PR.

Was this patch authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Claude Opus 4.8)

[stevomitric]

cc @MaxGekk can you PTAL at this test-only PR.

[MaxGekk]

0 blocking, 0 non-blocking, 0 nits.
A well-constructed, correct test-only PR. The asserted values are the intended sub-microsecond join semantics, the fixtures genuinely exercise sub-micro key equality/non-equality across all three join strategies and both codegen modes, suite placement and base-class choice are right, and parity with the existing nanos suites (TimestampNanosFunctionsSuiteBase / TimestampNanosWideningSuiteBase) is faithful.

Verification

I checked the asserted values are intended, not incidental, and that the tests can actually observe a precision bug (no SPARK-56395-style trap):

• The right relation is neither empty nor key-equal to the left — its 700ns/300ns keys share the same epochMicros as the left's 200ns/900ns. A truncate-to-micros bug would spuriously match every non-null left row to every non-null right row, blowing up INNER and turning the lid=2/lid=3 left-outer NULLs into matches — so the suite fails loudly on such a bug. lid=2 -> null proves a real sub-micro non-match (not an empty right side); lid=4 -> null proves NULL != NULL.
• The cross-precision-safety claim holds: SparkDateTimeUtils.truncateNanosWithinMicroToPrecision floors to (n/100)*100 at p=7 and (n/10)*10 at p=8, and the remainders 200/300/500/700/900 are all multiples of 100, so they are exact and non-colliding at every p in [7,9] — the same fixtures and expected rows are valid verbatim at all three precisions.
• Strategy forcing is sound: forceApplyShuffledHashJoin short-circuits the SHJ build-side selection (bypassing the muchSmaller heuristic that equal-sized tiny inputs would fail), SHJ permits LEFT OUTER, and with AQE disabled assertJoinUsed("exactly one") is deterministic.

The formal verdict stays with the committer.

[MaxGekk]

All tests passed.

+1, LGTM. Merging to master/4.x.
Thank you, @stevomitric.