[FLINK-40580][table] Render a VARIANT object or array as JSON when casting to a character string

[raminqaf]

Description:

What is the purpose of the change

Casting a VARIANT to a character string renders a stored scalar the way a regular SQL cast of that kind would (a boolean becomes TRUE, a timestamp uses the SQL format, a binary value is read as UTF-8). A VARIANT holding an object or an array had no scalar form, so the cast failed and pointed the user at JSON_STRING.

This makes CAST(v AS STRING) render an object or array the way a regular ARRAY or MAP to string cast does, rather than failing: an array as [e1, e2] and an object as {k1=v1, k2=v2}, with each value rendered by the same rules and a nested variant null shown as NULL. Strings are unquoted at every depth, so the result is a SQL rendering and not JSON.

CAST(PARSE_JSON('["a", "b"]')      AS STRING)  -- [a, b]        (was: runtime error)
CAST(PARSE_JSON('{"a": 1}')        AS STRING)  -- {a=1}         (was: runtime error)
CAST(PARSE_JSON('["a", null, 1]')  AS STRING)  -- [a, NULL, 1]
CAST(PARSE_JSON('{"k": ["a","b"]}')AS STRING)  -- {k=[a, b]}
CAST(PARSE_JSON('"foo"')           AS STRING)  -- foo           (unchanged)

The printing path is unchanged and still renders JSON via toJson(), so a VARIANT result column displays as JSON while an explicit CAST AS STRING extracts SQL text. This matches how a scalar string already differs between the two paths. For the JSON form with quoted strings, use JSON_STRING.

Only OBJECT and ARRAY change here. Scalar kinds whose string rendering is still unsupported (TIME and nanosecond timestamps, tracked in FLINK-40492) keep failing.

Brief change log

• VariantCastUtils renders an object/array by walking the variant at runtime (renderValue), reusing the existing scalar rendering per element or field; a variant's structure is dynamic, so the collection-to-string cast rules (which are codegen over a static element type) cannot be reused.
• A bounded CHAR(n)/VARCHAR(n) target trims the rendered string like any other over-length value; TRY_CAST returns the string rather than NULL; a stored JSON null still casts to SQL NULL.
• Updated the cast-support matrix and prose in data-types.md.

Verifying this change

This change added tests and can be verified as follows:

• CastRulesTest: VARIANT → STRING for an object and an array assert the SQL rendering (unquoted strings, nested null as NULL), with the JSON rendering kept for the printing path.
• CastFunctionITCase: CAST/TRY_CAST of an object and an array to STRING, a nested null and a nested container, and a container cast to a bounded VARCHAR(n) that trims the rendered string.

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): no
• The public API, i.e., is any changed class annotated with @Public(Evolving): no
• The serializers: no
• The runtime per-record code paths (performance sensitive): no
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: no
• The S3 file system connector: no

Documentation

• Does this pull request introduce a new feature? yes (a new castable pair for VARIANT)
• If yes, how is the feature documented? docs (cast-support matrix)

---

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: Claude Code (Claude Opus 4.8)

[flinkbot]

CI report:

• d39406a Azure: FAILURE
• aa20b8a Azure: PENDING

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot run azure re-run the last Azure build

[twalthr]

the targetDescription should not be reused across elements. The target needs to be precise per value. same for map key and value.

[raminqaf]

Good catch. Fixed. Nested values now report an unbounded "a character string" target instead of the container's CHAR(n)/VARCHAR(n), since an element is rendered in full and only the whole result is trimmed. Only a top-level scalar keeps its real bounded target. Added regression tests for a byte value nested in both an array element and an object value.

[twalthr]

LGTM, thanks @raminqaf