eldenmoon opened a new pull request, #4170:
URL: https://github.com/apache/doris-website/pull/4170
## What changed
Reworks the dev (Doris 5.0.0) VARIANT documentation, English and Chinese, so
that it describes the behavior of master together with apache/doris#67675:
- **VARIANT reference** (`VARIANT.md`), reorganized into one page per type
with these sections:
- *Write data*: how each write path turns input into a VARIANT value.
`INSERT` of a string stores a VARIANT string, while `PARSE_TO_VARIANT` and load
jobs parse JSON. Covers the JSON-format load that re-parses string values,
parse errors, and invalid JSON (kept as a string by default).
- *What storage keeps*: `null` members and empty containers are dropped, a
root `null` reads back as `{}`, `DATE`/`DATETIME` outside a Schema Template
become strings, dotted keys become nested paths, and mixed booleans and numbers
can become `1`/`0`.
- *CAST and implicit conversion*: both CAST directions with verified
whitelists, failure to `NULL` regardless of `enable_strict_cast`, the implicit
type chosen for sub-path comparisons (`DECIMAL(38, 9)`, `DOUBLE`,
`DATETIME(6)`, `STRING`, `BOOLEAN`), function and JSON-function arguments, and
what still needs an explicit CAST.
- *NULL semantics*: SQL `NULL` versus VARIANT `null` for every relevant
operator, and the difference between computed and stored values.
- *Comparison, grouping, and ordering*: the supported-operation matrix,
equality rules (for example `1 = 1.0` but `DECIMAL 1.5 != DOUBLE 1.5`), the
total order across kinds, typed versus VARIANT comparison, and caveats (cost,
no runtime filter, stored-value effects).
- *Schema Template*: accepted field types, write-time conversion, reading
without auto cast, and glob matching.
- *Type inference and type conflicts*: updated for the current storage
(for example, integer plus double now becomes JSONB).
- *ALTER TABLE*: what can and cannot change. `ADD COLUMN ... VARIANT NOT
NULL` is impossible, the template cannot change, and only
`variant_doc_materialization_min_rows` can be altered.
- *Column properties*: defaults, ranges and ALTER-ability, plus the
`default_variant_*` session variables and the BE configurations.
- **Function pages**:
- `PARSE_TO_VARIANT` / `TRY_PARSE_TO_VARIANT`: invalid JSON is kept as a
string; `NULL` or an error only for over-long keys and duplicate keys.
- `VARIANT_TYPE`: returns one type name for the value itself.
- `ELEMENT_AT`: `NULL` cases, and null semantics.
- **Workload guide, import page, feature page**: the examples no longer
`INSERT` JSON strings into VARIANT. The import page explains how loads convert
values, and the feature page drops outdated claims about join keys and type
promotion.
Merge this after apache/doris#67675. That PR introduces the whole-VARIANT
`=`/`!=`/`<=>`, joins, ORDER BY and window keys, the implicit JSON cast for
JSON functions, and the rejection of invalid UTF-8 in `CAST(string AS
VARIANT)`, and it removes the Schema Template auto cast. Everything else
describes current master.
## Why
The dev pages still described several 4.x behaviors that no longer hold on
master, and some pages contradicted each other:
- The examples wrote JSON with `INSERT ... VALUES ('{...}')`, which now
stores a VARIANT string, so `v['a']` returns `NULL`.
- The FAQ said VARIANT `null` and SQL `NULL` are equivalent, while the NULL
section said they differ.
- `TRY_PARSE_TO_VARIANT` claimed that invalid JSON returns `NULL`.
- `VARIANT_TYPE` showed a per-path JSON map.
- The CAST whitelist listed `TIMESTAMPTZ` as a source, which the FE rejects.
- The type promotion table was outdated.
The user-visible questions of CAST behavior, ALTER support, NULL handling
and GROUP BY/ORDER BY ordering were not answered anywhere.
Version wording: "Doris 4.2 and later" is replaced by "Doris 5.0.0 and
later", because branch-4.2 keeps `enable_variant_v2 = false` (VARIANT V1 by
default), and other dev pages already refer to master features as 5.0.0. The
4.x pages are intentionally unchanged.
## Validation
- Every SQL example and behavior claim was run on a single-node cluster
built from the apache/doris#67675 head (master merged at `050b83b148c`), with
default session variables and BE configuration. This covered INSERT and
group-commit INSERT, Stream Load in CSV and JSON format, parse errors, CAST in
both directions with `enable_strict_cast` on and off, null handling before and
after storage, ORDER BY / GROUP BY / join / window results, all ALTER
statements in the table, and Schema Template conversions. The code paths behind
them were cross-checked in FE (`TypeCoercionUtils`, `CheckCast`,
`Column.checkSchemaChangeAllowed`, `PropertyAnalyzer`, `NereidsLoadUtils`) and
BE (`variant_canonical.cpp`, `variant_string_parse.cpp`,
`variant_path_builder.cpp`).
- `git diff --check`: passed.
- `docs:links:changed`, `docs:sql-functions:changed`,
`docs:features:changed`, frontmatter and markdown-structure lint: no findings.
- `docs:i18n-sync:changed`: only `i18n-sync-version-counterpart` warnings.
This is an intentional version exception, because the 4.x docs describe VARIANT
V1.
- `docs:seo:changed`: the existing cross-version duplicate-title warnings,
plus description-length warnings on three pages whose descriptions this PR does
not change.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
