This is an automated email from the ASF dual-hosted git repository.
morningman 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 b36e0362ce6 [doc] add FAQ on DECIMAL precision loss when writing into
VARIANT (#3669)
b36e0362ce6 is described below
commit b36e0362ce635d6f46eec8182c55da93c3636dd4
Author: Chenyang Sun <[email protected]>
AuthorDate: Tue May 19 11:05:45 2026 +0800
[doc] add FAQ on DECIMAL precision loss when writing into VARIANT (#3669)
Document why DECIMAL values lose trailing decimals when written into a
VARIANT column: VARIANT does not infer DECIMAL during subcolumn type
inference and stores numbers as DOUBLE, and even a Schema Template
DECIMAL declaration does not fully guarantee precision because the write
path parses the value as DOUBLE before converting to DECIMAL. Added to
dev and 4.x, EN and ZH.
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [ ] Chinese
- [ ] English
- [ ] Japanese candidate translation needed
## 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 4.7 (1M context) <[email protected]>
---
docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md | 2 ++
.../sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md | 2 ++
.../sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md | 2 ++
.../sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md | 2 ++
4 files changed, 8 insertions(+)
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 0dc473d6335..46856616e28 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
@@ -578,3 +578,5 @@ ClickBench (43 queries):
- No. They are equivalent.
2. Why doesn’t my query/index work?
- Check whether you CAST paths to the correct types; whether the type was
promoted to JSONB due to conflicts; or whether you mistakenly expect an index
on the whole VARIANT instead of on subpaths.
+3. Why does DECIMAL lose precision when written into a VARIANT column?
+ - When writing to a VARIANT column, the subcolumn type is not inferred as
DECIMAL — numeric values are stored as DOUBLE, which can drop trailing
decimals. Even declaring the subpath as DECIMAL via the Schema Template (e.g.
`pm25 VARIANT<'xxx': DECIMAL(6, 2)>`) does not fully guarantee precision,
because the value is first parsed as DOUBLE and then converted to DECIMAL on
the write path. If the JSON value is written as a string (e.g. `'{"num":
"12.345"}'`) together with a matching Sche [...]
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 679fec86212..a13a39bcaa8 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
@@ -578,3 +578,5 @@ DESCRIBE ${table_name} PARTITION ($partition_name);
- 没有区别，两者等价。
2. 为什么我的查询/索引没有生效？
- 请检查是否对路径做了正确的 CAST、是否因为类型冲突被提升为 JSONB、或是否误以为给 VARIANT“整体”建的索引可用于子列。
+3. 为什么 DECIMAL 写入 VARIANT 列时出现小数位/精度丢失？
+ - 写入 VARIANT 列时，在推断子列类型时不会推断为 DECIMAL，数值会以 DOUBLE 存储，因而可能丢失末位小数。即使通过 Schema
Template 将子路径显式声明为 DECIMAL（例如 `pm25 VARIANT<'xxx': DECIMAL(6, 2)>`），写入路径也会先解析为
DOUBLE 再转换为 DECIMAL，仍不能完全保证精度。如果在 JSON 中将该字段写成字符串形式（例如 `'{"num":
"12.345"}'`），并配合 Schema Template 声明为对应的 DECIMAL（例如 `DECIMAL(9,
3)`），写入时会直接由字符串解析为 DECIMAL，可以保证精度。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 679fec86212..a13a39bcaa8 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -578,3 +578,5 @@ DESCRIBE ${table_name} PARTITION ($partition_name);
- 没有区别，两者等价。
2. 为什么我的查询/索引没有生效？
- 请检查是否对路径做了正确的 CAST、是否因为类型冲突被提升为 JSONB、或是否误以为给 VARIANT“整体”建的索引可用于子列。
+3. 为什么 DECIMAL 写入 VARIANT 列时出现小数位/精度丢失？
+ - 写入 VARIANT 列时，在推断子列类型时不会推断为 DECIMAL，数值会以 DOUBLE 存储，因而可能丢失末位小数。即使通过 Schema
Template 将子路径显式声明为 DECIMAL（例如 `pm25 VARIANT<'xxx': DECIMAL(6, 2)>`），写入路径也会先解析为
DOUBLE 再转换为 DECIMAL，仍不能完全保证精度。如果在 JSON 中将该字段写成字符串形式（例如 `'{"num":
"12.345"}'`），并配合 Schema Template 声明为对应的 DECIMAL（例如 `DECIMAL(9,
3)`），写入时会直接由字符串解析为 DECIMAL，可以保证精度。
diff --git
a/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 0dc473d6335..46856616e28 100644
---
a/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -578,3 +578,5 @@ ClickBench (43 queries):
- No. They are equivalent.
2. Why doesn’t my query/index work?
- Check whether you CAST paths to the correct types; whether the type was
promoted to JSONB due to conflicts; or whether you mistakenly expect an index
on the whole VARIANT instead of on subpaths.
+3. Why does DECIMAL lose precision when written into a VARIANT column?
+ - When writing to a VARIANT column, the subcolumn type is not inferred as
DECIMAL — numeric values are stored as DOUBLE, which can drop trailing
decimals. Even declaring the subpath as DECIMAL via the Schema Template (e.g.
`pm25 VARIANT<'xxx': DECIMAL(6, 2)>`) does not fully guarantee precision,
because the value is first parsed as DOUBLE and then converted to DECIMAL on
the write path. If the JSON value is written as a string (e.g. `'{"num":
"12.345"}'`) together with a matching Sche [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
