This is an automated email from the ASF dual-hosted git repository.

csun5285 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 8e67abf21c6 [doc](variant) Add a VARIANT storage and tuning guide and 
update the VARIANT docs (#4658)
8e67abf21c6 is described below

commit 8e67abf21c68f906197d311b397b7e39f92e619e
Author: Chenyang Sun <[email protected]>
AuthorDate: Thu Nov 19 20:44:54 2026 +0800

    [doc](variant) Add a VARIANT storage and tuning guide and update the 
VARIANT docs (#4658)
    
    Add variant-storage-tuning.md (en, zh-CN) under VARIANT in the sidebar:
    how JSON paths become subcolumns or stay in sparse encoding, the
    properties variant_max_subcolumns_count,
    variant_subcolumn_extraction_min_rows and variant_enable_doc_mode with
    four scenarios, and variant_sparse_hash_shard_count.
    
    Update the dev VARIANT docs to the behavior of apache/doris#70408: the
    row threshold renamed to variant_subcolumn_extraction_min_rows and
    working without DOC mode, variant_sparse_hash_shard_count in place of
    variant_doc_hash_shard_count, DOC mode together with the subcolumn
    count, a count of 0 on columns created from 4.2,
    variant_enable_typed_paths_to_sparse only false, the DOC mode
    description of the workload guide, and the subcolumn count of the
    VARIANT SEARCH example.
    
    ## Versions
    
    - [x] dev
    - [ ] 4.x
    - [ ] 3.x
    - [ ] 2.1 or older (not covered by version/language sync gate)
    
    ## Languages
    
    - [ ] Chinese
    - [ ] English
    
    ## Docs Checklist
    
    - [ ] Checked by AI
    - [ ] Test Cases Built
    - [ ] Updated required version and language counterparts, or explained
    why not
    - [ ] If only one language changed, confirmed whether source/translation
    counterparts need sync
    
    ---------
    
    Co-authored-by: Claude Opus 5.5 <[email protected]>
---
 .../sql-data-types/semi-structured/VARIANT.md      |  78 +++++--
 .../semi-structured/variant-storage-tuning.md      | 255 +++++++++++++++++++++
 .../semi-structured/variant-workload-guide.md      |  17 +-
 .../index/inverted-index/search-function.md        |   2 +-
 .../sql-data-types/semi-structured/VARIANT.md      |  78 +++++--
 .../semi-structured/variant-storage-tuning.md      | 255 +++++++++++++++++++++
 .../semi-structured/variant-workload-guide.md      |  17 +-
 .../index/inverted-index/search-function.md        |   2 +-
 sidebars.ts                                        |   1 +
 .../variant/variant-doc-mode-full-document.png     | Bin 0 -> 166648 bytes
 .../variant-subcolumns-and-sparse-encoding.png     | Bin 0 -> 121601 bytes
 11 files changed, 655 insertions(+), 50 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 5d21b2b5c98..f4db666caef 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
@@ -538,7 +538,7 @@ v1 VARIANT<
 > NULL
 ```
 
-Matched paths participate in Subcolumnization by default. If too many paths 
match and generate too many subcolumns, consider 
`variant_enable_typed_paths_to_sparse` (see [Column 
properties](#column-properties)).
+Matched paths always go through Subcolumnization and do not count toward 
`variant_max_subcolumns_count`, so avoid patterns that match a large number of 
paths.
 
 The Schema Template cannot be changed after the column is created. See [ALTER 
TABLE](#alter-table).
 
@@ -556,7 +556,7 @@ ALTER TABLE example_tbl ADD COLUMN `v.x` VARIANT;
 - `ADD COLUMN` of a nullable VARIANT column, with or without a Schema Template 
and properties.
 - `DROP COLUMN`, `RENAME COLUMN`, and `MODIFY COLUMN ... COMMENT '...'`.
 - `ADD INDEX` and `DROP INDEX`. An index with `field_pattern` can only be 
defined in `CREATE TABLE`.
-- On a column without a Schema Template: changing `NOT NULL` to `NULL`, and 
changing `variant_doc_materialization_min_rows`. `MODIFY COLUMN` takes the 
complete column definition; a property it omits takes its default value (see 
[Column properties](#column-properties)), so restate every property whose value 
differs from the default.
+- On a column without a Schema Template: changing `NOT NULL` to `NULL`, and 
changing `variant_doc_materialization_min_rows` (a column created before 
version 4.2 without DOC mode and with `variant_max_subcolumns_count = 0` can 
only keep it at `0`). `MODIFY COLUMN` takes the complete column definition; a 
property it omits takes its default value (see [Column 
properties](#column-properties)), so restate every property whose value differs 
from the default.
 
 Not supported:
 
@@ -588,8 +588,7 @@ CREATE TABLE example_table (
       'path_2' : STRING,
       properties(
           'variant_max_subcolumns_count' = '2048',
-          'variant_enable_typed_paths_to_sparse' = 'true',
-          'variant_sparse_hash_shard_count' = '64'
+          'variant_doc_hash_shard_count' = '64'
       )
   >
 );
@@ -597,13 +596,12 @@ CREATE TABLE example_table (
 
 | Property | Default | ALTER | Description |
 | --- | --- | --- | --- |
-| `variant_max_subcolumns_count` | `2048` | No | Maximum number of dynamic 
paths that go through Subcolumnization in one data file; paths with more 
non-null values are chosen first, and the other paths are stored in sparse 
columns. `0` means no limit. Range 0 to 100000; stay at or below 10000. The 
default is enough for most workloads; if the workload truly needs a much larger 
number of subcolumns, prefer [DOC 
mode](./variant-workload-guide.md#doc-mode-template). |
-| `variant_enable_typed_paths_to_sparse` | `false` | No | By default, Schema 
Template paths always go through Subcolumnization and do not count toward 
`variant_max_subcolumns_count`. When `true`, they count toward the limit and 
can be stored in sparse columns. |
-| `variant_sparse_hash_shard_count` | `1` | No | Number of physical sparse 
columns that sparse paths are distributed to by hash. Range 0 to 1024; `0` is 
treated as `1`. |
+| `variant_max_subcolumns_count` | `2048` | No | Maximum number of dynamic 
paths that go through Subcolumnization in one data file; paths with more 
non-null values are chosen first, and the other paths are stored in sparse 
columns. `0` means that no dynamic path goes through Subcolumnization and all 
of them are stored in sparse columns; in a column created before version 4.2, 
`0` still means no limit, see [Sparse columns](#sparse-columns). Range 0 to 
100000; stay at or below 10000. The d [...]
+| `variant_enable_typed_paths_to_sparse` | `false` | No | Cannot be set from 
version 4.2: a column definition that states it fails, also with `false`. 
Schema Template paths always go through Subcolumnization and do not count 
toward `variant_max_subcolumns_count`. A column that set it to `true` before 
version 4.2 keeps it: these paths count toward the limit and can be stored in 
sparse columns. `SHOW CREATE TABLE` before version 4.2 prints this property for 
every VARIANT column without DOC [...]
+| `variant_doc_hash_shard_count` | `1` | No | Number of physical sparse 
columns that sparse paths are distributed to by hash; with DOC mode, the number 
of columns that the stored document is split into. Range 0 to 1024; `0` is 
treated as `1`. Before version 4.2 it applied only with DOC mode. |
 | `variant_max_sparse_column_statistics_size` | `10000` | No | Maximum number 
of sparse paths in one data file whose statistics are recorded. Beyond it, a 
query on a path that has no statistics cannot skip the sparse columns. Range 1 
to 50000. |
-| `variant_enable_doc_mode` | `false` | No | Enables DOC mode. It cannot be 
set together with `variant_max_subcolumns_count`, 
`variant_enable_typed_paths_to_sparse`, 
`variant_max_sparse_column_statistics_size`, or 
`variant_sparse_hash_shard_count`. |
-| `variant_doc_materialization_min_rows` | `0` | Only without a Schema 
Template | DOC mode only. A write with fewer rows stores only the document; 
Subcolumnization happens once compaction merges files up to the threshold. `0` 
performs Subcolumnization at write time. Range 0 to 1000000000. |
-| `variant_doc_hash_shard_count` | `64` | No | DOC mode only. Number of 
columns that the stored document is split into. Range 0 to 1024; `0` is treated 
as `1`. |
+| `variant_enable_doc_mode` | `false` | No | Enables DOC mode, which also 
stores the complete document. It can be set together with 
`variant_max_subcolumns_count`, `variant_doc_materialization_min_rows` and 
`variant_doc_hash_shard_count`, but not with 
`variant_max_sparse_column_statistics_size`. |
+| `variant_doc_materialization_min_rows` | `0` | Only without a Schema 
Template | A data file with fewer rows skips Subcolumnization and stores its 
dynamic paths in sparse columns (with DOC mode, only the document); 
Subcolumnization happens once compaction writes a data file that reaches the 
threshold. `0` performs Subcolumnization at write time. Range 0 to 1000000000. 
Before version 4.2 it applied only with DOC mode. |
 
 The **ALTER** column tells whether `ALTER TABLE ... MODIFY COLUMN` can change 
the property; see [ALTER TABLE](#alter-table). See [Wide 
columns](#wide-columns) for how to use the sparse and DOC mode properties.
 
@@ -722,6 +720,7 @@ Disabling norms does not affect `MATCH` filtering, but 
`score()` returns an erro
    );
    SELECT * FROM tbl WHERE v_str MATCH 'Doris';
    ```
+4. The path is stored in sparse columns: a subpath index needs a subcolumn. A 
path beyond `variant_max_subcolumns_count` has none, with 
`variant_max_subcolumns_count = 0` no dynamic path has one, and a data file 
with fewer rows than `variant_doc_materialization_min_rows` has no dynamic 
subcolumn until compaction writes a data file that reaches the threshold. 
Without a subcolumn, `SEARCH()` fails with "SEARCH index unavailable for 
Variant field", and `MATCH` falls back to matching the val [...]
 
 ## Wide columns
 
@@ -729,27 +728,71 @@ When ingested data contains many distinct JSON keys, the 
number of subcolumns pr
 
 For workload selection guidance, see [Variant Workload 
Guide](./variant-workload-guide.md). This section only explains the mechanisms 
and their related properties.
 
-Note: these two mechanisms are mutually exclusive—enabling DOC encoding 
disables sparse columns, and vice versa.
+With DOC encoding, `variant_max_subcolumns_count`, 
`variant_doc_materialization_min_rows` and `variant_doc_hash_shard_count` apply 
as well: at most `variant_max_subcolumns_count` paths are extracted, and the 
other paths are read from the document; 
`variant_max_sparse_column_statistics_size` cannot be set together with DOC 
encoding. For the values to choose in each scenario, see [VARIANT Storage and 
Tuning](./variant-storage-tuning.md).
 
 ### Sparse columns
 
 **How it works**
 
 - The system ranks paths by non-null ratio / sparsity: high-frequency 
(less-sparse) paths go through Subcolumnization and are stored as independent 
subcolumns; remaining low-frequency (sparse) paths are merged and stored in 
sparse columns. The maximum number of extracted subcolumns is controlled by 
`variant_max_subcolumns_count`.
-- If a path is declared in a Schema Template, by default it will not be moved 
into sparse columns; set `variant_enable_typed_paths_to_sparse` to allow typed 
paths to be moved into sparse columns.
-- Sparse columns support sharding: distribute sparse subpaths across multiple 
sparse columns to reduce per-column read overhead and improve read efficiency. 
Use `variant_sparse_hash_shard_count` to specify how many sparse columns are 
physically stored.
+- A path declared in a Schema Template is not moved into sparse columns 
(except in a column that set `variant_enable_typed_paths_to_sparse = true` 
before version 4.2).
+- `variant_max_subcolumns_count = 0` stores every dynamic path in sparse 
columns, while Schema Template paths still go through Subcolumnization. Use it 
when values are mostly read whole. To send every dynamic path through 
Subcolumnization instead, for example to keep subpath indexes on them, set a 
count above the number of distinct paths:
+  ```sql
+  -- every dynamic path in sparse columns
+  v VARIANT<properties('variant_max_subcolumns_count' = '0')>
+
+  -- every dynamic path as a subcolumn, as long as the paths fit in the count
+  v VARIANT<properties('variant_max_subcolumns_count' = '2048')>
+  ```
+
+  From version 4.2, this meaning applies to every statement that creates a 
table, including `CREATE TABLE`, `CREATE TABLE LIKE` and `CREATE TABLE AS 
SELECT`. A column created before version 4.2 keeps its old behavior: `0` sends 
every dynamic path through Subcolumnization, with no limit. `SHOW CREATE TABLE` 
marks a VARIANT column with a comment after its type: `/* 
variant_serialize_type = v1 */` for a column created before version 4.2 and `/* 
variant_serialize_type = v2 */` for one create [...]
+
+  ```sql
+  -- Version 4.1
+  CREATE TABLE old_t (
+      k INT,
+      v VARIANT<properties('variant_max_subcolumns_count' = '0')>
+  )
+  DUPLICATE KEY(k) DISTRIBUTED BY HASH(k) BUCKETS 1;
+  INSERT INTO old_t VALUES (1, PARSE_TO_VARIANT('{"a": 1, "b": "x"}'));
+
+  -- After upgrading to version 4.2: new_t has the same definition as old_t, 
with a count of 0
+  CREATE TABLE new_t LIKE old_t;
+  INSERT INTO new_t SELECT * FROM old_t;
+
+  SET describe_extend_variant_column = true;
+  DESC old_t;  -- lists the subcolumns v.a and v.b, because old_t keeps the 
old meaning
+  DESC new_t;  -- lists no subcolumn, because new_t stores a and b in sparse 
columns
+  SHOW CREATE TABLE old_t;  -- the type of v is followed by /* 
variant_serialize_type = v1 */
+  SHOW CREATE TABLE new_t;  -- the type of v is followed by /* 
variant_serialize_type = v2 */
+  ```
+
+  When `CREATE TABLE AS SELECT` stores a VARIANT that the query computes, such 
as `PARSE_TO_VARIANT(...)`, `TRY_PARSE_TO_VARIANT(...)` or a subpath `v['a']`, 
in a new column, the column takes the `variant_max_subcolumns_count` of the 
expression's type: `0` for `PARSE_TO_VARIANT` and `TRY_PARSE_TO_VARIANT`, so 
every dynamic path is stored in sparse columns, and the count of the source 
column for a subpath. To get the default limit, cast the expression to VARIANT; 
`CAST(PARSE_TO_VARIANT(s) [...]
+- Sparse columns support sharding: distribute sparse subpaths across multiple 
sparse columns to reduce per-column read overhead and improve read efficiency. 
Use `variant_doc_hash_shard_count` to specify how many sparse columns are 
physically stored. Versions 4.0 and 4.1 set this shard count with 
`variant_sparse_hash_shard_count`; from version 4.2 it is still accepted, but 
its value is ignored.
+
+:::caution Rollback
+After upgrading to version 4.2, once a new VARIANT column is created, do not 
roll back to a version before 4.2. New columns are stored with the 4.2 behavior 
described on this page: for example, a version before 4.2 reads the `0` of a 
new column with `variant_max_subcolumns_count = 0` as no limit, and its 
compaction drops the paths that are stored only in sparse columns. These 
statements create new VARIANT columns:
+
+- `CREATE TABLE` with a VARIANT column.
+- `CREATE TABLE LIKE`, or the output of `SHOW CREATE TABLE` run again, for a 
table with a VARIANT column, also one created before version 4.2.
+- `CREATE TABLE AS SELECT` whose result has a VARIANT column.
+- `ALTER TABLE ... ADD COLUMN` of a VARIANT column, also on a table created 
before version 4.2.
+- An async materialized view with a VARIANT column.
+
+In `SHOW CREATE TABLE`, a new column is marked `/* variant_serialize_type = v2 
*/`.
+:::
 
 **Reference notes**
 
 - If most keys have similar non-null ratios (little sparsity contrast), it’s 
hard to identify truly sparse paths and the benefit of sparse columns is 
reduced.
 - `variant_max_subcolumns_count` defaults to `2048`, which is already enough 
for most workloads. Avoid raising it aggressively just to pre-allocate more 
extracted subcolumns; if the workload truly needs large-scale Subcolumnization, 
prefer [DOC mode](./variant-workload-guide.md#doc-mode-template). The practical 
upper bound is still recommended to stay ≤ `10000`.
-- `variant_sparse_hash_shard_count` can be roughly estimated as “number of 
sparse paths / 128”. Example: total JSON keys ≈ 10,000, 
`variant_max_subcolumns_count = 2000`, then sparse paths ≈ 8000, so 
`variant_sparse_hash_shard_count` can start around `8000/128`.
+- `variant_doc_hash_shard_count` can be roughly estimated as “number of sparse 
paths / 128”. Example: total JSON keys ≈ 10,000, `variant_max_subcolumns_count 
= 2000`, then sparse paths ≈ 8000, so `variant_doc_hash_shard_count` can start 
around `8000/128`.
 
 ### DOC encoding (DOC mode)
 
 **How it works**
 
-- Paths can still go through Subcolumnization for path-based queries, and the 
original JSON is additionally stored as a stored field to return the full JSON 
document efficiently.
+- Paths can still go through Subcolumnization for path-based queries, up to 
`variant_max_subcolumns_count` paths, and the original JSON is additionally 
stored as a stored field to return the full JSON document efficiently.
 - DOC encoding supports sharding: the original JSON is split into multiple 
columns for storage and reassembled when querying the full JSON. Use 
`variant_doc_hash_shard_count` to specify the number of DOC shards.
 - For small-batch writes, Subcolumnization can be skipped and deferred to 
later merges. This is controlled by `variant_doc_materialization_min_rows`. For 
example, if `variant_doc_materialization_min_rows = 10000`, writes below 10,000 
rows will only store the original JSON and won’t trigger Subcolumnization for 
that batch.
 - For ultra-wide workloads, DOC mode is also the more stable choice when 
Subcolumnization scale approaches ten-thousand subcolumns. Compared with 
default eager Subcolumnization, compaction memory can drop by about two-thirds, 
and sparse wide-column ingest throughput can improve by about 5-10x.
@@ -774,7 +817,10 @@ CREATE TABLE example_table (
 
 - DOC mode requires `variant_enable_doc_mode = true`.
 - In DOC mode, Schema Template fields are limited to strings, integers, 
`FLOAT`, `DOUBLE`, `BOOLEAN`, and arrays of these types.
-- `variant_doc_hash_shard_count` can be roughly estimated as “total JSON keys 
/ 128”.
+- With DOC mode, `variant_doc_hash_shard_count` can be roughly estimated as 
“total JSON keys / 128”.
+- A new DOC mode column has `1` shard by default (64 before version 4.2).
+- From version 4.2, `variant_doc_hash_shard_count` sets the shard count with 
and without DOC mode. The `SHOW CREATE TABLE` output of a DOC mode table 
created before version 4.2 runs and keeps its shard count; it does not state 
`variant_max_subcolumns_count`, so the new column extracts at most `2048` paths 
unless you state it.
+- A DOC mode column created before version 4.2 keeps its old behavior: once a 
data file reaches the row threshold, every path is extracted, and the column 
keeps the shard count it was created with.
 
 ### Behavior at limits and tuning suggestions
 
diff --git 
a/docs/sql-manual/basic-element/sql-data-types/semi-structured/variant-storage-tuning.md
 
b/docs/sql-manual/basic-element/sql-data-types/semi-structured/variant-storage-tuning.md
new file mode 100644
index 00000000000..608a967c697
--- /dev/null
+++ 
b/docs/sql-manual/basic-element/sql-data-types/semi-structured/variant-storage-tuning.md
@@ -0,0 +1,255 @@
+---
+{
+    "title": "VARIANT Storage and Tuning",
+    "language": "en",
+    "description": "How VARIANT stores JSON paths as subcolumns or in sparse 
encoding, and how to set its subcolumn limit, row threshold and DOC mode for 
each scenario."
+}
+---
+
+VARIANT stores and queries JSON without defining every field in advance. To 
balance query speed against write cost, Doris extracts some frequently 
occurring fields into subcolumns of their own and stores the other fields in 
sparse encoding, which balances storage space and performance. Users still 
access all of the data through the same VARIANT column.
+
+Basic VARIANT tuning answers three questions: how many subcolumns to extract 
at most, when to extract them, and whether to also keep the complete document. 
With few fields, extract early to get the benefit of columnar queries. With a 
very large number of fields, limit or defer the extraction to control the cost 
of loads and compaction.
+
+## 1. How VARIANT stores and reads data
+
+### 1.1 One JSON document, two ways to store its fields
+
+Suppose there are three event records:
+
+```json
+{"user_id": 101, "action": "click", "campaign_a": 7, "experiment_a": "A", 
"tag_a": "new"}
+{"user_id": 102, "action": "view",  "device_flag": true, "os_name": "iOS", 
"tag_b": "returning"}
+{"user_id": 103, "action": "click", "experiment_b": "B", "source_page": 
"home", "device_model": "M1"}
+```
+
+`user_id` and `action` appear in every record; the other fields appear only in 
some records. With an extraction limit of 2, the layout can look like this:
+
+<img src="/images/variant/variant-subcolumns-and-sparse-encoding.png" 
alt="user_id and action are extracted into subcolumns, the other paths are kept 
in sparse encoding per record" width="720" />
+
+"Sparse encoding" here means that the paths that are not extracted, together 
with their values, are encoded into sparse columns; queries can still read them 
by path. The Doris table itself still uses columnar storage.
+
+A subcolumn organizes the data of one path as a column. A query of 
`payload['user_id']` reads that subcolumn and does not read the other business 
fields. Fields that are not extracted can still be queried by path, but the 
paths and values in the sparse encoding have to be parsed, which usually means 
reading and processing more data.
+
+Therefore, **the extraction limit controls the physical storage layout, not 
the total number of JSON fields that can be written.** Paths beyond the limit 
are stored in sparse encoding; they are not dropped or rejected just because 
they exceed the limit.
+
+The system chooses the candidates for automatic extraction from the path 
statistics of the data. "Frequent" here refers to how often a field occurs in 
the data; the system does not identify business hot spots from the history of 
SQL queries.
+
+### 1.2 Three basic properties: how many, when, and whether to keep the 
complete document
+
+| Property | Question it answers | Main effect of changing it |
+| --- | --- | --- |
+| `variant_max_subcolumns_count` | How many subcolumns are extracted at most? 
| A larger limit gives more paths the chance to be stored as columns, and adds 
write, metadata and compaction cost; `0` turns automatic extraction off |
+| `variant_doc_materialization_min_rows` | When does automatic extraction 
start? | A higher threshold saves the extraction work for data files with few 
rows; path queries on that data may read more from the sparse encoding |
+| `variant_enable_doc_mode` | Is the complete document also kept? | When 
enabled, queries of whole documents read the document representation directly; 
this adds storage and write cost |
+
+The three independent examples below show how the properties change the 
result. The values explain the rules; they are not recommended defaults.
+
+**How many: `variant_max_subcolumns_count`.** Suppose a data file that 
qualifies for extraction has 20 distinct paths. With 
`variant_max_subcolumns_count` set to `2`, at most 2 subcolumns are extracted 
and at least the other 18 paths are stored in sparse encoding. With `8`, at 
most 8 are extracted and at least the other 12 paths stay in sparse encoding. 
With `0`, nothing is extracted automatically and all 20 paths are stored in 
sparse encoding, except paths declared in a Schema Template, [...]
+
+:::note
+`0` turns automatic extraction off only for columns created by version 4.2 or 
later. A column created before version 4.2 keeps its behavior after the 
upgrade: `0` means no limit, and every dynamic path is extracted into a 
subcolumn. See [Sparse columns](./VARIANT.md#sparse-columns).
+:::
+
+**When: `variant_doc_materialization_min_rows`.** With 
`variant_doc_materialization_min_rows = 0`, extraction is tried when data is 
written. With `1000000`, a data file of 500,000 rows is written without 
automatic extraction, and extraction is tried when a later compaction writes a 
data file of 1,200,000 rows. This property decides when extraction happens, not 
how many subcolumns are extracted in the end. Despite the doc in its name, it 
applies without DOC mode too; before version 4.2 it [...]
+
+**Whether to keep the complete document: `variant_enable_doc_mode`.** Suppose 
`payload` already has 128 extracted subcolumns and queries often run `SELECT 
payload`. With `variant_enable_doc_mode = false`, the whole document has to be 
rebuilt from the subcolumns and the data in the sparse encoding. With 
`variant_enable_doc_mode = true`, Doris also stores a complete representation 
of the document and queries read it directly, at the cost of more storage space 
and write work.
+
+The row threshold is evaluated for each single data file to be written; it 
does not apply to the cumulative rows of the table or to the total rows of one 
load job. Loads and compaction follow the same threshold and the same subcolumn 
limit; dynamic paths that do not meet the row condition or exceed the subcolumn 
limit are stored in sparse encoding. Different data files may end up with 
different subcolumn layouts.
+
+### 1.3 The query pattern decides the value of extraction
+
+Subcolumns usually pay off when queries read only a few paths. For example:
+
+```sql
+SELECT
+    CAST(payload['action'] AS STRING) AS action,
+    COUNT(*)
+FROM events
+GROUP BY CAST(payload['action'] AS STRING);
+```
+
+To return the complete JSON, query the whole VARIANT column. For example, to 
fetch the record with `user_id = 101` from the sample data above:
+
+```sql
+SELECT payload
+FROM events
+WHERE CAST(payload['user_id'] AS BIGINT) = 101;
+```
+
+The filter can read the `user_id` subcolumn, but `SELECT payload` has to 
restore the complete document of the row. Without a copy of the complete 
document, Doris also reads the `action` subcolumn and `campaign_a`, 
`experiment_a` and `tag_a` from the sparse encoding, and merges these paths and 
values into one JSON result. If a document has thousands of extracted 
subcolumns, returning the whole document reads and merges more subcolumns as 
well.
+
+So more subcolumns help queries that access only a few paths, and also add 
write and compaction cost. When `SELECT payload` is frequent, also weigh the 
cost of rebuilding whole documents and whether to enable 
`variant_enable_doc_mode`.
+
+## 2. Choose a configuration by scenario
+
+The examples below use append-only event data, with complete `CREATE TABLE` 
statements and typical queries, to show how to choose a configuration. 
`DUPLICATE KEY` suits the append-only writes of the examples; `BUCKETS 8` is 
only an example value for a medium-sized table, so choose the number of buckets 
by the data volume and the size of the cluster. The examples omit partitions 
and the number of replicas and use the defaults of the cluster.
+
+### 2.1 A moderate number of fields: columnar queries on frequently used paths
+
+**Data.** A user behavior event has dozens of fairly stable fields, such as 
`user_id`, `event_type`, `duration_ms` and `page`. Most records have these 
fields, and analytical queries access a few of the paths again and again. For 
example, a `payload` is 
`{"user_id":101,"event_type":"click","duration_ms":35,"page":"home"}`.
+
+**Table.** Try extraction when data is written, and give dynamic paths a 
limited subcolumn budget:
+
+```sql
+CREATE TABLE event_analysis (
+    event_time DATETIME NOT NULL,
+    event_id   BIGINT NOT NULL,
+    payload    VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "128",
+        "variant_doc_materialization_min_rows" = "0",
+        "variant_enable_doc_mode" = "false"
+    )>
+)
+DUPLICATE KEY(event_time, event_id)
+DISTRIBUTED BY HASH(event_id) BUCKETS 8;
+```
+
+**Typical query.** Count the events of each event type within one day that 
take at least 30 milliseconds, reading only the paths the query uses:
+
+```sql
+SELECT CAST(payload['event_type'] AS STRING) AS event_type,
+       COUNT(*) AS event_count
+FROM event_analysis
+WHERE event_time >= '2026-11-04 00:00:00'
+  AND event_time <  '2026-11-05 00:00:00'
+  AND CAST(payload['duration_ms'] AS BIGINT) >= 30
+GROUP BY CAST(payload['event_type'] AS STRING);
+```
+
+`variant_doc_materialization_min_rows = 0` means extraction is not deferred 
because of the number of rows in a data file; `variant_max_subcolumns_count = 
128` means at most 128 dynamic subcolumns are extracted. Once the queried paths 
are subcolumns, a higher limit usually does not make them faster. Consider a 
larger limit only when more frequently queried paths are still in sparse 
encoding and path queries become the bottleneck.
+
+Compare query latency, scanned data and load throughput with the actual filter 
and aggregation SQL; do not choose the subcolumn limit from the number of JSON 
keys alone.
+
+### 2.2 Sparse wide tables: extract common fields, keep long-tail fields in 
sparse encoding
+
+**Data.** All device records together have tens of thousands of attributes, 
but each record has only a few dozen. Fields such as `region` and `model` 
appear in most records, while fields such as `sensor_x17` and `firmware_ext_b` 
appear only on a few devices. For example, two records contain 
`{"region":"east","model":"M1","sensor_x17":8.2}` and 
`{"region":"west","model":"M2","firmware_ext_b":"r7"}`. The table is "wide" 
because the union of paths is large, not because each record is large.
+
+Creating a subcolumn for every path produces a large number of sparse physical 
columns. Every subcolumn still needs its share of write, metadata and 
compaction work, even if it holds only a few values.
+
+**Table.** Limit the number of automatic subcolumns, so that common fields can 
be stored as columns and long-tail fields are stored in sparse encoding:
+
+```sql
+CREATE TABLE device_events_sparse (
+    event_time DATETIME NOT NULL,
+    device_id  BIGINT NOT NULL,
+    attributes VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "128",
+        "variant_doc_materialization_min_rows" = "0",
+        "variant_enable_doc_mode" = "false"
+    )>
+)
+DUPLICATE KEY(event_time, device_id)
+DISTRIBUTED BY HASH(device_id) BUCKETS 8;
+```
+
+**Typical queries.** Business reports mostly aggregate by common paths, and 
occasionally read a long-tail path of a single device:
+
+```sql
+SELECT CAST(attributes['region'] AS STRING) AS region,
+       COUNT(*) AS event_count
+FROM device_events_sparse
+WHERE event_time >= '2026-11-04 00:00:00'
+  AND event_time <  '2026-11-05 00:00:00'
+GROUP BY CAST(attributes['region'] AS STRING);
+
+SELECT device_id,
+       CAST(attributes['sensor_x17'] AS DOUBLE) AS sensor_x17
+FROM device_events_sparse
+WHERE device_id = 101;
+```
+
+Suppose a data file has 20,000 distinct paths. With a limit of 128, the vast 
majority of long-tail paths are stored in sparse encoding. If `region` occurs 
frequently, it is more likely to become a subcolumn; if `sensor_x17` occurs 
only in a few records, reading it usually parses the data in the sparse 
encoding. The automatic choice follows the distribution of paths in the data, 
not how often the SQL above runs.
+
+If the business really needs more paths stored as columns, compare limits such 
as 128, 512 and 1024. A higher limit may speed up frequently queried paths, and 
may also add pressure on loads, metadata and compaction.
+
+### 2.3 Very wide records and slow loads: defer or turn off automatic 
extraction
+
+**Data.** Every collected record has thousands of fields. For example, the 
`payload` of a device snapshot holds `source` and `metric_0001` to 
`metric_5000`, and `snapshot_id` is a separate column of the table. Most 
`metric_*` fields are rarely used in filters, and with small batches written 
continuously, building subcolumns or the following compaction already slows 
down the loads. This differs from the sparse scenario of the previous section, 
where the union of paths across the table is  [...]
+
+First decide between two goals: no extraction only while small batches are 
written, or no automatic extraction for the whole life of the data.
+
+**Goal 1: no extraction for data files with few rows, extraction once they 
reach a threshold.** Raise the row threshold when creating the table:
+
+```sql
+CREATE TABLE wide_snapshots_deferred (
+    snapshot_time DATETIME NOT NULL,
+    snapshot_id   BIGINT NOT NULL,
+    payload       VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "128",
+        "variant_doc_materialization_min_rows" = "1000",
+        "variant_enable_doc_mode" = "false"
+    )>
+)
+DUPLICATE KEY(snapshot_time, snapshot_id)
+DISTRIBUTED BY HASH(snapshot_id) BUCKETS 8;
+```
+
+For example, when a data file of 500 rows is written, the dynamic paths are 
first stored in sparse encoding; extraction is tried when a later compaction 
produces a data file of 1,200 rows, and at most 128 subcolumns are extracted. 
When each row is very wide, a data file usually holds fewer rows, so `1000` is 
only an example threshold; adjust it to the actual number of rows and the row 
width of your data files.
+
+**Goal 2: no automatic extraction for the whole life of the data.** Set the 
subcolumn limit to `0`:
+
+```sql
+CREATE TABLE wide_snapshots_row_only (
+    snapshot_time DATETIME NOT NULL,
+    snapshot_id   BIGINT NOT NULL,
+    payload       VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "0",
+        "variant_doc_materialization_min_rows" = "0",
+        "variant_enable_doc_mode" = "false"
+    )>
+)
+DUPLICATE KEY(snapshot_time, snapshot_id)
+DISTRIBUTED BY HASH(snapshot_id) BUCKETS 8;
+```
+
+Neither loads nor compaction extract dynamic subcolumns, and the paths are 
stored in sparse encoding. This saves the extraction work on very wide data; 
filters and aggregations by path then have to parse the data in the sparse 
encoding and may be slower. Whether `variant_enable_doc_mode` also keeps the 
complete document is a separate setting.
+
+**Typical query.** Both tables can run the SQL below; replace the table name 
to compare the configurations:
+
+```sql
+SELECT snapshot_id,
+       CAST(payload['source'] AS STRING) AS source
+FROM wide_snapshots_deferred
+WHERE snapshot_time >= '2026-11-04 00:00:00'
+  AND snapshot_time <  '2026-11-05 00:00:00'
+  AND CAST(payload['source'] AS STRING) = 'collector-a';
+```
+
+Compare three configurations: immediate extraction, deferred extraction, and 
automatic extraction turned off. Record the query latency right after the loads 
and after compaction, and under continuous writes record the throughput, the 
compaction cost and the size on disk; measuring only the speed of a short load 
may miss the background cost.
+
+### 2.4 Complete JSON returned often: decide whether to keep a copy of the 
complete document
+
+Take the three event records from before: every `payload` has `user_id` and 
`action`, and each also has its own campaign, device or experiment fields. The 
application often finds a record by `user_id` and returns the whole `payload`, 
and also aggregates by `action`.
+
+<img src="/images/variant/variant-doc-mode-full-document.png" alt="With DOC 
mode, the sparse encoding keeps the complete payload of every record, while 
user_id and action are also extracted into subcolumns" width="720" />
+
+**Table.** Set the automatic subcolumn limit to `2`, assuming `user_id` and 
`action` are extracted into subcolumns. `variant_enable_doc_mode = true` makes 
the sparse encoding keep all paths and values of every record, including the 
extracted `user_id` and `action`:
+
+```sql
+CREATE TABLE event_documents (
+    event_id BIGINT NOT NULL,
+    payload  VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "2",
+        "variant_doc_materialization_min_rows" = "0",
+        "variant_enable_doc_mode" = "true"
+    )>
+)
+DUPLICATE KEY(event_id)
+DISTRIBUTED BY HASH(event_id) BUCKETS 8;
+```
+
+**Typical query.** Filter by `user_id` and return the complete document:
+
+```sql
+SELECT payload
+FROM event_documents
+WHERE CAST(payload['user_id'] AS BIGINT) = 101;
+```
+
+If `user_id` and `action` are already subcolumns, the filter of this SQL can 
read the `user_id` subcolumn, and `payload` is returned by reading the complete 
document from the sparse encoding directly.
+
+## 3. Advanced settings
+
+**`variant_doc_hash_shard_count`: the number of shards of the sparse 
encoding.** This property sets the number of physical shards that the sparse 
encoding uses; paths that are not extracted are mapped to a shard by hash. The 
default is 1. It is unrelated to the BUCKETS of the table and to the number of 
tablets. With `variant_enable_doc_mode`, the complete document is split into 
the same number of shards. Despite the doc in its name, it applies without DOC 
mode too; versions 4.0 and 4.1 s [...]
+
+For example, 18 long-tail paths are stored in sparse encoding. With `4`, these 
paths are mapped to 4 available shards; with `16`, to 16 available shards. To 
query one long-tail path, Doris can locate the shard that holds it and read 
less data of other paths. Querying a whole document may still read several 
shards.
diff --git 
a/docs/sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide.md
 
b/docs/sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide.md
index d9fed41af12..5747530e613 100644
--- 
a/docs/sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide.md
+++ 
b/docs/sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide.md
@@ -16,7 +16,7 @@ Use this guide when you are deciding how to model a new 
`VARIANT` workload. It h
 - If the JSON is very wide, should I start with default behavior, sparse 
columns, or DOC mode?
 - Which settings should I leave at defaults, and which ones should I change 
first?
 
-If you already know you want `VARIANT` and only need syntax or type rules, go 
to [VARIANT](./VARIANT.md). If you want the smallest runnable import example, 
go to [Import Variant 
Data](../../../../data-operate/import/complex-types/variant.md).
+If you already know you want `VARIANT` and only need syntax or type rules, go 
to [VARIANT](./VARIANT.md). If you want the smallest runnable import example, 
go to [Import Variant 
Data](../../../../data-operate/import/complex-types/variant.md). To understand 
how subcolumns and sparse encoding store data, and how to set the properties 
for each scenario, see [VARIANT Storage and 
Tuning](./variant-storage-tuning.md).
 
 :::tip Why choose VARIANT
 `VARIANT` keeps JSON flexible, but Doris can still apply Subcolumnization to 
frequently used paths. That lets common filters, aggregations, and path-level 
indexes work well without freezing the whole document schema in advance. On 
very wide JSON, storage-layer optimizations keep Subcolumnization practical at 
much larger path counts.
@@ -76,15 +76,15 @@ Before reading the storage modes below, make sure these 
terms are clear. Each is
 
 As shown above, hot paths (such as `user_id`, `page`) stay as independent 
columnar subcolumns with full analytics speed, while thousands of long-tail 
paths converge into shared sparse storage. The threshold is controlled by 
`variant_max_subcolumns_count`.
 
-**Sparse sharding.** When the long-tail path count is very large, a single 
sparse column can become a read bottleneck. Sparse sharding distributes 
long-tail paths by hash across multiple physical columns 
(`variant_sparse_hash_shard_count`), so they can be scanned in parallel.
+**Sparse sharding.** When the long-tail path count is very large, a single 
sparse column can become a read bottleneck. Sparse sharding distributes 
long-tail paths by hash across multiple physical columns 
(`variant_doc_hash_shard_count`), so they can be scanned in parallel.
 
 <img src="/images/variant/variant-sparse-sharding.png" alt="Sparse Sharding: 
Parallel Read for Long-Tail Paths" width="720" />
 
-**DOC mode.** Delays Subcolumnization at write time and additionally stores 
the original JSON as a map-format stored field (the **doc map**). This gives 
fast ingest and efficient whole-document return at the cost of extra storage. 
Subcolumnization still happens later during compaction.
+**DOC mode.** Additionally stores the original JSON as a map-format stored 
field (the **doc map**), which whole-document queries read directly, at the 
cost of extra storage. As in the default mode, Subcolumnization is controlled 
by `variant_max_subcolumns_count` and `variant_doc_materialization_min_rows`: 
once a data file reaches the row threshold, at most 
`variant_max_subcolumns_count` paths are extracted. With a larger row 
threshold, small batches only write the doc map, which speeds u [...]
 
 <img src="/images/variant/variant-doc-mode.png" alt="DOC Mode: Deferred 
Extraction + Fast Document Return" width="700" />
 
-As illustrated above, during write the JSON is preserved as-is into a Doc 
Store for fast ingest. Subcolumns are extracted later during compaction. At 
read time, path-based queries (e.g. `SELECT v['user_id']`) read from 
materialized subcolumns at full columnar speed, while whole-document queries 
(`SELECT v`) read directly from the Doc Store without reconstructing from 
subcolumns.
+As illustrated above, during write the JSON is preserved as-is into a Doc 
Store for fast ingest. When a row threshold is set, subcolumns are extracted 
later during compaction. At read time, path-based queries (e.g. `SELECT 
v['user_id']`) read from materialized subcolumns at full columnar speed, while 
whole-document queries (`SELECT v`) read directly from the Doc Store without 
reconstructing from subcolumns.
 
 DOC mode has three distinct read paths depending on whether the queried path 
has been materialized:
 
@@ -107,8 +107,8 @@ Use the table below to pick a starting point, then read the 
matching section.
 | | Typical scenario | Recommended mode | Key configuration |
 |---|---|---|---|
 | **A** | Event logs, audit logs | Default VARIANT + V3 | Keep defaults |
-| **B** | Advertising / telemetry / user profiles (wide, hot paths few) | 
Sparse + V3 | `variant_max_subcolumns_count`, `variant_sparse_hash_shard_count` 
|
-| **C** | Model output / trace / archives (ingest-first or whole-doc return) | 
DOC mode + V3 | `variant_enable_doc_mode`, 
`variant_doc_materialization_min_rows` |
+| **B** | Advertising / telemetry / user profiles (wide, hot paths few) | 
Sparse + V3 | `variant_max_subcolumns_count`, `variant_doc_hash_shard_count` |
+| **C** | Model output / trace / archives (ingest-first or whole-doc return) | 
DOC mode + V3 | `variant_enable_doc_mode`, 
`variant_doc_materialization_min_rows`, `variant_doc_hash_shard_count` |
 | **D** | Orders / payments / devices (key paths need stable types) | Schema 
Template + A or B | Define only key paths |
 
 ### Default Mode
@@ -153,7 +153,7 @@ CREATE TABLE IF NOT EXISTS telemetry_wide (
         'region' : STRING,
         properties(
             'variant_max_subcolumns_count' = '2048',
-            'variant_sparse_hash_shard_count' = '64'
+            'variant_doc_hash_shard_count' = '64'
         )
     >
 )
@@ -211,7 +211,8 @@ Use it when ingest throughput is the first priority, the 
workload frequently nee
 
 Watch for:
 - DOC mode is not the default answer for every wide-JSON workload. If hot-path 
analytics dominates, sparse columns usually fit better.
-- DOC mode and sparse columns are mutually exclusive. They cannot be enabled 
at the same time.
+- DOC mode can be set together with `variant_max_subcolumns_count` and 
`variant_doc_hash_shard_count`; see [VARIANT Storage and 
Tuning](./variant-storage-tuning.md).
+- The default shard count of DOC mode (`variant_doc_hash_shard_count`) is `1`. 
When queries often read paths of very wide JSON that are not materialized yet, 
set the shard count explicitly, such as `64` in the example above.
 - Apart from `DROP`, `RENAME`, and comment changes, a column that has a Schema 
Template cannot be altered, so its `variant_doc_materialization_min_rows` 
cannot change later. Choose the value when you create the table.
 
 ### Schema Template
diff --git a/docs/table-design/index/inverted-index/search-function.md 
b/docs/table-design/index/inverted-index/search-function.md
index 65506e70d99..3b1d64fda29 100644
--- a/docs/table-design/index/inverted-index/search-function.md
+++ b/docs/table-design/index/inverted-index/search-function.md
@@ -482,7 +482,7 @@ ORDER BY id;
 -- A VARIANT column with an inverted index
 CREATE TABLE test_variant_search_subcolumn (
     id BIGINT,
-    properties VARIANT<PROPERTIES("variant_max_subcolumns_count"="0")>,
+    properties VARIANT<PROPERTIES("variant_max_subcolumns_count"="2048")>,
     INDEX idx_properties (properties) USING INVERTED PROPERTIES (
         "parser" = "unicode",
         "lower_case" = "true",
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 3d68b9f5cc8..49bd051311b 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
@@ -538,7 +538,7 @@ v1 VARIANT<
 > NULL
 ```
 
-匹配成功的路径默认参与子列列式提取(Subcolumnization)。如果匹配的路径过多、生成了过多子列,可以考虑开启 
`variant_enable_typed_paths_to_sparse`(参见[列属性](#column-properties))。
+匹配成功的路径始终参与子列列式提取(Subcolumnization),且不计入 
`variant_max_subcolumns_count`,因此请避免使用会匹配大量路径的过宽通配符。
 
 列创建后不能修改 Schema Template,参见 [ALTER TABLE](#alter-table)。
 
@@ -556,7 +556,7 @@ ALTER TABLE example_tbl ADD COLUMN `v.x` VARIANT;
 - `ADD COLUMN` 新增可为 NULL 的 VARIANT 列,可以带 Schema Template 和属性。
 - `DROP COLUMN`、`RENAME COLUMN` 和 `MODIFY COLUMN ... COMMENT '...'`。
 - `ADD INDEX` 和 `DROP INDEX`。带 `field_pattern` 的索引只能在 `CREATE TABLE` 中定义。
-- 对没有 Schema Template 的列:把 `NOT NULL` 改为 `NULL`,以及修改 
`variant_doc_materialization_min_rows`。`MODIFY COLUMN` 
需要给出完整的列定义,未写出的属性取默认值(参见[列属性](#column-properties)),因此取值与默认值不同的属性都要写出。
+- 对没有 Schema Template 的列:把 `NOT NULL` 改为 `NULL`,以及修改 
`variant_doc_materialization_min_rows`(4.2 版本之前创建、没有开启 DOC mode 且 
`variant_max_subcolumns_count = 0` 的列只能保持 `0`)。`MODIFY COLUMN` 
需要给出完整的列定义,未写出的属性取默认值(参见[列属性](#column-properties)),因此取值与默认值不同的属性都要写出。
 
 不支持:
 
@@ -588,8 +588,7 @@ CREATE TABLE example_table (
       'path_2' : STRING,
       properties(
           'variant_max_subcolumns_count' = '2048',
-          'variant_enable_typed_paths_to_sparse' = 'true',
-          'variant_sparse_hash_shard_count' = '64'
+          'variant_doc_hash_shard_count' = '64'
       )
   >
 );
@@ -597,13 +596,12 @@ CREATE TABLE example_table (
 
 | 属性 | 默认值 | ALTER | 描述 |
 | --- | --- | --- | --- |
-| `variant_max_subcolumns_count` | `2048` | 否 | 
单个数据文件中参与子列列式提取(Subcolumnization)的动态路径数上限;非空值多的路径优先入选,其余路径存入稀疏列。`0` 表示不限制。取值范围 
0 到 100000,建议不超过 10000。默认值已足够覆盖大多数 workload;如果确实需要大规模子列,优先考虑 [DOC 
mode](./variant-workload-guide.md#doc-mode-template)。 |
-| `variant_enable_typed_paths_to_sparse` | `false` | 否 | 默认情况下,Schema Template 
路径一定参与子列列式提取,且不计入 `variant_max_subcolumns_count`。设置为 `true` 
后,这些路径也计入上限,并可能存入稀疏列。 |
-| `variant_sparse_hash_shard_count` | `1` | 否 | 稀疏路径按 Hash 分散到的物理稀疏列数量。取值范围 0 
到 1024,`0` 按 `1` 处理。 |
+| `variant_max_subcolumns_count` | `2048` | 否 | 
单个数据文件中参与子列列式提取(Subcolumnization)的动态路径数上限;非空值多的路径优先入选,其余路径存入稀疏列。`0` 
表示动态路径都不参与子列列式提取(Subcolumnization),全部存入稀疏列;4.2 版本之前创建的列中 `0` 
仍表示不限制,参见[稀疏列机制](#sparse-columns)。取值范围 0 到 100000,建议不超过 10000。默认值已足够覆盖大多数 
workload;如果确实需要大规模子列,优先考虑 [DOC 
mode](./variant-workload-guide.md#doc-mode-template)。 |
+| `variant_enable_typed_paths_to_sparse` | `false` | 否 | 4.2 
版本起不能设置:列定义中写出该属性会报错,取值为 `false` 也一样。Schema Template 路径一定参与子列列式提取,且不计入 
`variant_max_subcolumns_count`。4.2 版本之前设置为 `true` 的列保持原样:这些路径计入上限,并可能存入稀疏列。4.2 
版本之前的 `SHOW CREATE TABLE` 会为每个没有开启 DOC mode 的 VARIANT 列输出该属性,执行这些输出前需要删掉它;输出中的 
`variant_sparse_hash_shard_count` 会被忽略,需要保留分片数时请改为 
`variant_doc_hash_shard_count`。 |
+| `variant_doc_hash_shard_count` | `1` | 否 | 稀疏路径按 Hash 分散到的物理稀疏列数量;开启 DOC 
mode 时,为存储的文档被拆分到的列数。取值范围 0 到 1024,`0` 按 `1` 处理。4.2 版本之前只在开启 DOC mode 时生效。 |
 | `variant_max_sparse_column_statistics_size` | `10000` | 否 | 
单个数据文件中记录统计信息的稀疏路径数上限。超过后,查询没有统计信息的路径时无法跳过稀疏列。取值范围 1 到 50000。 |
-| `variant_enable_doc_mode` | `false` | 否 | 开启 DOC mode。不能与 
`variant_max_subcolumns_count`、`variant_enable_typed_paths_to_sparse`、`variant_max_sparse_column_statistics_size`、`variant_sparse_hash_shard_count`
 同时设置。 |
-| `variant_doc_materialization_min_rows` | `0` | 仅限没有 Schema Template 的列 | 仅用于 
DOC mode。行数少于该值的写入只存储文档,待 Compaction 把文件合并到该阈值后再执行子列列式提取。`0` 
表示写入时即执行子列列式提取。取值范围 0 到 1000000000。 |
-| `variant_doc_hash_shard_count` | `64` | 否 | 仅用于 DOC mode。存储的文档被拆分到的列数。取值范围 0 
到 1024,`0` 按 `1` 处理。 |
+| `variant_enable_doc_mode` | `false` | 否 | 开启 DOC mode,额外保存完整文档。可以与 
`variant_max_subcolumns_count`、`variant_doc_materialization_min_rows`、`variant_doc_hash_shard_count`
 同时设置,不能与 `variant_max_sparse_column_statistics_size` 同时设置。 |
+| `variant_doc_materialization_min_rows` | `0` | 仅限没有 Schema Template 的列 | 
行数少于该值的数据文件不执行子列列式提取,动态路径存入稀疏列(开启 DOC mode 时只存储文档),待 Compaction 
写出的数据文件达到该阈值后再执行。`0` 表示写入时即执行子列列式提取。取值范围 0 到 1000000000。4.2 版本之前只在开启 DOC mode 
时生效。 |
 
 表中 **ALTER** 列表示 `ALTER TABLE ... MODIFY COLUMN` 能否修改该属性,参见 [ALTER 
TABLE](#alter-table)。稀疏列和 DOC mode 相关属性的用法参见[宽列](#wide-columns)。
 
@@ -722,6 +720,7 @@ CREATE TABLE IF NOT EXISTS tbl (
    );
    SELECT * FROM tbl WHERE v_str MATCH 'Doris';
    ```
+4. 路径存储在稀疏列中:子路径索引依赖子列。超出 `variant_max_subcolumns_count` 
的路径没有子列;`variant_max_subcolumns_count = 0` 时,所有动态路径都没有子列;行数少于 
`variant_doc_materialization_min_rows` 的数据文件也没有动态子列,直到 Compaction 
写出的数据文件达到该阈值。路径没有子列时,`SEARCH()` 会报错 “SEARCH index unavailable for Variant 
field”,`MATCH` 默认回退为读取值逐行匹配(`enable_match_without_inverted_index = false` 
时报错)。可以用 Schema Template 固定路径,或参见[稀疏列机制](#sparse-columns)。
 
 ## 宽列 {#wide-columns}
 
@@ -729,27 +728,71 @@ CREATE TABLE IF NOT EXISTS tbl (
 
 如果你要决定什么时候选 Sparse、什么时候选 DOC mode,请先看 [VARIANT 
使用与配置指南](./variant-workload-guide.md)。本节只说明机制本身及其相关属性。
 
-注意:这两种机制**互斥**——启用 DOC 编码后将无法使用稀疏列机制,反之亦然。
+开启 DOC 
编码时,`variant_max_subcolumns_count`、`variant_doc_materialization_min_rows` 和 
`variant_doc_hash_shard_count` 同样生效:最多提取 `variant_max_subcolumns_count` 
个路径,其余路径从文档中读取;`variant_max_sparse_column_statistics_size` 不能与 DOC 
编码同时设置。各参数在不同场景下的取值参见 [VARIANT 存储原理与场景调优](./variant-storage-tuning.md)。
 
 ### 稀疏列机制 {#sparse-columns}
 
 **机制说明**
 
 - 系统会按“非空比例/稀疏度”对路径排序:高频(不稀疏)路径优先执行子列列式提取(Subcolumnization),并存为独立子列;可执行 
Subcolumnization 的最大子列数量由 `variant_max_subcolumns_count` 
指定,其余低频(稀疏)路径会被合并存放到稀疏列中。
-- 在 Schema Template 中声明过的路径,默认不会被放入稀疏列;可通过 
`variant_enable_typed_paths_to_sparse` 允许这些路径进入稀疏列。
-- 稀疏列支持 sharding:通过将稀疏子路径分散到多个稀疏列中,降低单列读取负担、提升读取效率;可通过 
`variant_sparse_hash_shard_count` 指定稀疏列的实际存储个数。
+- 在 Schema Template 中声明过的路径不会被放入稀疏列(4.2 版本之前设置了 
`variant_enable_typed_paths_to_sparse = true` 的列除外)。
+- 设置 `variant_max_subcolumns_count = 0` 时,所有动态路径都存入稀疏列;Schema Template 
路径仍参与子列列式提取(Subcolumnization)。适合值主要被整体读取的场景。如果希望所有动态路径都参与子列列式提取(Subcolumnization),比如要保留它们的子路径索引,请把该值设置得比不同路径的数量更大:
+  ```sql
+  -- 所有动态路径都在稀疏列中
+  v VARIANT<properties('variant_max_subcolumns_count' = '0')>
+
+  -- 所有动态路径都成为子列(路径数量不超过该值时)
+  v VARIANT<properties('variant_max_subcolumns_count' = '2048')>
+  ```
+
+  从 4.2 版本起,任何建表语句中的 `0` 都是这个语义,包括 `CREATE TABLE`、`CREATE TABLE LIKE` 和 
`CREATE TABLE AS SELECT`。4.2 版本之前创建的列保持原有行为:`0` 
表示所有动态路径都参与子列列式提取(Subcolumnization),不限制数量。`SHOW CREATE TABLE` 在 VARIANT 
列的类型后面用注释标出列的行为:`/* variant_serialize_type = v1 */` 表示 4.2 版本之前创建的列,`/* 
variant_serialize_type = v2 */` 表示 4.2 版本起创建的列。注释只用于查看,执行这段输出时会被忽略,建出的总是新列。
+
+  ```sql
+  -- 4.1 版本
+  CREATE TABLE old_t (
+      k INT,
+      v VARIANT<properties('variant_max_subcolumns_count' = '0')>
+  )
+  DUPLICATE KEY(k) DISTRIBUTED BY HASH(k) BUCKETS 1;
+  INSERT INTO old_t VALUES (1, PARSE_TO_VARIANT('{"a": 1, "b": "x"}'));
+
+  -- 升级到 4.2 版本后:new_t 的定义与 old_t 相同,count 也是 0
+  CREATE TABLE new_t LIKE old_t;
+  INSERT INTO new_t SELECT * FROM old_t;
+
+  SET describe_extend_variant_column = true;
+  DESC old_t;  -- 列出子列 v.a 和 v.b,因为 old_t 保持原有语义
+  DESC new_t;  -- 不列出子列,因为 new_t 把 a 和 b 存入稀疏列
+  SHOW CREATE TABLE old_t;  -- v 的类型后面是 /* variant_serialize_type = v1 */
+  SHOW CREATE TABLE new_t;  -- v 的类型后面是 /* variant_serialize_type = v2 */
+  ```
+
+  `CREATE TABLE AS SELECT` 把查询计算出的 VARIANT(如 
`PARSE_TO_VARIANT(...)`、`TRY_PARSE_TO_VARIANT(...)`、子路径 
`v['a']`)存为新列时,`variant_max_subcolumns_count` 取表达式类型的值:`PARSE_TO_VARIANT` 和 
`TRY_PARSE_TO_VARIANT` 为 `0`,动态路径都存入稀疏列;子路径取源列的值。需要默认上限时,把表达式 CAST 为 VARIANT,例如 
`CAST(PARSE_TO_VARIANT(s) AS VARIANT)` 的上限为 `2048`。
+- 稀疏列支持 sharding:通过将稀疏子路径分散到多个稀疏列中,降低单列读取负担、提升读取效率;可通过 
`variant_doc_hash_shard_count` 指定稀疏列的实际存储个数。4.0、4.1 版本用 
`variant_sparse_hash_shard_count` 设置这个分片数;4.2 版本起它仍可写出,但值会被忽略。
+
+:::caution 回滚
+升级到 4.2 版本后,一旦创建了新的 VARIANT 列,就不能再回滚到 4.2 之前的版本。新列按本页描述的 4.2 语义存储:例如 
`variant_max_subcolumns_count` 为 `0` 的新列,旧版本会把 `0` 当作不限制,它的 Compaction 
会丢掉只保存在稀疏列中的路径。以下方式都会创建新的 VARIANT 列:
+
+- `CREATE TABLE` 定义 VARIANT 列。
+- `CREATE TABLE LIKE`,或重新执行 `SHOW CREATE TABLE` 的输出,表中有 VARIANT 列,包括复制 4.2 
版本之前创建的表。
+- `CREATE TABLE AS SELECT` 的结果中有 VARIANT 列。
+- `ALTER TABLE ... ADD COLUMN` 新增 VARIANT 列,在 4.2 版本之前创建的表上新增也一样。
+- 新建的异步物化视图中有 VARIANT 列。
+
+`SHOW CREATE TABLE` 中标有 `/* variant_serialize_type = v2 */` 的列就是新列。
+:::
 
 **参考说明**
 
 - JSON key 总量大,但各个 JSON key 
的“非空比例/稀疏度”都比较接近、缺乏区分度:这种情况下很难区分哪些列是真正稀疏的,稀疏列机制的效果会被降低。
 - `variant_max_subcolumns_count` 默认就是 `2048`,已经足够覆盖大多数 
workload。不要为了预留更多自动提取子列而激进调大;如果场景确实需要大规模子列列式提取(Subcolumnization),优先参考 [DOC 
mode](./variant-workload-guide.md#doc-mode-template)。实践上仍建议不超过 **10000**。
-- `variant_sparse_hash_shard_count` 的设置可按“进入稀疏列的总列数 / 128”粗略估算。例如:VARIANT 中所有 
JSON key 为 1 万,设置 `variant_max_subcolumns_count = 2000`,进入稀疏列的总列数约为 8000,则 
`variant_sparse_hash_shard_count` 可参考 `8000/128`。
+- `variant_doc_hash_shard_count` 的设置可按“进入稀疏列的总列数 / 128”粗略估算。例如:VARIANT 中所有 
JSON key 为 1 万,设置 `variant_max_subcolumns_count = 2000`,进入稀疏列的总列数约为 8000,则 
`variant_doc_hash_shard_count` 可参考 `8000/128`。
 
 ### DOC 编码机制 {#doc-encoding-doc-mode}
 
 **机制说明**
 
-- 子路径仍可执行子列列式提取(Subcolumnization)用于按路径查询,同时会额外保存一份“原始 JSON”作为存储字段,以便更快返回整条 
JSON 文档。
+- 子路径仍可执行子列列式提取(Subcolumnization)用于按路径查询,最多提取 `variant_max_subcolumns_count` 
个路径,同时会额外保存一份“原始 JSON”作为存储字段,以便更快返回整条 JSON 文档。
 - DOC 编码支持 sharding:原始 JSON 会被拆分到多个列中存储,读取整条 JSON 时再组装这些分片;可通过 
`variant_doc_hash_shard_count` 指定 DOC 编码的实际分片数。
 - 小批量写入时可以暂不执行子列列式提取(Subcolumnization),后续合并时再触发:该行为由 
`variant_doc_materialization_min_rows` 决定。例如 
`variant_doc_materialization_min_rows = 10000`,当写入行数低于 1 万时,该批次只写入原始 JSON,不会触发 
Subcolumnization。
 - 对超宽列 workload,DOC mode 也是更稳定的选择,尤其是在 Subcolumnization 规模接近万列时。相比默认的即时 
Subcolumnization,compaction 内存可下降约 2/3,在稀疏宽列导入场景下导入性能可提升约 5~10 倍。
@@ -774,7 +817,10 @@ CREATE TABLE example_table (
 
 - 需开启 `variant_enable_doc_mode`。
 - DOC mode 下,Schema Template 字段只能是字符串、整数、`FLOAT`、`DOUBLE`、`BOOLEAN` 
以及由这些类型组成的数组。
-- `variant_doc_hash_shard_count` 的设置可按 “JSON key 的总个数 / 128” 粗略估算。
+- 开启 DOC mode 时,`variant_doc_hash_shard_count` 的设置可按 “JSON key 的总个数 / 128” 
粗略估算。
+- 新建的 DOC mode 列默认分片数为 `1`(4.2 版本之前为 64)。
+- 4.2 版本起,`variant_doc_hash_shard_count` 在开启和不开启 DOC mode 时都生效。4.2 版本之前创建的 DOC 
mode 表,其 `SHOW CREATE TABLE` 输出可以直接执行,分片数保持原值;这样的输出没有写出 
`variant_max_subcolumns_count`,因此建出的新列最多提取 `2048` 个路径,需要其他取值时请写出 
`variant_max_subcolumns_count`。
+- 4.2 版本之前创建的 DOC mode 列保持原有行为:数据文件达到行数阈值后提取所有路径,分片数保持建表时的值。
 
 ### 达到上限后的行为与调优建议 {#behavior-at-limits-and-tuning-suggestions}
 
diff --git 
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/variant-storage-tuning.md
 
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/variant-storage-tuning.md
new file mode 100644
index 00000000000..c4a3de54b90
--- /dev/null
+++ 
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/variant-storage-tuning.md
@@ -0,0 +1,255 @@
+---
+{
+    "title": "VARIANT 存储原理与场景调优",
+    "language": "zh-CN",
+    "description": "VARIANT 如何把 JSON 路径拆成独立子列或采用稀疏编码保存,以及如何按场景设置 
variant_max_subcolumns_count、variant_doc_materialization_min_rows 和 
variant_enable_doc_mode。"
+}
+---
+
+VARIANT 可以在不预先定义所有字段的情况下存储和查询 JSON。为了兼顾字段查询速度与写入成本,Doris 
将一部分高频出现的字段拆成独立子列,其余字段采用稀疏编码保存,兼顾存储空间与性能。用户仍然通过同一个 VARIANT 列访问这些数据。
+
+VARIANT 
的基本调优需要回答三个问题:最多自动拆多少个子列、什么时候拆列,以及是否额外保留完整文档。字段较少时,可以尽早拆列,获得列式查询的收益;字段非常多时,可以限制或推迟拆列,控制导入和
 Compaction 的开销。
+
+## 1. VARIANT 如何存储和读取数据
+
+### 1.1 一份 JSON,两种字段存储方式
+
+假设三条事件记录如下:
+
+```json
+{"user_id": 101, "action": "click", "campaign_a": 7, "experiment_a": "A", 
"tag_a": "new"}
+{"user_id": 102, "action": "view",  "device_flag": true, "os_name": "iOS", 
"tag_b": "returning"}
+{"user_id": 103, "action": "click", "experiment_b": "B", "source_page": 
"home", "device_model": "M1"}
+```
+
+`user_id` 和 `action` 每条记录都出现,其他字段只在部分记录中出现。如果自动拆列上限为 2,可以形成以下布局:
+
+<img src="/images/variant/variant-subcolumns-and-sparse-encoding.png" 
alt="user_id 和 action 拆成独立子列,其余路径按记录采用稀疏编码保存" width="720" />
+
+这里的“稀疏编码”指将未拆列路径及其值合并编码到稀疏列中,查询仍可按路径读取。Doris 表本身仍采用列式存储。
+
+独立子列让同一个路径的数据按列组织。查询 `payload['user_id']` 
时,可以读取对应子列,避免读取其他业务字段。未拆列的字段仍可按路径查询,但需要解析稀疏编码中的路径和值,通常会读取和处理更多数据。
+
+因此,**拆列上限控制的是物理存储布局,不是允许写入的 JSON 字段总数。** 超过上限的路径采用稀疏编码保存,不会仅仅因为超过该上限而被丢弃或拒绝写入。
+
+系统根据数据中的路径统计选择自动拆列的候选字段。这里的“高频”指字段在数据中的出现情况,不意味着系统根据 SQL 访问历史自动识别业务热点。
+
+### 1.2 三个基本参数:拆多少、何时拆、是否保留完整文档
+
+| 参数 | 回答的问题 | 调整后的主要影响 |
+| --- | --- | --- |
+| `variant_max_subcolumns_count` | 最多自动拆多少个子列? | 
增大上限,让更多路径有机会独立列存,同时增加写入、元数据与合并开销;`0` 表示关闭自动拆列 |
+| `variant_doc_materialization_min_rows` | 什么时候开始自动拆列? | 
提高阈值,减少行数较少的数据文件的自动拆列工作;这些数据的路径查询可能更多地读取稀疏编码中的数据 |
+| `variant_enable_doc_mode` | 是否额外保留完整文档? | 开启后,整条文档查询可以直接读取文档表示;同时增加存储与写入开销 |
+
+下面用三个独立的例子说明参数变化。示例值用于解释规则,不是推荐默认值。
+
+**拆多少:`variant_max_subcolumns_count`。** 假设某个满足拆列条件的数据文件中有 20 个不同路径。将 
`variant_max_subcolumns_count` 设为 `2` 时,最多自动拆出 2 个子列,其余至少 18 个路径采用稀疏编码保存;调到 `8` 
后,最多可以自动拆出 8 个,其余至少 12 个路径仍采用稀疏编码保存。设为 `0` 时,不自动拆列,20 个路径都采用稀疏编码保存;Schema 
Template 中声明的路径除外,它们仍然拆成独立子列。
+
+:::note
+`0` 表示关闭自动拆列,只适用于 4.2 及以后版本创建的列。4.2 之前创建的列在升级后保持原有行为:`0` 
表示不限制子列数量,所有动态路径都拆成独立子列。参见 [稀疏列机制](./VARIANT.md#sparse-columns)。
+:::
+
+**什么时候拆:`variant_doc_materialization_min_rows`。** 
`variant_doc_materialization_min_rows = 0` 时,写入时就尝试自动拆列;设为 `1000000` 时,写出一个 50 
万行的数据文件暂不自动拆列,后续 Compaction 写出 120 万行的数据文件时才尝试自动拆列。这个参数决定拆列时机,不决定最终拆出多少列。参数名中带有 
doc,但不开启 DOC mode 时同样生效;4.2 版本之前它只在 DOC mode 下生效。
+
+**是否保留完整文档:`variant_enable_doc_mode`。** 假设 `payload` 已经拆出 128 个子列,查询经常执行 
`SELECT payload`。`variant_enable_doc_mode = false` 
时,整条文档需要从子列和稀疏编码中的数据重组;`variant_enable_doc_mode = true` 时,Doris 
额外保存一份完整文档表示,查询可以直接读取它,代价是更多存储空间和写入工作。
+
+这里的行数阈值按待写出的单个数据文件计算,不能按全表累计行数或一次导入任务的总行数判断。导入与 Compaction 
都遵守同一阈值和子列上限;不满足行数条件或超过子列上限的动态路径采用稀疏编码保存。不同数据文件可能形成不同的子列布局。
+
+### 1.3 查询方式决定拆列的价值
+
+只读取少数路径时,独立子列通常更有优势。例如:
+
+```sql
+SELECT
+    CAST(payload['action'] AS STRING) AS action,
+    COUNT(*)
+FROM events
+GROUP BY CAST(payload['action'] AS STRING);
+```
+
+如果要返回完整 JSON,可以查询整个 VARIANT 列。例如,从前面的示例数据中取出 `user_id = 101` 的记录:
+
+```sql
+SELECT payload
+FROM events
+WHERE CAST(payload['user_id'] AS BIGINT) = 101;
+```
+
+过滤条件可以读取 `user_id` 子列;但 `SELECT payload` 需要还原该行的完整文档。没有完整文档副本时,Doris 还要读取 
`action` 子列,以及稀疏编码中的 `campaign_a`、`experiment_a`、`tag_a`,再将这些路径和值合并成一个 JSON 
结果。若一份文档拆出了上千个子列,返回整条文档时需要读取和重组的子列也会增多。
+
+因此,增加子列有利于只访问少数路径的查询,也会增加写入和 Compaction 成本;对于经常执行 `SELECT payload` 
的场景,还要评估整条文档的重组开销,以及是否启用 `variant_enable_doc_mode`。
+
+## 2. 按场景选择配置
+
+下面的例子以追加写入的事件数据为背景,使用完整的 `CREATE TABLE` 和典型查询说明如何选配置。`DUPLICATE KEY` 
适合示例中的追加写入;`BUCKETS 8` 仅作为中等规模表的示例值,实际分桶数应按数据量和集群规模调整。示例省略分区与副本数配置,沿用集群默认值。
+
+### 2.1 字段规模适中:让常用路径获得列式查询收益
+
+**数据特征。** 一条用户行为事件包含几十个较稳定的字段,例如 
`user_id`、`event_type`、`duration_ms`、`page`。多数记录都有这些字段,分析查询反复访问其中几个路径。例如一条 
`payload` 为 
`{"user_id":101,"event_type":"click","duration_ms":35,"page":"home"}`。
+
+**建表配置。** 写入时就尝试自动拆列,并给动态路径一个有限的子列预算:
+
+```sql
+CREATE TABLE event_analysis (
+    event_time DATETIME NOT NULL,
+    event_id   BIGINT NOT NULL,
+    payload    VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "128",
+        "variant_doc_materialization_min_rows" = "0",
+        "variant_enable_doc_mode" = "false"
+    )>
+)
+DUPLICATE KEY(event_time, event_id)
+DISTRIBUTED BY HASH(event_id) BUCKETS 8;
+```
+
+**典型查询。** 按事件类型统计一天内耗时不少于 30 毫秒的事件数,并只读取查询涉及的路径:
+
+```sql
+SELECT CAST(payload['event_type'] AS STRING) AS event_type,
+       COUNT(*) AS event_count
+FROM event_analysis
+WHERE event_time >= '2026-11-04 00:00:00'
+  AND event_time <  '2026-11-05 00:00:00'
+  AND CAST(payload['duration_ms'] AS BIGINT) >= 30
+GROUP BY CAST(payload['event_type'] AS STRING);
+```
+
+`variant_doc_materialization_min_rows = 0` 
表示不因数据文件行数推迟自动拆列;`variant_max_subcolumns_count = 128` 表示最多自动拆出 128 
个动态子列。如果查询路径已成为独立子列,继续提高上限通常不会让这些路径变得更快。只有更多常查路径仍采用稀疏编码、路径查询成为瓶颈时,才考虑扩大上限。
+
+用实际过滤和聚合 SQL 比较查询延迟、扫描量与导入吞吐,不要仅凭 JSON 的 key 数决定子列上限。
+
+### 2.2 稀疏宽表:常见字段拆列,长尾字段采用稀疏编码保存
+
+**数据特征。** 所有设备记录合计有数万种属性,但每条记录只有几十种。`region`、`model` 
等字段大多出现,`sensor_x17`、`firmware_ext_b` 等字段只在少数设备上出现。例如两条记录分别含有 
`{"region":"east","model":"M1","sensor_x17":8.2}` 和 
`{"region":"west","model":"M2","firmware_ext_b":"r7"}`。这里的“宽”来自路径并集很大,不代表每条记录都很大。
+
+为所有路径创建独立子列,会产生大量稀疏的物理列。每个子列仍然需要相应的写入、元数据和合并处理,即使它只包含少量有效值。
+
+**建表配置。** 限制自动子列数量,让常见字段有机会独立列存,长尾字段采用稀疏编码保存:
+
+```sql
+CREATE TABLE device_events_sparse (
+    event_time DATETIME NOT NULL,
+    device_id  BIGINT NOT NULL,
+    attributes VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "128",
+        "variant_doc_materialization_min_rows" = "0",
+        "variant_enable_doc_mode" = "false"
+    )>
+)
+DUPLICATE KEY(event_time, device_id)
+DISTRIBUTED BY HASH(device_id) BUCKETS 8;
+```
+
+**典型查询。** 业务报表主要按常见路径统计,也偶尔按单个设备读取长尾路径:
+
+```sql
+SELECT CAST(attributes['region'] AS STRING) AS region,
+       COUNT(*) AS event_count
+FROM device_events_sparse
+WHERE event_time >= '2026-11-04 00:00:00'
+  AND event_time <  '2026-11-05 00:00:00'
+GROUP BY CAST(attributes['region'] AS STRING);
+
+SELECT device_id,
+       CAST(attributes['sensor_x17'] AS DOUBLE) AS sensor_x17
+FROM device_events_sparse
+WHERE device_id = 101;
+```
+
+假设某个数据文件中有 2 万种路径,128 的上限使绝大多数长尾路径采用稀疏编码保存。`region` 
如果出现频率高,就更有机会成为独立子列;`sensor_x17` 如果只出现在少量记录中,通常解析稀疏编码中的数据。自动选择依据是数据中的路径分布,不是上述 
SQL 的调用次数。
+
+如果业务确实需要更多路径列存,可对比 128、512、1024 等上限。上限升高,常查路径可能获益,导入、元数据和 Compaction 的压力也可能增加。
+
+### 2.3 单条记录很宽、导入慢:推迟或关闭自动拆列
+
+**数据特征。** 每条采集记录都包含数千个字段,例如一份设备快照的 `payload` 含 `source` 和 `metric_0001` 到 
`metric_5000`,`snapshot_id` 则作为表中的独立列。多数 `metric_*` 很少用于过滤;小批次持续写入时,子列构建或后续 
Compaction 已经拖慢导入。这与上节“全表路径并集很大、单行却很窄”的稀疏场景不同。
+
+先区分两个目标:小批次写入时暂时不拆列,还是整个数据生命周期都不自动拆列。
+
+**目标一:行数较少的数据文件暂不拆列,达到阈值后再拆。** 建表时提高行数阈值:
+
+```sql
+CREATE TABLE wide_snapshots_deferred (
+    snapshot_time DATETIME NOT NULL,
+    snapshot_id   BIGINT NOT NULL,
+    payload       VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "128",
+        "variant_doc_materialization_min_rows" = "1000",
+        "variant_enable_doc_mode" = "false"
+    )>
+)
+DUPLICATE KEY(snapshot_time, snapshot_id)
+DISTRIBUTED BY HASH(snapshot_id) BUCKETS 8;
+```
+
+例如写出 500 行的数据文件时,动态路径先采用稀疏编码保存;后续 Compaction 生成 1200 行的数据文件时,才尝试自动拆列,最多拆出 128 
个子列。单行很宽时,数据文件能容纳的行数通常更少,`1000` 只是示例阈值,应结合实际数据文件行数和行宽调整。
+
+**目标二:整个生命周期都不自动拆列。** 按目标设计,将子列上限设为 `0`:
+
+```sql
+CREATE TABLE wide_snapshots_row_only (
+    snapshot_time DATETIME NOT NULL,
+    snapshot_id   BIGINT NOT NULL,
+    payload       VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "0",
+        "variant_doc_materialization_min_rows" = "0",
+        "variant_enable_doc_mode" = "false"
+    )>
+)
+DUPLICATE KEY(snapshot_time, snapshot_id)
+DISTRIBUTED BY HASH(snapshot_id) BUCKETS 8;
+```
+
+导入和 Compaction 
都不自动拆出动态子列,路径采用稀疏编码保存。它可以减少超宽数据的拆列工作;按路径过滤或聚合时则需要解析稀疏编码中的数据,可能变慢。`variant_enable_doc_mode`
 是否额外保留完整文档是另一项独立设置。
+
+**典型查询。** 两种表都可执行下列 SQL;替换表名即可对比配置效果:
+
+```sql
+SELECT snapshot_id,
+       CAST(payload['source'] AS STRING) AS source
+FROM wide_snapshots_deferred
+WHERE snapshot_time >= '2026-11-04 00:00:00'
+  AND snapshot_time <  '2026-11-05 00:00:00'
+  AND CAST(payload['source'] AS STRING) = 'collector-a';
+```
+
+对比即时拆列、推迟拆列和关闭自动拆列三组配置。分别记录导入刚结束与 Compaction 后的查询延迟,并在持续写入时记录吞吐、Compaction 
开销和落盘大小;只测短时间导入速度,可能漏掉后台成本。
+
+### 2.4 经常返回完整 JSON:评估是否保留完整文档副本
+
+沿用之前的三条事件记录:`payload` 中都有 `user_id` 和 `action`,同时各自带有不同的活动、设备或实验字段。应用经常按 
`user_id` 找到记录并返回整个 `payload`,也会按 `action` 做统计。
+
+<img src="/images/variant/variant-doc-mode-full-document.png" alt="开启 DOC mode 
后,稀疏编码保存每条记录的完整 payload,user_id 和 action 同时拆成独立子列" width="720" />
+
+**建表配置。** 将自动子列上限设为 `2`,假设 `user_id` 和 `action` 
被拆为独立子列。`variant_enable_doc_mode = true` 使稀疏编码保存每条记录的全部路径和值,包括已经拆出的 `user_id` 和 
`action`:
+
+```sql
+CREATE TABLE event_documents (
+    event_id BIGINT NOT NULL,
+    payload  VARIANT<PROPERTIES(
+        "variant_max_subcolumns_count" = "2",
+        "variant_doc_materialization_min_rows" = "0",
+        "variant_enable_doc_mode" = "true"
+    )>
+)
+DUPLICATE KEY(event_id)
+DISTRIBUTED BY HASH(event_id) BUCKETS 8;
+```
+
+**典型查询。** 用 `user_id` 过滤后返回完整文档:
+
+```sql
+SELECT payload
+FROM event_documents
+WHERE CAST(payload['user_id'] AS BIGINT) = 101;
+```
+
+如果 `user_id` 和 `action` 已成为独立子列,这条 SQL 的过滤条件可以读取 `user_id` 子列,返回 `payload` 
时则直接读取稀疏编码中的完整文档。
+
+## 3. 高级设置
+
+**`variant_doc_hash_shard_count`:调整稀疏编码的分片数。** 这个参数控制稀疏编码使用的物理分片数,未拆列路径按 hash 
映射到对应分片,默认值为 1。它与表的 BUCKETS、Tablet 数量无关。开启 `variant_enable_doc_mode` 
时,完整文档同样按这个分片数拆分存储。参数名中带有 doc,但不开启 DOC mode 时同样生效;4.0、4.1 版本不开启 DOC mode 时用 
`variant_sparse_hash_shard_count` 设置分片数,4.2 版本起它的值会被忽略。
+
+例如,有 18 个长尾路径采用稀疏编码保存。设置为 `4` 时,这些路径映射到 4 个可用 shard;设置为 `16` 时,映射到 16 个可用 
shard。查询一个长尾路径时,Doris 可以定位它所在的 shard,减少读取其他路径的数据。查询整条文档仍可能需要读取多个 shard。
diff --git 
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide.md
 
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide.md
index 943c0a8febc..b4c13c969fc 100644
--- 
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide.md
+++ 
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide.md
@@ -16,7 +16,7 @@
 - JSON 很宽时,应该先用默认模式、Sparse,还是 DOC mode?
 - 哪些配置先保持默认,哪些配置才值得优先调整?
 
-如果你已经确定要使用 `VARIANT`,只是想查语法或类型规则,请直接看 
[VARIANT](./VARIANT.md)。如果你只需要一个最小可运行的导入示例,请看 [导入 Variant 
数据](../../../../data-operate/import/complex-types/variant.md)。
+如果你已经确定要使用 `VARIANT`,只是想查语法或类型规则,请直接看 
[VARIANT](./VARIANT.md)。如果你只需要一个最小可运行的导入示例,请看 [导入 Variant 
数据](../../../../data-operate/import/complex-types/variant.md)。如果想了解子列和稀疏编码的存储原理,以及各参数在不同场景下怎么取值,请看
 [VARIANT 存储原理与场景调优](./variant-storage-tuning.md)。
 
 :::tip 为什么使用 VARIANT
 `VARIANT` 保留了 JSON 
的灵活性,同时又能让常用路径通过子列列式提取(Subcolumnization)获得类似普通列的裁剪、聚合和索引能力,不必先把整份文档固化成静态 
schema。对超宽 JSON,存储层优化也让更大规模的 Subcolumnization 保持可控。
@@ -76,15 +76,15 @@
 
 如上图所示,热点路径(如 `user_id`、`page`)继续以独立列式子列的形式保持高性能分析能力,而数千个长尾路径则汇入共享稀疏存储。阈值通过 
`variant_max_subcolumns_count` 控制。
 
-**Sparse sharding(稀疏分片)。** 
当长尾路径数量非常大时,单个稀疏列可能成为读取瓶颈。稀疏分片通过哈希将长尾路径分散到多个物理列(`variant_sparse_hash_shard_count`),从而可以并行扫描。
+**Sparse sharding(稀疏分片)。** 
当长尾路径数量非常大时,单个稀疏列可能成为读取瓶颈。稀疏分片通过哈希将长尾路径分散到多个物理列(`variant_doc_hash_shard_count`),从而可以并行扫描。
 
 <img src="/images/variant/variant-sparse-sharding.png" alt="Sparse 
Sharding:长尾路径并行读取" width="720" />
 
-**DOC mode。** 写入时延迟子列列式提取(Subcolumnization),并额外存储一份 map 格式的原始 JSON(即 **doc 
map**)。这带来了快速导入和高效整条文档返回能力,代价是额外存储。后续 Compaction 时仍会完成 Subcolumnization。
+**DOC mode。** 额外存储一份 map 格式的原始 JSON(即 **doc 
map**),整条文档查询直接读取它,代价是额外存储。子列列式提取(Subcolumnization)与默认模式一样由 
`variant_max_subcolumns_count` 和 `variant_doc_materialization_min_rows` 
控制:数据文件达到行数阈值后,最多提取 `variant_max_subcolumns_count` 个路径。调大行数阈值时,小批量写入只写 doc 
map,导入更快,Subcolumnization 推迟到后续 Compaction。
 
 <img src="/images/variant/variant-doc-mode.png" alt="DOC Mode:延迟提取 + 快速文档返回" 
width="700" />
 
-如上图所示,写入时 JSON 被原样保存到 Doc Store 以实现快速导入。子列在后续 Compaction 过程中提取。读取时,按路径查询(如 
`SELECT v['user_id']`)从物化子列中以列式速度读取;而整条文档查询(`SELECT v`)则直接从 Doc Store 
中读取,无需从大量子列重组文档。
+如上图所示,写入时 JSON 被原样保存到 Doc Store 以实现快速导入。设置了行数阈值时,子列在后续 Compaction 
过程中提取。读取时,按路径查询(如 `SELECT v['user_id']`)从物化子列中以列式速度读取;而整条文档查询(`SELECT v`)则直接从 
Doc Store 中读取,无需从大量子列重组文档。
 
 DOC mode 的读取路径取决于被查询的路径是否已经物化:
 
@@ -107,8 +107,8 @@ DOC mode 的读取路径取决于被查询的路径是否已经物化:
 | | 典型场景 | 推荐模式 | 关键配置 |
 |---|---|---|---|
 | **A** | 事件日志、审计日志 | 默认 VARIANT + V3 | 保持默认 |
-| **B** | 广告/遥测/用户画像(宽、热点少) | Sparse + V3 | 
`variant_max_subcolumns_count`、`variant_sparse_hash_shard_count` |
-| **C** | 模型输出/Trace/归档(写入优先或整条返回) | DOC mode + V3 | 
`variant_enable_doc_mode`、`variant_doc_materialization_min_rows` |
+| **B** | 广告/遥测/用户画像(宽、热点少) | Sparse + V3 | 
`variant_max_subcolumns_count`、`variant_doc_hash_shard_count` |
+| **C** | 模型输出/Trace/归档(写入优先或整条返回) | DOC mode + V3 | 
`variant_enable_doc_mode`、`variant_doc_materialization_min_rows`、`variant_doc_hash_shard_count`
 |
 | **D** | 订单/支付/设备(关键路径需稳定类型) | Schema Template + A 或 B | 只定义关键路径 |
 
 ### 默认模式
@@ -153,7 +153,7 @@ CREATE TABLE IF NOT EXISTS telemetry_wide (
         'region' : STRING,
         properties(
             'variant_max_subcolumns_count' = '2048',
-            'variant_sparse_hash_shard_count' = '64'
+            'variant_doc_hash_shard_count' = '64'
         )
     >
 )
@@ -211,7 +211,8 @@ PROPERTIES (
 
 注意:
 - DOC mode 不是所有宽 JSON 场景的默认答案。若核心诉求是热点路径分析,通常还是 Sparse 更合适。
-- DOC mode 和 Sparse 互斥,不能同时开启。
+- DOC mode 可以与 `variant_max_subcolumns_count`、`variant_doc_hash_shard_count` 
一起设置,参见 [VARIANT 存储原理与场景调优](./variant-storage-tuning.md)。
+- DOC mode 的默认分片数(`variant_doc_hash_shard_count`)为 `1`。超宽 JSON 
中经常查询尚未物化的路径时,请显式设置分片数,例如上面示例中的 `64`。
 - 带 Schema Template 的列除了 `DROP`、`RENAME` 和修改注释之外不能 ALTER,因此之后也无法修改它的 
`variant_doc_materialization_min_rows`,请在建表时确定这个值。
 
 ### Schema Template 模式
diff --git 
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/index/inverted-index/search-function.md
 
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/index/inverted-index/search-function.md
index 5bdd192ba28..a4351292ebb 100644
--- 
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/index/inverted-index/search-function.md
+++ 
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/table-design/index/inverted-index/search-function.md
@@ -482,7 +482,7 @@ ORDER BY id;
 -- 带 VARIANT 列与倒排索引
 CREATE TABLE test_variant_search_subcolumn (
     id BIGINT,
-    properties VARIANT<PROPERTIES("variant_max_subcolumns_count"="0")>,
+    properties VARIANT<PROPERTIES("variant_max_subcolumns_count"="2048")>,
     INDEX idx_properties (properties) USING INVERTED PROPERTIES (
         "parser" = "unicode",
         "lower_case" = "true",
diff --git a/sidebars.ts b/sidebars.ts
index 9020d80f7e0..b6cd67cfc8c 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -1373,6 +1373,7 @@ const sidebars: SidebarsConfig = {
                                                     id: 
'sql-manual/basic-element/sql-data-types/semi-structured/variant-workload-guide',
                                                     label: 'VARIANT Internal',
                                                 },
+                                                
'sql-manual/basic-element/sql-data-types/semi-structured/variant-storage-tuning',
                                             ],
                                         },
                                     ],
diff --git a/static/images/variant/variant-doc-mode-full-document.png 
b/static/images/variant/variant-doc-mode-full-document.png
new file mode 100644
index 00000000000..cc1f1afc6ad
Binary files /dev/null and 
b/static/images/variant/variant-doc-mode-full-document.png differ
diff --git a/static/images/variant/variant-subcolumns-and-sparse-encoding.png 
b/static/images/variant/variant-subcolumns-and-sparse-encoding.png
new file mode 100644
index 00000000000..c655ba4c550
Binary files /dev/null and 
b/static/images/variant/variant-subcolumns-and-sparse-encoding.png differ


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to