raminqaf commented on code in PR #28758:
URL: https://github.com/apache/flink/pull/28758#discussion_r3594523534
##########
docs/content/docs/sql/reference/data-types.md:
##########
@@ -1523,11 +1523,47 @@ without requiring upfront schema definition. For
example, if a new field is adde
can be directly incorporated into the `VARIANT` data without modifying the
table schema. This is
particularly useful in dynamic environments where schemas may evolve over time.
+A `VARIANT` stores a single value of one of the following kinds: `NULL`,
`BOOLEAN`, `TINYINT`,
+`SMALLINT`, `INT`, `BIGINT`, `FLOAT`, `DOUBLE`, `DECIMAL` (up to precision
38), `STRING`, `DATE`,
+`TIMESTAMP`, `TIMESTAMP_LTZ`, `BYTES`, or a nested array or object.
`TIMESTAMP` and `TIMESTAMP_LTZ`
+are stored with microsecond precision and `DATE` as a day count. There is no
`TIME` kind.
+
+The `PARSE_JSON` function produces only the kinds that JSON syntax can express:
+
+| JSON input | Stored `VARIANT` kind
|
+|-----------------------------------------------------|-------------------------------------------------|
+| `null` | `NULL`
|
+| `true` / `false` | `BOOLEAN`
|
+| Integer within the 64-bit signed range | smallest of
`TINYINT`/`SMALLINT`/`INT`/`BIGINT` |
+| Integer beyond 64-bit, up to 38 significant digits | `DECIMAL`
|
+| Decimal in plain notation, up to precision/scale 38 | `DECIMAL`
|
+| Number in scientific notation, e.g. `1.5e3` | `DOUBLE`
|
+| Number exceeding 38 digits of precision or scale | `DOUBLE`
|
+| String | `STRING`
|
+| Array | array (elements
encoded by the same rules) |
+| Object | object (values encoded
by the same rules) |
+
+Because JSON has no literal for float, date, timestamp, or binary values,
`PARSE_JSON` never
+produces `FLOAT`, `DATE`, `TIMESTAMP`, `TIMESTAMP_LTZ`, or `BYTES`. A
`VARIANT` can still hold
+those kinds when built by other producers, such as the programmatic
`VariantBuilder` API or format
+conversions like Avro.
+
A primitive-valued `VARIANT` can be converted to a scalar type with `CAST` or
`TRY_CAST`. Numeric
-targets are lenient: a variant holding any numeric value casts to any numeric
type, so a JSON integer
-such as `PARSE_JSON('42')` casts to `INT` or `BIGINT`. Other targets require
the stored value to be of
-the matching kind. When the value cannot be converted, `CAST` fails the job
and `TRY_CAST` returns
-`NULL`. Use the `JSON_STRING` function to obtain the JSON string
representation of a `VARIANT`.
+targets accept any numeric value, so `PARSE_JSON('42')` casts to `INT`,
`BIGINT`, or `DOUBLE`. A value
+outside an integer or `DECIMAL` target's range fails `CAST` and returns `NULL`
for `TRY_CAST`. Other
+targets require the stored value to be of the matching kind, and a mismatch is
handled the same way.
+Casting to `CHAR`/`VARCHAR` (or calling `JSON_STRING`) returns the JSON string
representation. Casting
Review Comment:
@twalthr I want to emphasize on this statement. A `CAST(v.a AS STRING`) is
the same `VARIANT → STRING` cast. A `v.a` (variant field access) returns
another `VARIANT`.
--
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]
