[SPARK-57285][SQL] Route nanosecond timestamp cast-to-string through the Types Framework

[MaxGekk]

What changes were proposed in this pull request?

This PR makes the Types Framework (TypeApiOps) the single integration point for nanosecond timestamp CAST(... AS STRING), for both the interpreted and codegen paths.

Specifically:

• TypeApiOps.apply gains a by-name zoneId parameter that defaults to the session-local time zone config (SqlApiConf.get.sessionLocalTimeZone) and is threaded into the TIMESTAMP_LTZ nanos ops. It is by-name so the zone is forced only when the LTZ ops is actually constructed: zone-independent (TimeType, TIMESTAMP_NTZ nanos) and unsupported types never evaluate it, which matters because a CAST's zone is unresolved (None.get) until a time zone is assigned.
• TimestampLTZNanosTypeApiOps now carries its ZoneId as a required constructor parameter and holds the fraction formatter in a @transient private lazy val, so the formatter is built once per ops instance (once per cast, per task) rather than per row. TimestampNTZNanosTypeApiOps stays zone-independent (UTC).
• ToStringBase no longer bypasses or special-cases the framework: both the interpreted and codegen paths dispatch uniformly through TypeApiOps(from, zoneId). CAST passes its resolved zone; zone-less callers (EXPLAIN, SQL-literal toSQLValue, Row.jsonValue) accept the session-zone default.
• The now-unused UNSUPPORTED_FEATURE.TIMESTAMP_NANOS_TO_STRING error condition and its DataTypeErrors helper are removed.

The microsecond timestamp types (TIMESTAMP / TIMESTAMP_NTZ) remain handled inline in ToStringBase and are out of scope.

Why are the changes needed?

SPARK-57256 implemented nanosecond cast-to-string inline in ToStringBase, deliberately bypassing the framework because the zone-less TypeApiOps.format(v) cannot render LTZ in the session time zone. That left nanos cast-to-string as a one-off integration outside the framework, inconsistent with the SPIP direction (SPARK-56822) of wiring the new types through the centralized TypeOps / TypeApiOps. This PR closes that gap.

Does this PR introduce any user-facing change?

Yes. Previously, rendering a TIMESTAMP_LTZ nanosecond value to string without an explicit time zone (EXPLAIN of a literal, SQL-literal toSQLValue, Row.jsonValue) raised UNSUPPORTED_FEATURE.TIMESTAMP_NANOS_TO_STRING. Now these callers render the value in the session-local time zone (spark.sql.session.timeZone), consistent with how CAST(... AS STRING) already rendered LTZ nanos. The UNSUPPORTED_FEATURE.TIMESTAMP_NANOS_TO_STRING error condition is removed. The CAST(... AS STRING) output itself is unchanged.

How was this patch tested?

• Updated TimestampNanosTypeOpsSuite to cover the new behavior: NTZ renders zone-independently, LTZ renders in the zone carried by the ops instance, and zone-less LTZ now renders in the session-local time zone (instead of raising), exercising precision flooring.
• Existing CastWithAnsiOnSuite, CastWithAnsiOffSuite, ToPrettyStringSuite, and TimestampNanosRowSuite stay green (275 tests pass), and SparkThrowableSuite (33 tests) confirms the removed error condition leaves the error framework consistent.

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

Generated-by: Cursor (Claude Opus 4.8)

[MaxGekk]

@davidm-db @dejankrak-db @stevomitric Could you review this PR, please.

[stevomitric]

This builds a fresh formatter per row, while NTZ caches its own. The zoneId is constant across a cast - could we cache it here the same way NTZ does rather than new-ing one each call?

[MaxGekk]

Good catch, fixed. TimestampLTZNanosTypeApiOps now takes the ZoneId as a constructor parameter and holds the fraction formatter in a @transient private lazy val, exactly like NTZ, so it is built once per ops instance (once per cast, per task) rather than per row. The zone is threaded in centrally via TypeApiOps.apply(dt, zoneId) (by-name, defaulting to the session-local time zone), and CAST passes its resolved zone. Done in cb0a03d.

[stevomitric]

LGTM. Thanks @MaxGekk for resolving comments.

[MaxGekk]

@uros-b @cloud-fan Could you review this PR, please.

[uros-db]

In the new codegen path and the interpreted path falls through to castToStringDefault, whose nanos cases were deleted, so it now lands on the generic terminal case: case _ => o => UTF8String.fromString(o.toString). TypeApiOps(...) returns None whenever typesFrameworkEnabled == false. The intended invariant ("nanos types imply the framework is on") is only enforced at set-time, and only on one flag:

      .checkValue(
        enabled => !enabled || SQLConf.get.typesFrameworkEnabled,
        "REQUIREMENT",
        _ => Map("confRequirement" ->
          (s"'${TYPES_FRAMEWORK_ENABLED.key}' must be true to enable the nanosecond " +
            "timestamp types.")))

TYPES_FRAMEWORK_ENABLED has no symmetric guard, so a session can set timestampNanosTypes.enabled=true, materialize nanos values, then set types.framework.enabled=false. In that (admittedly unusual, internal-flag) state, casting a nanos value to string would:

• interpreted: silently produce TimestampNanosVal.toString (wrong output) instead of a formatted timestamp;
• codegen: throw NoSuchElementException from .get.