This is an automated email from the ASF dual-hosted git repository.
yiguolei pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 78e606cb751 [docs](variant) document VARIANT behavior in Doris 4.2+
(#4001)
78e606cb751 is described below
commit 78e606cb7511b53f8e6b92b57b5f600806f668e2
Author: lihangyu <[email protected]>
AuthorDate: Sun Jul 26 09:12:03 2026 +0800
[docs](variant) document VARIANT behavior in Doris 4.2+ (#4001)
## What changed
- Merge the Doris 4.2+ compute behavior into the main English and
Chinese VARIANT reference instead of exposing a separate V2 document or
V2 session switch.
- Document JSON/JSONB input for PARSE_TO_VARIANT and rename the nullable
parser documentation to TRY_PARSE_TO_VARIANT.
- Add complete CAST guidance in both directions, using explicit source
and target whitelists. String-to-VARIANT CAST preserves a string root
and does not parse JSON; JSON/JSONB conversion is structural and reports
unsupported value types from the BE.
- State that unsupported CAST sources and targets, including MAP and
STRUCT, return a BE error, while ARRAY conversion recurses only through
supported element types.
- Document logical equality and canonical hash semantics, including
GROUP BY, DISTINCT, set operations, JOIN restrictions, ORDER BY
restrictions, window keys, COUNT, MIN/MAX, nested expressions, and
explode behavior.
- Align ELEMENT_AT documentation with Doris 4.2+ VARIANT array indexing
and update the Variant Functions sidebar.
## Why
The documentation should describe user-visible VARIANT capabilities by
Doris version, not expose the internal ColumnVariantV2 implementation.
The follow-up review also finalized the public parser name and clarified
CAST parsing, type whitelists, and JSON/JSONB error behavior.
## Validation
- git diff --check: passed.
- corepack yarn docs:sql-functions:changed: passed with no findings.
- corepack yarn docs:features:changed: passed with no findings.
- corepack yarn docs:links:changed: passed with no errors.
Redirect-review warnings are intentional because the removed and renamed
pages were introduced only by this unmerged PR.
- corepack yarn docs:i18n-sync:changed: passed. Current-to-versioned
warnings are an intentional version exception because these behaviors
start in Doris 4.2 and should not be copied into existing released
4.x/3.x docs.
- corepack yarn docs:seo:changed: passed; only existing cross-version
and cross-locale duplicate-title warnings remain.
- corepack yarn typecheck: repository baseline still fails on unrelated
existing TypeScript errors outside the changed docs and sidebars.
---
.../sql-data-types/semi-structured/VARIANT.md | 215 ++++++++++++++++++---
.../variant-functions/element-at.md | 39 ++--
.../variant-functions/parse-to-variant.md | 113 +++++++++++
.../variant-functions/try-parse-to-variant.md | 90 +++++++++
.../sql-data-types/semi-structured/VARIANT.md | 213 +++++++++++++++++---
.../variant-functions/element-at.md | 43 +++--
.../variant-functions/parse-to-variant.md | 113 +++++++++++
.../variant-functions/try-parse-to-variant.md | 90 +++++++++
sidebars.ts | 2 +
9 files changed, 834 insertions(+), 84 deletions(-)
diff --git
a/docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 227fa747696..05f298de410 100644
--- a/docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++ b/docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -2,7 +2,7 @@
{
"title": "VARIANT",
"language": "en-US",
- "description": "The VARIANT type stores semi-structured JSON data. It can
contain different primitive types (integers, strings, booleans, etc.),
one-dimensional arrays, and nested objects. On write, Doris infers the
structure and type of sub-paths based on JSON paths and performs
Subcolumnization on frequent paths, exposing them as independent columnar
subcolumns for both flexibility and performance."
+ "description": "VARIANT stores semi-structured JSON data and supports
typed access, casts, hash-based grouping, deduplication, and selected SQL
operations."
}
---
@@ -67,6 +67,170 @@ FROM ${table_name}
WHERE ARRAY_CONTAINS(CAST(v['tags'] AS ARRAY<TEXT>), 'Doris');
```
+## Create and access values
+
+:::info Version availability
+The behavior in this section applies to Doris 4.2 and later.
+:::
+
+VARIANT values can be created from JSON text, JSON/JSONB values, or typed SQL
expressions:
+
+- Use
[PARSE_TO_VARIANT](../../../sql-functions/scalar-functions/variant-functions/parse-to-variant)
when a string or JSON/JSONB expression should be parsed as a structured
VARIANT value.
+- Use `CAST(expression AS VARIANT)` to convert a supported SQL value to
VARIANT. A string remains a VARIANT string value; this CAST does not parse JSON.
+
+### Parse JSON text
+
+```sql
+SELECT PARSE_TO_VARIANT('{"user": {"id": 42}, "active": true}');
+SELECT PARSE_TO_VARIANT('[10, 20, 30]');
+SELECT PARSE_TO_VARIANT(CAST('{"user": {"id": 42}}' AS JSON));
+```
+
+Use
[TRY_PARSE_TO_VARIANT](../../../sql-functions/scalar-functions/variant-functions/try-parse-to-variant)
when invalid JSON should return SQL `NULL` instead of failing the query.
+
+### Access objects and arrays
+
+Object fields can be accessed with a string key. In Doris 4.2 and later,
positive VARIANT array indexes start from 1, and negative indexes count
backward from the end. The extracted value remains `VARIANT`; CAST it before
typed comparison, arithmetic, or aggregation.
+
+```sql
+SELECT CAST(PARSE_TO_VARIANT('{"user": {"id": 42}}')['user']['id'] AS BIGINT);
+SELECT ELEMENT_AT(PARSE_TO_VARIANT('[10, 20, 30]'), 1); -- 10
+SELECT ELEMENT_AT(PARSE_TO_VARIANT('[10, 20, 30]'), -1); -- 30
+```
+
+See
[ELEMENT_AT](../../../sql-functions/scalar-functions/variant-functions/element-at)
for object and array access details.
+
+## CAST rules
+
+CAST involving VARIANT has two directions: converting a supported SQL value to
VARIANT and extracting a compatible SQL value from VARIANT.
+
+### CAST other types to VARIANT
+
+| Source type | Behavior |
+| --- | --- |
+| `CHAR`, `VARCHAR`, `STRING` | Preserves the input as a VARIANT string.
JSON-looking text is not parsed. |
+| `BOOLEAN` | Preserves the Boolean value. |
+| `TINYINT`, `SMALLINT`, `INT`, `BIGINT`, `LARGEINT` | Preserves the integer
value. |
+| `FLOAT`, `DOUBLE` | Preserves the floating-point value. |
+| `DECIMALV2`, `DECIMAL(p, s)` with `p <= 38` | Preserves the Decimal value,
subject to the limits below. |
+| `DATE`, `DATETIME`, `TIMESTAMPTZ` | Preserves the typed logical value. |
+| `IPV4`, `IPV6` | Preserves the IP address value. |
+| `JSON` / `JSONB` | Converts the structured value directly to VARIANT. If the
input contains a JSONB value type that VARIANT cannot represent, the BE returns
an error. |
+| `ARRAY<T>` | Converts each element recursively when `T` is `VARIANT` or is
also in this whitelist, and preserves SQL NULL elements. |
+
+Only the source types listed above are supported. Other source types,
including `MAP`, `STRUCT`, `TIME`, Decimal values with precision greater than
38, and arrays containing an unsupported element type, cause the BE to return
an error.
+
+```sql
+-- A string remains a VARIANT string root, even if it looks like JSON.
+SELECT CAST(CAST('{"id": 1}' AS VARIANT) AS STRING) AS string_value,
+ VARIANT_TYPE(CAST('{"id": 1}' AS VARIANT)) AS root_type;
+-- string_value: {"id": 1}; root_type: string
+
+-- Parse JSON text explicitly when a structured VARIANT value is required.
+SELECT PARSE_TO_VARIANT('{"id": 1}') AS parsed_object;
+-- {"id":1}
+
+-- JSON/JSONB input is converted structurally.
+SELECT CAST(CAST('{"id": 1}' AS JSON) AS VARIANT) AS parsed_object;
+-- {"id":1}
+```
+
+Because string CAST does not parse JSON, malformed JSON text is still a valid
VARIANT string. Use `PARSE_TO_VARIANT` for strict JSON parsing or
`TRY_PARSE_TO_VARIANT` when malformed input should become SQL `NULL`.
+
+### CAST VARIANT to other types
+
+VARIANT can be cast to a compatible scalar, JSON/JSONB, or array target:
+
+| Target type | Behavior |
+| --- | --- |
+| `BOOLEAN` | Converts a compatible Boolean or scalar root. |
+| `TINYINT`, `SMALLINT`, `INT`, `BIGINT`, `LARGEINT` | Converts a compatible
scalar root to the requested integer type. |
+| `FLOAT`, `DOUBLE` | Converts a compatible numeric root. |
+| `DECIMALV2`, `DECIMAL(p, s)` | Converts a compatible numeric root to the
requested Decimal type. |
+| `DATE`, `DATETIME`, `TIMESTAMPTZ` | Converts a compatible date/time root. |
+| `CHAR`, `VARCHAR`, `STRING` | Returns scalar text for scalar roots and JSON
text for objects and arrays. Variant/JSON `null` becomes the string `null`;
outer SQL `NULL` remains SQL `NULL`. |
+| `IPV4`, `IPV6` | Converts a compatible IP address root to the requested IP
address type. |
+| `JSON` / `JSONB` | Converts the value structurally. If the VARIANT value
contains a type that JSON/JSONB cannot represent, the BE returns an error. |
+| `ARRAY<T>` | Converts a VARIANT array element by element when `T` is
`VARIANT` or is also in this whitelist; incompatible elements follow the target
CAST rules. |
+
+Only the target types listed above are supported. Other target types,
including `MAP`, `STRUCT`, and `TIME`, cause the BE to return an error. For a
supported target, an incompatible value shape, invalid text, or numeric
overflow follows the applicable CAST error-or-NULL behavior.
+
+```sql
+SELECT CAST(PARSE_TO_VARIANT('42') AS BIGINT) AS id;
+-- 42
+
+SELECT CAST(PARSE_TO_VARIANT('[1, null, 3]') AS ARRAY<INT>) AS values;
+-- [1, NULL, 3]
+
+SELECT CAST(PARSE_TO_VARIANT('{"id": 1}') AS JSON) AS json_value;
+-- {"id":1}
+```
+
+### Decimal and date/time conversion limits
+
+| Doris input type | Supported VARIANT behavior |
+| --- | --- |
+| Legacy `DECIMALV2` | Precision up to 27 and scale up to 9 are preserved
exactly. |
+| `DECIMAL(p, s)` | `1 <= p <= 38` and `0 <= s <= p` are preserved exactly.
Values that require precision greater than 38 are not supported. |
+| `DATE` | Preserved as a calendar date with no time or time zone. |
+| Legacy `DATETIME` | Preserved with whole-second precision and no time-zone
adjustment. |
+| `DATETIME(p)` | Supports `0 <= p <= 6` with no time-zone adjustment. |
+| `TIMESTAMPTZ(p)` | Supports `0 <= p <= 6` with time-zone-adjusted timestamp
semantics. |
+| Decimal precision greater than 38 | Not supported as input to VARIANT. |
+| `TIME` | Not supported as input to VARIANT. |
+
+Every source value must also be valid for its Doris source type. Unsupported
precision, invalid dates, or incompatible values return an error instead of
being repaired.
+
+## Grouping, deduplication, and hash semantics
+
+In Doris 4.2 and later, grouping, deduplication, and set operations treat
logically equivalent VARIANT values as the same value, regardless of source SQL
type or physical representation:
+
+- Equivalent integral numeric representations are treated as the same value.
+- Decimal trailing zeros do not change the value, so `1.20` and `1.2` are
treated as the same value.
+- `+0`, `-0`, and integral zero are treated as the same value.
+- Object key order does not affect whether values are treated as the same,
while array element order does.
+- Variant/JSON `null` is distinct from SQL `NULL`.
+
+Hash-based operators use the same logical-value rules when calculating their
keys. Values treated as the same under the rules above therefore produce the
same internal hash key, regardless of whether they came from parsed JSON or a
typed CAST. This hash is an implementation detail, not a stable user-facing
checksum.
+
+These rules apply to supported operations such as `GROUP BY`, `DISTINCT`,
`COUNT(DISTINCT ...)`, `INTERSECT`, `EXCEPT`, and `UNION DISTINCT`. They do not
enable root VARIANT comparison predicates: direct `VARIANT = VARIANT` and
ordering comparisons remain unsupported.
+
+```sql
+-- 1 and 1.0 have one distinct logical value.
+SELECT COUNT(DISTINCT value) AS distinct_count
+FROM (
+ SELECT PARSE_TO_VARIANT('1') AS value
+ UNION ALL
+ SELECT PARSE_TO_VARIANT('1.0') AS value
+) AS numeric_values;
+-- distinct_count: 1
+
+-- Object key order is ignored; array order is preserved.
+SELECT COUNT(DISTINCT value) AS distinct_count
+FROM (
+ SELECT PARSE_TO_VARIANT('{"a": 1, "b": 2}') AS value
+ UNION ALL
+ SELECT PARSE_TO_VARIANT('{"b": 2, "a": 1}') AS value
+) AS object_values;
+-- distinct_count: 1
+
+SELECT COUNT(DISTINCT value) AS distinct_count
+FROM (
+ SELECT PARSE_TO_VARIANT('[1, 2]') AS value
+ UNION ALL
+ SELECT PARSE_TO_VARIANT('[2, 1]') AS value
+) AS array_values;
+-- distinct_count: 2
+```
+
+## NULL semantics
+
+SQL `NULL` and Variant/JSON `null` are different values:
+
+- SQL `NULL` represents the absence of a SQL value and follows normal SQL NULL
propagation.
+- Variant/JSON `null` is a VARIANT value, for example the result of
`PARSE_TO_VARIANT('null')`.
+- `TRY_PARSE_TO_VARIANT` returns SQL `NULL` for malformed input. This differs
from successfully parsing the JSON literal `null`.
+
## Primitive types
VARIANT infers subcolumn types automatically. Supported types include:
@@ -171,11 +335,12 @@ SELECT * FROM test_var_schema;
+------+-----------------------------+
```
-Schema only guides the persisted storage type. During query execution, the
effective type depends on actual data at runtime:
+Schema only guides the persisted storage type. Query expressions that are not
written to a table still keep their actual runtime types:
```sql
--- At runtime v['a'] may still be STRING
-SELECT variant_type(CAST('{"a" : "12345"}' AS VARIANT<'a' : INT>)['a']);
+-- The quoted JSON member is a STRING. PARSE_TO_VARIANT is used because
+-- CAST(string AS VARIANT) always preserves the whole input as a string.
+SELECT variant_type(PARSE_TO_VARIANT('{"a" : "12345"}')['a']);
```
Wildcard matching and order:
@@ -387,10 +552,26 @@ SELECT v FROM variant_tbl WHERE k = 2;
Sorting applies at every level — top-level keys become `a`, `b`, `c`, and the
nested object's keys become `x`, `y`.
-## Supported operations and CAST rules
+## Supported operations
+
+In Doris 4.2 and later, whole VARIANT values support hash-based grouping and
deduplication, but they do not support comparison, join-key, or ordering
semantics.
-- VARIANT cannot be compared/operated directly with other types; comparisons
between two VARIANTs are not supported either.
-- For comparison, filtering, aggregation, and ordering, CAST subpaths to
concrete types (explicitly or implicitly).
+| Operation on a whole VARIANT value | Support | Notes |
+| --- | --- | --- |
+| `GROUP BY` | Supported | Uses the grouping and hash rules described above. |
+| `DISTINCT`, `COUNT(DISTINCT ...)` | Supported | Logically equivalent values
are deduplicated. |
+| `INTERSECT`, `EXCEPT`, `UNION DISTINCT` | Supported | Uses the same rules
described above. |
+| `COUNT(*)`, `COUNT(variant)` | Supported | `COUNT(variant)` excludes outer
SQL `NULL` in the normal SQL manner. |
+| `IF`, `CASE`, `IFNULL`, `COALESCE` | Supported | Conditional expressions can
return and consume VARIANT values. |
+| VARIANT in transient `ARRAY`, `MAP`, or `STRUCT` expressions | Supported |
This does not allow these nested types in persisted table schemas. |
+| `EXPLODE_VARIANT_ARRAY`, `EXPLODE`/`EXPLODE_OUTER` on `ARRAY<VARIANT>` |
Supported | Emits VARIANT elements and preserves SQL NULL versus Variant/JSON
`null`. |
+| `=`, `!=`, `<=>`, `<`, `<=`, `>`, `>=` | Not supported | Extract and CAST a
comparable subpath on both sides. |
+| Join key | Not supported | CAST the required subpath to the same concrete
type on both inputs. |
+| `ORDER BY`, Sort/TopN key | Not supported | CAST the required subpath before
ordering. |
+| Window partition/order key | Not supported | A whole VARIANT value cannot be
a window key. |
+| `MIN(variant)`, `MAX(variant)` | Not supported | CAST a scalar subpath
before aggregation. |
+
+For comparison, filtering, arithmetic, and ordering, extract the required
subpath and CAST it to a concrete type explicitly or implicitly:
```sql
-- Explicit CAST
@@ -403,22 +584,6 @@ SELECT * FROM tbl WHERE v['bool'];
SELECT * FROM tbl WHERE v['str'] MATCH 'Doris';
```
-- VARIANT itself cannot be used directly in ORDER BY, GROUP BY, as a JOIN KEY,
or as an aggregate argument; CAST subpaths instead.
-- Strings can be implicitly converted to VARIANT.
-
-| VARIANT | Castable | Coercible |
-| --------------- | -------- | --------- |
-| `ARRAY` | ✔ | ❌ |
-| `BOOLEAN` | ✔ | ✔ |
-| `DATE/DATETIME` | ✔ | ✔ |
-| `FLOAT` | ✔ | ✔ |
-| `IPV4/IPV6` | ✔ | ✔ |
-| `DECIMAL` | ✔ | ✔ |
-| `MAP` | ❌ | ❌ |
-| `TIMESTAMP` | ✔ | ✔ |
-| `VARCHAR` | ✔ | ✔ |
-| `JSON` | ✔ | ✔ |
-
## Wide columns
When ingested data contains many distinct JSON keys, the number of subcolumns
produced by Subcolumnization can grow rapidly; at scale this may cause metadata
bloat, higher write/merge cost, and query slowdowns. To address “wide columns”
(too many subcolumns), VARIANT provides two mechanisms: **Sparse columns** and
**DOC encoding**.
@@ -464,7 +629,7 @@ See the “Configuration” section below for the full property
list.
- **Wide tables optimization**: For wide tables with a large number of dynamic
sub-columns (e.g., more than 2000 columns) generated by the `VARIANT` type, it
is highly recommended to enable **Storage Format V3** by specifying
`"storage_format" = "V3"` in the table `PROPERTIES`. This decouples column
metadata from the Segment Footer, speeding up file opening and reducing memory
overhead.
- JSON key length ≤ 255.
- Cannot be a primary key or sort key.
-- Cannot be nested within other types (e.g., `Array<Variant>`,
`Struct<Variant>`).
+- Persisted table schemas cannot nest VARIANT within other types (for example,
`ARRAY<VARIANT>` or `STRUCT<VARIANT>`). Transient expression results can use
the supported nested-container operations listed above.
- Outside DOC mode, reading the entire VARIANT column scans all subpaths. For
very wide columns, direct `SELECT variant_col` is generally not recommended
unless DOC mode is enabled. If a column has many subpaths, consider storing the
original JSON string in an extra STRING/JSONB column for whole-object searches
like `LIKE`:
```sql
@@ -559,7 +724,7 @@ SET describe_extend_variant_column = true;
DESC variant_tbl;
```
-``` sql
+```sql
DESCRIBE ${table_name} PARTITION ($partition_name);
```
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md
b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md
index 4a9b8594781..c535bd0bee2 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md
@@ -28,7 +28,8 @@ ELEMENT_AT(container, key_or_index)
- For `ARRAY`: An integer, with indexing starting from **1**.
- For `MAP`: The key type (`K`) of the `MAP`, which can be any supported
primitive type.
- For `STRUCT`: A constant integer field position (starting from **1**) or a
constant string field name (matched **case-insensitively**).
- - For `VARIANT`: A string type.
+ - For `VARIANT` object access: A string key.
+ - For a VARIANT array in Doris 4.2 and later: An integer index; positive
indexes are 1-based and negative indexes count backward from the end.
## Return Value
@@ -41,10 +42,16 @@ ELEMENT_AT(container, key_or_index)
## Notes
-1. **Array indexes start from 1**, not 0.
-2. Negative indexes are supported: `-1` represents the last element, `-2` the
second-to-last, and so on.
+1. **ARRAY and, in Doris 4.2 and later, VARIANT array indexes start from 1**,
not 0.
+2. Negative indexes are supported for ARRAY and VARIANT array access: `-1`
represents the last element, `-2` the second-to-last, and so on.
3. The `ELEMENT_AT(container, key_or_index)` function behaves the same as
`container[key_or_index]` (see examples for details).
+```sql
+SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), 1); -- 10
+SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), 2); -- 20
+SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), -1); -- 30
+```
+
## Examples
1. The `ELEMENT_AT` function works the same as `[]`.
@@ -115,17 +122,17 @@ ELEMENT_AT(container, key_or_index)
5. When accessing a subfield of a `VARIANT`, if the `VARIANT` value is not an
OBJECT, an empty value is returned.
```SQL
- SELECT ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a");
- +------------------------------------------------------+
- | ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a") |
- +------------------------------------------------------+
- | 1 |
- +------------------------------------------------------+
-
- SELECT ELEMENT_AT(CAST('123' AS VARIANT), "");
- +----------------------------------------+
- | ELEMENT_AT(CAST('123' AS VARIANT), "") |
- +----------------------------------------+
- | |
- +----------------------------------------+
+ SELECT ELEMENT_AT(PARSE_TO_VARIANT('{"a": 1, "b": 2}'), "a");
+ +-------------------------------------------------------+
+ | ELEMENT_AT(PARSE_TO_VARIANT('{"a": 1, "b": 2}'), "a") |
+ +-------------------------------------------------------+
+ | 1 |
+ +-------------------------------------------------------+
+
+ SELECT ELEMENT_AT(PARSE_TO_VARIANT('123'), "");
+ +-------------------------------------------+
+ | ELEMENT_AT(PARSE_TO_VARIANT('123'), "") |
+ +-------------------------------------------+
+ | |
+ +-------------------------------------------+
```
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/variant-functions/parse-to-variant.md
b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/parse-to-variant.md
new file mode 100644
index 00000000000..13ce712d14e
--- /dev/null
+++
b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/parse-to-variant.md
@@ -0,0 +1,113 @@
+---
+{
+ "title": "PARSE_TO_VARIANT",
+ "language": "en",
+ "description": "Parses one complete JSON value from text or a JSON/JSONB
expression into a typed VARIANT value."
+}
+---
+
+## Description
+
+`PARSE_TO_VARIANT` parses one complete JSON value into `VARIANT`. It accepts
JSON objects, arrays, strings, numbers, booleans, and the JSON literal `null`.
This function is available in Doris 4.2 and later.
+
+## Syntax
+
+```sql
+PARSE_TO_VARIANT(<json_value>)
+```
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `<json_value>` | A `CHAR`, `VARCHAR`, or `STRING` expression containing one
complete JSON value, or a `JSON`/`JSONB` expression. JSON/JSONB input is
converted to JSON text and then parsed as VARIANT. |
+
+## Return Value
+
+Returns a `VARIANT` value.
+
+- SQL `NULL` input returns SQL `NULL`.
+- The JSON literal `null` returns Variant/JSON `null`, which is different from
SQL `NULL`.
+- Invalid JSON, duplicate object keys rejected by the current validation
settings, unsupported depth, or another validation error causes the query to
fail.
+
+## Example
+
+Parse JSON text:
+
+```sql
+SELECT CAST(
+ PARSE_TO_VARIANT('{"id": 42, "tags": ["doris", "sql"]}')
+ AS STRING
+ ) AS value;
+```
+
+```text
++----------------------------------------+
+| value |
++----------------------------------------+
+| {"id":42,"tags":["doris","sql"]} |
++----------------------------------------+
+```
+
+Parse a JSON/JSONB expression:
+
+```sql
+SELECT CAST(
+ PARSE_TO_VARIANT(CAST('{"id": 42}' AS JSON))
+ AS STRING
+ ) AS value;
+```
+
+```text
++-----------+
+| value |
++-----------+
+| {"id":42} |
++-----------+
+```
+
+Extract a value and CAST it to a concrete SQL type:
+
+```sql
+SELECT CAST(
+ PARSE_TO_VARIANT('{"user": {"id": 42}}')['user']['id']
+ AS BIGINT
+ ) AS user_id;
+```
+
+```text
++---------+
+| user_id |
++---------+
+| 42 |
++---------+
+```
+
+SQL `NULL` remains SQL `NULL`:
+
+```sql
+SELECT PARSE_TO_VARIANT(NULL) IS NULL AS is_sql_null;
+```
+
+```text
++-------------+
+| is_sql_null |
++-------------+
+| 1 |
++-------------+
+```
+
+Invalid JSON returns an error:
+
+```sql
+SELECT PARSE_TO_VARIANT('{"id":');
+```
+
+```text
+ERROR: Parse json document failed
+```
+
+## Usage Notes
+
+- Use [TRY_PARSE_TO_VARIANT](./try-parse-to-variant) when invalid input should
become SQL `NULL` instead of failing the query.
+- `PARSE_TO_VARIANT` explicitly parses JSON. By contrast, `CAST(string AS
VARIANT)` preserves the input as a VARIANT string and does not parse JSON; see
the [VARIANT CAST
rules](../../../basic-element/sql-data-types/semi-structured/VARIANT#cast-rules).
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/variant-functions/try-parse-to-variant.md
b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/try-parse-to-variant.md
new file mode 100644
index 00000000000..d20ac1438ea
--- /dev/null
+++
b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/try-parse-to-variant.md
@@ -0,0 +1,90 @@
+---
+{
+ "title": "TRY_PARSE_TO_VARIANT",
+ "language": "en",
+ "description": "Tries to parse one complete JSON value into VARIANT and
returns SQL NULL when parsing or validation fails."
+}
+---
+
+## Description
+
+`TRY_PARSE_TO_VARIANT` tries to parse one complete JSON value into `VARIANT`.
The `TRY_` prefix means that a parsing or validation error returns SQL `NULL`
instead of failing the query. This function is available in Doris 4.2 and later.
+
+## Syntax
+
+```sql
+TRY_PARSE_TO_VARIANT(<json_value>)
+```
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| `<json_value>` | A `CHAR`, `VARCHAR`, or `STRING` expression containing one
complete JSON value, or a `JSON`/`JSONB` expression. JSON/JSONB input is
converted to JSON text and then parsed as VARIANT. |
+
+## Return Value
+
+Returns a nullable `VARIANT` value.
+
+- Valid input returns the parsed VARIANT value.
+- Invalid JSON or another parsing or validation error returns SQL `NULL`.
+- SQL `NULL` input returns SQL `NULL`.
+- The valid JSON literal `null` returns Variant/JSON `null`, not SQL `NULL`.
+
+## Example
+
+Keep valid values and convert invalid JSON to SQL `NULL`:
+
+```sql
+SELECT CAST(
+ TRY_PARSE_TO_VARIANT('{"id": 1}')
+ AS STRING
+ ) AS valid_value,
+ TRY_PARSE_TO_VARIANT('{"id":') IS NULL AS invalid_is_null,
+ TRY_PARSE_TO_VARIANT(NULL) IS NULL AS input_is_null;
+```
+
+```text
++-------------+-----------------+---------------+
+| valid_value | invalid_is_null | input_is_null |
++-------------+-----------------+---------------+
+| {"id":1} | 1 | 1 |
++-------------+-----------------+---------------+
+```
+
+Parse JSON/JSONB input:
+
+```sql
+SELECT CAST(
+ TRY_PARSE_TO_VARIANT(CAST('[10, 20, 30]' AS JSON))
+ AS STRING
+ ) AS value;
+```
+
+```text
++------------+
+| value |
++------------+
+| [10,20,30] |
++------------+
+```
+
+JSON `null` and SQL `NULL` remain distinct:
+
+```sql
+SELECT TRY_PARSE_TO_VARIANT('null') IS NULL AS json_null_is_sql_null,
+ TRY_PARSE_TO_VARIANT('{') IS NULL AS error_is_sql_null;
+```
+
+```text
++-----------------------+-------------------+
+| json_null_is_sql_null | error_is_sql_null |
++-----------------------+-------------------+
+| 0 | 1 |
++-----------------------+-------------------+
+```
+
+## Usage Notes
+
+- Use [PARSE_TO_VARIANT](./parse-to-variant) when invalid input should fail
the query and expose the data-quality error.
+- This function converts only parsing and validation failures to SQL `NULL`;
it does not change the meaning of a valid JSON `null` value.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 344db4f2d6b..0b3310944ca 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -2,7 +2,7 @@
{
"title": "VARIANT",
"language": "zh-CN",
- "description": "VARIANT 类型用于存储半结构化 JSON
数据，可包含不同基础类型（整数、字符串、布尔等）以及一层数组与嵌套对象。写入时会自动基于 JSON Path
推断子列结构与类型，并对高频路径执行子列列式提取（Subcolumnization），使其以独立子列的形式参与分析，兼顾灵活性与性能。"
+ "description": "VARIANT 用于存储半结构化 JSON 数据，并支持带类型的路径访问、CAST、基于 Hash
的分组与去重，以及部分 SQL 操作。"
}
---
@@ -67,6 +67,170 @@ FROM ${table_name}
WHERE ARRAY_CONTAINS(CAST(v['tags'] AS ARRAY<TEXT>), 'Doris');
```
+## 创建和访问值
+
+:::info 版本说明
+本节所述行为适用于 Doris 4.2 及后续版本。
+:::
+
+VARIANT 值可以从 JSON 文本、JSON/JSONB 值或带确定类型的 SQL 表达式创建：
+
+- 如果要将字符串或 JSON/JSONB 表达式解析为结构化 VARIANT 值，请使用
[PARSE_TO_VARIANT](../../../sql-functions/scalar-functions/variant-functions/parse-to-variant)。
+- 如果要将受支持的 SQL 值转换为 VARIANT，请使用 `CAST(expression AS VARIANT)`。字符串会保留为 VARIANT
字符串值，该 CAST 不解析 JSON。
+
+### 解析 JSON 文本
+
+```sql
+SELECT PARSE_TO_VARIANT('{"user": {"id": 42}, "active": true}');
+SELECT PARSE_TO_VARIANT('[10, 20, 30]');
+SELECT PARSE_TO_VARIANT(CAST('{"user": {"id": 42}}' AS JSON));
+```
+
+如果非法 JSON 应该返回 SQL `NULL` 而不是使查询失败，请使用
[TRY_PARSE_TO_VARIANT](../../../sql-functions/scalar-functions/variant-functions/try-parse-to-variant)。
+
+### 访问对象和数组
+
+对象字段可以使用字符串 key 访问。在 Doris 4.2 及后续版本中，VARIANT 数组的正数索引从 1
开始，负数索引从数组末尾倒数。提取出的值仍是 `VARIANT`，如需按确定类型比较、计算或聚合，请先 CAST。
+
+```sql
+SELECT CAST(PARSE_TO_VARIANT('{"user": {"id": 42}}')['user']['id'] AS BIGINT);
+SELECT ELEMENT_AT(PARSE_TO_VARIANT('[10, 20, 30]'), 1); -- 10
+SELECT ELEMENT_AT(PARSE_TO_VARIANT('[10, 20, 30]'), -1); -- 30
+```
+
+对象和数组访问的详细说明请参见
[ELEMENT_AT](../../../sql-functions/scalar-functions/variant-functions/element-at)。
+
+## CAST 规则
+
+VARIANT 的 CAST 包括两个方向：把受支持的 SQL 值转换为 VARIANT，以及把 VARIANT 中兼容的值转换为具体 SQL 类型。
+
+### 其他类型 CAST 为 VARIANT
+
+| 源类型 | 行为 |
+| --- | --- |
+| `CHAR`、`VARCHAR`、`STRING` | 将输入保留为 VARIANT 字符串，不解析看起来像 JSON 的文本。 |
+| `BOOLEAN` | 保留 Boolean 值。 |
+| `TINYINT`、`SMALLINT`、`INT`、`BIGINT`、`LARGEINT` | 保留整数值。 |
+| `FLOAT`、`DOUBLE` | 保留浮点数值。 |
+| `DECIMALV2`、`DECIMAL(p, s)`（`p <= 38`） | 保留 Decimal 值，但需满足下文限制。 |
+| `DATE`、`DATETIME`、`TIMESTAMPTZ` | 保留对应的逻辑类型和值。 |
+| `IPV4`、`IPV6` | 保留 IP 地址值。 |
+| `JSON` / `JSONB` | 将结构化值直接转换为 VARIANT；如果输入包含 VARIANT 无法表示的 JSONB 值类型，BE 会报错。
|
+| `ARRAY<T>` | 当 `T` 为 `VARIANT` 或也在该白名单中时递归转换每个元素，并保留 SQL NULL 元素。 |
+
+仅支持上表列出的源类型。其他源类型，包括 `MAP`、`STRUCT`、`TIME`、precision 超过 38 的
Decimal，以及包含不支持元素类型的数组，都会由 BE 报错。
+
+```sql
+-- 字符串会保留为 VARIANT 字符串根值，即使内容看起来像 JSON。
+SELECT CAST(CAST('{"id": 1}' AS VARIANT) AS STRING) AS string_value,
+ VARIANT_TYPE(CAST('{"id": 1}' AS VARIANT)) AS root_type;
+-- string_value：{"id": 1}；root_type：string
+
+-- 需要结构化 VARIANT 值时，显式解析 JSON 文本。
+SELECT PARSE_TO_VARIANT('{"id": 1}') AS parsed_object;
+-- {"id":1}
+
+-- JSON/JSONB 输入按结构转换。
+SELECT CAST(CAST('{"id": 1}' AS JSON) AS VARIANT) AS parsed_object;
+-- {"id":1}
+```
+
+字符串 CAST 不解析 JSON，因此非法 JSON 文本仍是合法的 VARIANT 字符串。如需严格解析 JSON，请使用
`PARSE_TO_VARIANT`；如需在解析失败时返回 SQL `NULL`，请使用 `TRY_PARSE_TO_VARIANT`。
+
+### VARIANT CAST 为其他类型
+
+VARIANT 可以 CAST 为兼容的标量、JSON/JSONB 或数组类型：
+
+| 目标类型 | 行为 |
+| --- | --- |
+| `BOOLEAN` | 转换兼容的 Boolean 或标量根值。 |
+| `TINYINT`、`SMALLINT`、`INT`、`BIGINT`、`LARGEINT` | 将兼容的标量根值转换为指定整数类型。 |
+| `FLOAT`、`DOUBLE` | 转换兼容的数值根。 |
+| `DECIMALV2`、`DECIMAL(p, s)` | 将兼容的数值根转换为指定 Decimal 类型。 |
+| `DATE`、`DATETIME`、`TIMESTAMPTZ` | 转换兼容的日期时间根值。 |
+| `CHAR`、`VARCHAR`、`STRING` | 标量根值返回对应文本，对象和数组返回 JSON 文本。Variant/JSON `null`
返回字符串 `null`，外层 SQL `NULL` 仍是 SQL `NULL`。 |
+| `IPV4`、`IPV6` | 将兼容的 IP 地址根值转换为指定的 IP 地址类型。 |
+| `JSON` / `JSONB` | 按结构转换；如果 VARIANT 值包含 JSON/JSONB 无法表示的类型，BE 会报错。 |
+| `ARRAY<T>` | 当 `T` 为 `VARIANT` 或也在该白名单中时逐元素转换；不兼容元素遵循目标类型的 CAST 规则。 |
+
+仅支持上表列出的目标类型。其他目标类型，包括 `MAP`、`STRUCT` 和 `TIME`，都会由 BE
报错。对于受支持的目标类型，值形状不兼容、文本非法或数值越界时，按照对应 CAST 模式报错或返回 SQL `NULL`。
+
+```sql
+SELECT CAST(PARSE_TO_VARIANT('42') AS BIGINT) AS id;
+-- 42
+
+SELECT CAST(PARSE_TO_VARIANT('[1, null, 3]') AS ARRAY<INT>) AS values;
+-- [1, NULL, 3]
+
+SELECT CAST(PARSE_TO_VARIANT('{"id": 1}') AS JSON) AS json_value;
+-- {"id":1}
+```
+
+### Decimal 与日期时间转换限制
+
+| Doris 输入类型 | VARIANT 支持情况 |
+| --- | --- |
+| 旧版 `DECIMALV2` | 精确保留 precision 不超过 27、scale 不超过 9 的值。 |
+| `DECIMAL(p, s)` | 精确保留 `1 <= p <= 38` 且 `0 <= s <= p` 的值；不支持需要超过 38 位
precision 的值。 |
+| `DATE` | 保留为不含时间和时区的日历日期。 |
+| 旧版 `DATETIME` | 保留到秒，不进行时区调整。 |
+| `DATETIME(p)` | 支持 `0 <= p <= 6`，不进行时区调整。 |
+| `TIMESTAMPTZ(p)` | 支持 `0 <= p <= 6`，保留带时区调整的 timestamp 语义。 |
+| precision 超过 38 的 Decimal | 不支持作为 VARIANT 输入。 |
+| `TIME` | 不支持作为 VARIANT 输入。 |
+
+源值还必须满足对应 Doris 类型本身的合法性要求。precision 超限、日期非法或值不兼容时会报错，不会自动修复。
+
+## 分组、去重与 Hash 语义
+
+在 Doris 4.2 及后续版本中，分组、去重和集合运算会把逻辑上等价的 VARIANT 视为同一个值，不受来源 SQL 类型或物理表示影响：
+
+- 等价的整数数值表示会被视为同一个值。
+- Decimal 尾随零不影响值，因此 `1.20` 与 `1.2` 会被视为同一个值。
+- `+0`、`-0` 与整数零会被视为同一个值。
+- 对象 key 的顺序不影响是否视为同一个值，但数组元素顺序会影响。
+- Variant/JSON `null` 与 SQL `NULL` 不同。
+
+Hash 类算子也按上述逻辑值规则计算 key。因此，只要两个值按上述规则被视为同一个值，无论来源是解析后的 JSON 还是带类型的
CAST，都会得到相同的内部 Hash Key。该 Hash 只用于 Doris 内部执行，不是稳定的用户侧校验值。
+
+这些规则适用于 `GROUP BY`、`DISTINCT`、`COUNT(DISTINCT ...)`、`INTERSECT`、`EXCEPT` 和
`UNION DISTINCT` 等已支持的操作，但不会开放根 VARIANT 比较谓词：直接执行 `VARIANT = VARIANT` 或排序比较仍不支持。
+
+```sql
+-- 1 和 1.0 只有一个 distinct logical value。
+SELECT COUNT(DISTINCT value) AS distinct_count
+FROM (
+ SELECT PARSE_TO_VARIANT('1') AS value
+ UNION ALL
+ SELECT PARSE_TO_VARIANT('1.0') AS value
+) AS numeric_values;
+-- distinct_count: 1
+
+-- 对象 key 顺序被忽略；数组顺序会保留。
+SELECT COUNT(DISTINCT value) AS distinct_count
+FROM (
+ SELECT PARSE_TO_VARIANT('{"a": 1, "b": 2}') AS value
+ UNION ALL
+ SELECT PARSE_TO_VARIANT('{"b": 2, "a": 1}') AS value
+) AS object_values;
+-- distinct_count: 1
+
+SELECT COUNT(DISTINCT value) AS distinct_count
+FROM (
+ SELECT PARSE_TO_VARIANT('[1, 2]') AS value
+ UNION ALL
+ SELECT PARSE_TO_VARIANT('[2, 1]') AS value
+) AS array_values;
+-- distinct_count: 2
+```
+
+## NULL 语义
+
+SQL `NULL` 与 Variant/JSON `null` 是不同的值：
+
+- SQL `NULL` 表示 SQL 值缺失，并遵循普通 SQL NULL 传播规则。
+- Variant/JSON `null` 是一个 VARIANT 值，例如 `PARSE_TO_VARIANT('null')` 的返回值。
+- `TRY_PARSE_TO_VARIANT` 遇到非法输入时返回 SQL `NULL`，这与成功解析 JSON 字面量 `null` 不同。
+
## 基本类型
VARIANT 自动推断的子列基础类型包括：
@@ -171,11 +335,12 @@ SELECT * FROM test_var_schema;
+------+-----------------------------+
```
-Schema 仅指导“存储层”的持久化类型，计算逻辑仍以实际数据的动态类型为准：
+Schema 仅指导“存储层”的持久化类型。没有写入表的查询表达式仍保留实际的运行时类型：
```sql
--- 实际 v['a'] 的运行时类型仍可能是 STRING
-SELECT variant_type(CAST('{"a" : "12345"}' AS VARIANT<'a' : INT>)['a']);
+-- JSON 成员带引号，因此类型为 STRING。这里使用 PARSE_TO_VARIANT，
+-- 因为 CAST(string AS VARIANT) 始终把整个输入保留为字符串。
+SELECT variant_type(PARSE_TO_VARIANT('{"a" : "12345"}')['a']);
```
通配符与匹配顺序：
@@ -387,10 +552,26 @@ SELECT v FROM variant_tbl WHERE k = 2;
排序在每一层都会生效——顶层 key 输出为 `a`、`b`、`c`，嵌套 object 内 key 输出为 `x`、`y`。
-## 支持的运算与 CAST 规则
+## 支持的运算
-- VARIANT 本身不支持与其他类型直接比较/运算，两个 VARIANT 之间也不支持直接比较。
-- 如需比较、过滤、聚合、排序，请对子列显式或隐式 CAST 到确定类型。
+在 Doris 4.2 及后续版本中，整个 VARIANT 值支持基于 Hash 的分组和去重，但不支持比较、Join Key 或排序语义。
+
+| 对整个 VARIANT 值执行的操作 | 支持情况 | 说明 |
+| --- | --- | --- |
+| `GROUP BY` | 支持 | 使用上文所述的分组与 Hash 规则。 |
+| `DISTINCT`、`COUNT(DISTINCT ...)` | 支持 | 逻辑等价的值会被去重。 |
+| `INTERSECT`、`EXCEPT`、`UNION DISTINCT` | 支持 | 使用上文所述的相同规则。 |
+| `COUNT(*)`、`COUNT(variant)` | 支持 | `COUNT(variant)` 按普通 SQL 规则排除外层 SQL
`NULL`。 |
+| `IF`、`CASE`、`IFNULL`、`COALESCE` | 支持 | 条件表达式可以返回和消费 VARIANT 值。 |
+| 临时 `ARRAY`、`MAP` 或 `STRUCT` 表达式中包含 VARIANT | 支持 | 这不表示持久化表结构可以使用这些嵌套类型。 |
+| `EXPLODE_VARIANT_ARRAY`、对 `ARRAY<VARIANT>` 使用 `EXPLODE`/`EXPLODE_OUTER` | 支持
| 输出 VARIANT 元素，并保留 SQL `NULL` 与 Variant/JSON `null` 的区别。 |
+| `=`、`!=`、`<=>`、`<`、`<=`、`>`、`>=` | 不支持 | 请在两侧提取可比较的子路径，并 CAST 为具体类型。 |
+| Join Key | 不支持 | 请把两侧所需子路径 CAST 为相同的具体类型。 |
+| `ORDER BY`、Sort/TopN Key | 不支持 | 排序前请先 CAST 所需子路径。 |
+| 窗口分区键或排序键 | 不支持 | 整个 VARIANT 值不能作为窗口 Key。 |
+| `MIN(variant)`、`MAX(variant)` | 不支持 | 聚合前请先 CAST 标量子路径。 |
+
+如需比较、过滤、计算或排序，请提取所需子路径，再显式或隐式 CAST 为具体类型：
```sql
-- 显式 CAST
@@ -403,22 +584,6 @@ SELECT * FROM tbl WHERE v['bool'];
SELECT * FROM tbl WHERE v['str'] MATCH 'Doris';
```
-- VARIANT 本身不可直接用于 ORDER BY、GROUP BY、JOIN KEY 或聚合参数；对子列 CAST 后可正常使用。
-- 字符串类型可隐式转换为 VARIANT。
-
-| VARIANT | Castable | Coercible |
-| --------------- | -------- | --------- |
-| `ARRAY` | ✔ | ❌ |
-| `BOOLEAN` | ✔ | ✔ |
-| `DATE/DATETIME` | ✔ | ✔ |
-| `FLOAT` | ✔ | ✔ |
-| `IPV4/IPV6` | ✔ | ✔ |
-| `DECIMAL` | ✔ | ✔ |
-| `MAP` | ❌ | ❌ |
-| `TIMESTAMP` | ✔ | ✔ |
-| `VARCHAR` | ✔ | ✔ |
-| `JSON` | ✔ | ✔ |
-
## 宽列
当导入数据包含大量不同的 JSON key
时，通过子列列式提取（Subcolumnization）生成的子列会迅速增多；当规模达到一定程度，可能出现元数据膨胀、写入/合并开销增大、查询性能下降等问题。为应对“宽列”（子列过多），VARIANT
提供两种机制：**稀疏列** 与 **DOC 编码**。
@@ -464,7 +629,7 @@ SELECT * FROM tbl WHERE v['str'] MATCH 'Doris';
- **大宽表优化**：对于会通过子列列式提取（Subcolumnization）生成大量独立子列的宽表场景（例如超过 2000 列），强烈建议开启
**V3 存储格式**。通过在建表 `PROPERTIES` 中指定 `"storage_format" = "V3"`，可以将列元数据与 Segment
Footer 解耦，加快文件打开速度并降低内存占用。
- JSON key 长度 ≤ 255。
- 不支持作为主键或排序键。
-- 不支持与其他类型嵌套（如 `Array<Variant>`、`Struct<Variant>`）。
+- 持久化表结构不能把 VARIANT 嵌套在其他类型中（如
`ARRAY<VARIANT>`、`STRUCT<VARIANT>`）；临时表达式结果可以使用上表列出的嵌套容器能力。
- 在未启用 DOC mode 时，读取整个 VARIANT 列会扫描所有子字段。对于超宽列，一般不建议直接 `SELECT
variant_col`；如果整列读取是主要查询模式，建议优先使用 DOC mode。若列包含大量子字段，也可额外存储原始 JSON 的
STRING/JSONB 列，以优化如 `LIKE` 等整体匹配：
```sql
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md
index f9bc791d6ca..1899533f092 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md
@@ -2,7 +2,7 @@
{
"title": "ELEMENT_AT",
"language": "zh-CN",
- "description": "ELEMENTAT 函数用于从数组或 map 中按指定的索引或键提取对应的元素值。"
+ "description": "ELEMENT_AT 函数按索引、键或字段名从 ARRAY、MAP、STRUCT 或 VARIANT
中提取元素，并说明各类型的索引起点、负索引语义与越界行为。"
}
---
@@ -28,7 +28,8 @@ ELEMENT_AT(container, key_or_index)
- 对于 `ARRAY`：为整数类型，索引从 **1** 开始；
- 对于 `MAP`：为 `MAP` 中的键类型（`K`），可为任意支持的基础类型。
- 对于 `STRUCT`：为常量整数（字段位置，从 **1** 开始）或常量字符串（字段名，按**大小写不敏感**匹配）。
- - 对于 `VARIANT`： 为字符串类型
+ - 对于 `VARIANT` 对象访问：为字符串类型的 key；
+ - 对于 Doris 4.2 及后续版本中的 VARIANT 数组：为整数索引，正数索引从 1 开始，负数索引从数组末尾倒数。
## 返回值
@@ -41,10 +42,16 @@ ELEMENT_AT(container, key_or_index)
## 使用说明
-1. **数组索引从 1 开始**，不是从 0 开始；
-2. 支持负数索引，`-1` 表示最后一个元素，`-2` 表示倒数第二个，以此类推；
+1. **ARRAY 数组以及 Doris 4.2 及后续版本中的 VARIANT 数组，索引都从 1 开始**，不是从 0 开始；
+2. ARRAY 和 VARIANT 数组都支持负数索引，`-1` 表示最后一个元素，`-2` 表示倒数第二个，以此类推；
3. `ELEMENT_AT(container, key_or_index)` 函数的功能与 `container[key_or_index]`
作用一致（详细见示例）。
+```sql
+SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), 1); -- 10
+SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), 2); -- 20
+SELECT ELEMENT_AT(parse_to_variant('[10, 20, 30]'), -1); -- 30
+```
+
## 示例
1. `ELEMENT_AT` 函数的功能与 `[]` 作用一致。
@@ -115,19 +122,17 @@ ELEMENT_AT(container, key_or_index)
5. 访问 `VARIANT` 的某个子列，如果 `VARIANT` 的值不是 OBJECT，返回空
```SQL
- SELECT ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a");
- +------------------------------------------------------+
- | ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a") |
- +------------------------------------------------------+
- | 1 |
- +------------------------------------------------------+
-
- SELECT ELEMENT_AT(CAST('123' AS VARIANT), "");
- +----------------------------------------+
- | ELEMENT_AT(CAST('123' AS VARIANT), "") |
- +----------------------------------------+
- | |
- +----------------------------------------+
+ SELECT ELEMENT_AT(PARSE_TO_VARIANT('{"a": 1, "b": 2}'), "a");
+ +-------------------------------------------------------+
+ | ELEMENT_AT(PARSE_TO_VARIANT('{"a": 1, "b": 2}'), "a") |
+ +-------------------------------------------------------+
+ | 1 |
+ +-------------------------------------------------------+
+
+ SELECT ELEMENT_AT(PARSE_TO_VARIANT('123'), "");
+ +-------------------------------------------+
+ | ELEMENT_AT(PARSE_TO_VARIANT('123'), "") |
+ +-------------------------------------------+
+ | |
+ +-------------------------------------------+
```
-
-
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/parse-to-variant.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/parse-to-variant.md
new file mode 100644
index 00000000000..3d2f063e3a5
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/parse-to-variant.md
@@ -0,0 +1,113 @@
+---
+{
+ "title": "PARSE_TO_VARIANT",
+ "language": "zh-CN",
+ "description": "PARSE_TO_VARIANT 将 JSON 文本或 JSON/JSONB 表达式中的完整 JSON
值解析为带类型信息的 VARIANT，并说明输入、返回值、错误行为与示例。"
+}
+---
+
+## 功能
+
+`PARSE_TO_VARIANT` 将一个完整 JSON 值解析为 `VARIANT`，支持 JSON 对象、数组、字符串、数字、布尔值和 JSON
字面量 `null`。该函数自 Doris 4.2 起支持。
+
+## 语法
+
+```sql
+PARSE_TO_VARIANT(<json_value>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `<json_value>` | 包含一个完整 JSON 值的 `CHAR`、`VARCHAR` 或 `STRING` 表达式，也可以是
`JSON`/`JSONB` 表达式。JSON/JSONB 输入会先转换为 JSON 文本，再解析为 VARIANT。 |
+
+## 返回值
+
+返回 `VARIANT` 值。
+
+- 输入为 SQL `NULL` 时返回 SQL `NULL`。
+- 输入为 JSON 字面量 `null` 时返回 Variant/JSON `null`，它与 SQL `NULL` 不同。
+- JSON 非法、对象 key 重复且当前校验设置不允许、嵌套深度超限或发生其他校验错误时，查询失败。
+
+## 示例
+
+解析 JSON 文本：
+
+```sql
+SELECT CAST(
+ PARSE_TO_VARIANT('{"id": 42, "tags": ["doris", "sql"]}')
+ AS STRING
+ ) AS value;
+```
+
+```text
++----------------------------------------+
+| value |
++----------------------------------------+
+| {"id":42,"tags":["doris","sql"]} |
++----------------------------------------+
+```
+
+解析 JSON/JSONB 表达式：
+
+```sql
+SELECT CAST(
+ PARSE_TO_VARIANT(CAST('{"id": 42}' AS JSON))
+ AS STRING
+ ) AS value;
+```
+
+```text
++-----------+
+| value |
++-----------+
+| {"id":42} |
++-----------+
+```
+
+提取值并 CAST 为具体 SQL 类型：
+
+```sql
+SELECT CAST(
+ PARSE_TO_VARIANT('{"user": {"id": 42}}')['user']['id']
+ AS BIGINT
+ ) AS user_id;
+```
+
+```text
++---------+
+| user_id |
++---------+
+| 42 |
++---------+
+```
+
+SQL `NULL` 仍返回 SQL `NULL`：
+
+```sql
+SELECT PARSE_TO_VARIANT(NULL) IS NULL AS is_sql_null;
+```
+
+```text
++-------------+
+| is_sql_null |
++-------------+
+| 1 |
++-------------+
+```
+
+非法 JSON 会报错：
+
+```sql
+SELECT PARSE_TO_VARIANT('{"id":');
+```
+
+```text
+ERROR: Parse json document failed
+```
+
+## 使用说明
+
+- 如果希望把非法输入转换为 SQL `NULL`，请使用 [TRY_PARSE_TO_VARIANT](./try-parse-to-variant)。
+- `PARSE_TO_VARIANT` 会显式解析 JSON。相比之下，`CAST(string AS VARIANT)` 会把输入保留为 VARIANT
字符串，不解析 JSON，详见 [VARIANT CAST
规则](../../../basic-element/sql-data-types/semi-structured/VARIANT#cast-规则)。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/try-parse-to-variant.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/try-parse-to-variant.md
new file mode 100644
index 00000000000..86b4f8b2637
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/try-parse-to-variant.md
@@ -0,0 +1,90 @@
+---
+{
+ "title": "TRY_PARSE_TO_VARIANT",
+ "language": "zh-CN",
+ "description": "TRY_PARSE_TO_VARIANT 尝试把完整 JSON 值解析为 VARIANT，并在解析或校验失败时返回
SQL NULL，而不是使当前查询直接失败。"
+}
+---
+
+## 功能
+
+`TRY_PARSE_TO_VARIANT` 尝试把一个完整 JSON 值解析为 `VARIANT`。函数名中的 `TRY_`
表示：发生解析或校验错误时返回 SQL `NULL`，而不是使查询失败。该函数自 Doris 4.2 起支持。
+
+## 语法
+
+```sql
+TRY_PARSE_TO_VARIANT(<json_value>)
+```
+
+## 参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `<json_value>` | 包含一个完整 JSON 值的 `CHAR`、`VARCHAR` 或 `STRING` 表达式，也可以是
`JSON`/`JSONB` 表达式。JSON/JSONB 输入会先转换为 JSON 文本，再解析为 VARIANT。 |
+
+## 返回值
+
+返回可为 NULL 的 `VARIANT` 值。
+
+- 合法输入返回解析后的 VARIANT 值。
+- 非法 JSON 或其他解析、校验错误返回 SQL `NULL`。
+- 输入为 SQL `NULL` 时返回 SQL `NULL`。
+- 合法的 JSON 字面量 `null` 返回 Variant/JSON `null`，不是 SQL `NULL`。
+
+## 示例
+
+保留合法值，并把非法 JSON 转换为 SQL `NULL`：
+
+```sql
+SELECT CAST(
+ TRY_PARSE_TO_VARIANT('{"id": 1}')
+ AS STRING
+ ) AS valid_value,
+ TRY_PARSE_TO_VARIANT('{"id":') IS NULL AS invalid_is_null,
+ TRY_PARSE_TO_VARIANT(NULL) IS NULL AS input_is_null;
+```
+
+```text
++-------------+-----------------+---------------+
+| valid_value | invalid_is_null | input_is_null |
++-------------+-----------------+---------------+
+| {"id":1} | 1 | 1 |
++-------------+-----------------+---------------+
+```
+
+解析 JSON/JSONB 输入：
+
+```sql
+SELECT CAST(
+ TRY_PARSE_TO_VARIANT(CAST('[10, 20, 30]' AS JSON))
+ AS STRING
+ ) AS value;
+```
+
+```text
++------------+
+| value |
++------------+
+| [10,20,30] |
++------------+
+```
+
+JSON `null` 与 SQL `NULL` 仍然不同：
+
+```sql
+SELECT TRY_PARSE_TO_VARIANT('null') IS NULL AS json_null_is_sql_null,
+ TRY_PARSE_TO_VARIANT('{') IS NULL AS error_is_sql_null;
+```
+
+```text
++-----------------------+-------------------+
+| json_null_is_sql_null | error_is_sql_null |
++-----------------------+-------------------+
+| 0 | 1 |
++-----------------------+-------------------+
+```
+
+## 使用说明
+
+- 如果非法输入应该使查询失败并暴露数据质量问题，请使用 [PARSE_TO_VARIANT](./parse-to-variant)。
+- 本函数只会把解析和校验错误转换为 SQL `NULL`，不会改变合法 JSON `null` 的含义。
diff --git a/sidebars.ts b/sidebars.ts
index 37d283556c7..e19f3ef6f9d 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -1875,6 +1875,8 @@ const sidebars: SidebarsConfig = {
label: 'Variant Functions',
items: [
'sql-manual/sql-functions/scalar-functions/variant-functions/element-at',
+
'sql-manual/sql-functions/scalar-functions/variant-functions/parse-to-variant',
+
'sql-manual/sql-functions/scalar-functions/variant-functions/try-parse-to-variant',
'sql-manual/sql-functions/scalar-functions/variant-functions/variant-type',
],
},
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
