raminqaf commented on code in PR #29369:
URL: https://github.com/apache/flink/pull/29369#discussion_r4184380862
##########
docs/content/docs/sql/reference/data-types.md:
##########
@@ -1725,7 +1725,38 @@ CAST(NULL AS VARIANT) -- NULL
CAST(CAST('NaN' AS DOUBLE) AS VARIANT) -- NaN, stored as a DOUBLE
CAST(INTERVAL '2' DAY AS VARIANT) -- fails at validation
CAST(ARRAY[1, NULL] AS ARRAY<VARIANT>) -- [1, NULL], each element a
VARIANT, the NULL stays SQL NULL
-CAST(ARRAY[1, 2] AS VARIANT) -- fails at validation, not
supported yet
+```
+
+A whole `ARRAY`, `MAP`, `ROW`, or `STRUCTURED` value can also be cast into a
single `VARIANT`. An
+`ARRAY` becomes a variant array, and a `MAP`, `ROW`, or `STRUCTURED` value a
variant object. Each
+leaf is stored by the rules above, so the cast is supported only when every
leaf type casts to
+`VARIANT`.
+
+- A `ROW` or `STRUCTURED` value is keyed by its field names. The SQL `ROW`
constructor names its
+ fields `EXPR$0`, `EXPR$1`, and so on, and the Table API `row()` names them
`f0`, `f1`, and so on.
+ To choose the keys, cast to a `ROW` with named fields first, or name each
field with `as()` in the
+ Table API.
+- A `MAP` needs a character string key, which becomes the object key. A `NULL`
key fails the cast.
+ If a key appears twice, the last value is kept.
+- A variant object sorts its keys, so the field order of a `ROW` is not kept.
+- A `NULL` element, field, or map value becomes a variant null, so an array
keeps its length and an
+ object keeps its keys.
+- A nested `VARIANT` is embedded as is.
+- The whole value must fit into the 16 MiB of a `VARIANT`. Any `ARRAY` or
`MAP` can exceed it, and so
+ can a `ROW` with a nested `VARIANT` or with fields whose declared sizes add
up to more. The cast
+ then fails, and `TRY_CAST` returns `NULL` for the whole value.
+- Casting the `VARIANT` back to the original type returns the original value,
since a cast to `ROW`
Review Comment:
Added both exceptions, and the sentence that contrasts `ARRAY<INT>` to
`ARRAY<VARIANT>` with `ARRAY<INT>` to `VARIANT`. I also documented that the
order of `MAP` entries is part of the encoding. Two MAPs with the same entries
in a different order cast to VARIANT values that are not equal, the same as
`PARSE_JSON` does for the key order of JSON text.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
