Add `output_format_float_precision` setting to limit decimal digits in float output by phulv94 · Pull Request #99721 · ClickHouse/ClickHouse

phulv94 · 2026-03-17T10:28:16Z

When set to 0 (the default), the existing shortest round-trip representation (dragonbox) is used. When set to N, values are rounded to N decimal places using the double-conversion library's ToFixed. Closes #99199

Changelog category (leave one):

New Feature

Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):

Add output_format_float_precision setting to control the number of decimal digits in floating-point text output.

Documentation entry for user-facing changes

Documentation is written (mandatory for new features)

phulv94 · 2026-03-17T10:43:27Z

@rienath Can you take a look when you have freetime?

clickhouse-gh · 2026-03-17T11:33:55Z

Workflow [PR], commit [8b4cba8]

Summary: ❌

job_name	test_name	status	info
Stress test (arm_asan_ubsan, s3)		failure
	Logical error: 'std::exception. Code: 1001, type: std::invalid_argument, e.what() = stoi: no conversion (version 26.4.1.408), Stack trace: (STID: 2508-3132)	FAIL	cidb
Stress test (arm_tsan)		failure
	Logical error: Unexpected number of columns in result sample block: A expected B ([C] = [D] + [E] + [F]) (STID: 2980-385f)	FAIL	cidb, issue
Stress test (arm_msan)		failure
	MemorySanitizer: use-of-uninitialized-value (STID: 1003-358c)	FAIL	cidb
Stress test (arm_ubsan)		failure
	Hung check failed, possible deadlock found	FAIL	cidb
Finish Workflow		failure
	python3 ./ci/jobs/scripts/workflow_hooks/feature_docs.py	failure

AI Review

Summary

This PR introduces output_format_float_precision and wires it through text serialization paths (SerializationNumber, writeJSONNumber) with fallback behavior for non-finite and large-magnitude values, plus coverage in a new stateless test. On the current PR head, I did not find additional correctness, safety, or performance issues beyond already-discussed inline comments.

Missing context

⚠️ No CI run results/logs were provided in this review request, so runtime validation was limited to static analysis of the PR head diff and tests.

ClickHouse Rules

Item	Status	Notes
Deletion logging	➖
Serialization versioning	➖
Core-area scrutiny	✅
No test removal	✅
Experimental gate	➖
No magic constants	✅
Backward compatibility	✅
`SettingsChangesHistory.cpp`	✅
PR metadata quality	✅
Safe rollout	✅
Compilation time	✅

Final Verdict

Status: ✅ Approve

src/IO/WriteHelpers.cpp

src/Core/FormatFactorySettings.h

tests/queries/0_stateless/03400_output_format_float_precision.sql

src/IO/WriteHelpers.cpp

tests/queries/0_stateless/03400_output_format_float_precision.sql

src/Formats/FormatFactory.cpp

phulv94 · 2026-03-19T07:24:43Z

@rienath seem like the CI look good, can you take a look?

rienath · 2026-03-19T09:19:57Z

@phulv94 please resolve conflicts

phulv94 · 2026-03-20T08:40:15Z

@phulv94 please resolve conflicts

I've resolved conflicts.

rienath

Thanks for working on this! The overall approach looks good. There are a couple of issues to address before merge.

With the current implementation, ToFixed always pads with trailing zeroes up to the requested precision, even when they carry no information. For example:

:) SELECT (1.1::BFloat16) settings output_format_float_precision=0;
-- 1.09375

:) SELECT (1.1::BFloat16) settings output_format_float_precision=30;
-- 1.093750000000000000000000000000

The exact representation has only 6 meaningful digits, but we get 24 extra zeroes. Similarly for negative zero:

:) SELECT (-0.0::BFloat16) settings output_format_float_precision=1;
-- -0.0

:) SELECT (-0.0::BFloat16) settings output_format_float_precision=0;
-- -0

The setting should mean "round to at most N decimal places", not "always pad to N decimal places". It would be great to strip trailing zeroes (and the trailing decimal point if it becomes unnecessary), so that output_format_float_precision = 30 produces 1.09375, not 1.093750000000000000000000000000.

Another important problem is numbers with magnitude >= 10^60 throw because ToFixed can't represent them. A format setting should never cause previously-working queries to fail on valid data.

:) SELECT 1e61 settings output_format_float_precision=0;
-- 1e61

:) SELECT 1e61 settings output_format_float_precision=1;
-- Code: 28. DB::Exception: Cannot print floating point number. (CANNOT_PRINT_FLOAT_OR_DOUBLE_NUMBER)

When you fixe these, please add regression tests. You could use the examples above

rienath · 2026-03-27T10:37:13Z

src/Core/SettingsChangesHistory.cpp

            {"functions_h3_default_if_invalid", true, false, "A new setting for legacy behaviour to allow invalid inputs to h3 functions"},
            {"max_skip_unavailable_shards_num", 0, 0, "New setting to limit the number of shards that can be silently skipped when skip_unavailable_shards is enabled."},
            {"max_skip_unavailable_shards_ratio", 0, 0, "New setting to limit the ratio of shards that can be silently skipped when skip_unavailable_shards is enabled."},
+            {"output_format_float_precision", 0, 0, "A new setting to control decimal digits in float output"},


We need to merge master and move this to 26.4 section

rienath · 2026-03-27T10:39:37Z

src/Formats/FormatSettings.h

    bool null_as_default = true;
    bool force_null_for_omitted_fields = false;
    bool decimal_trailing_zeros = false;
+    UInt64 float_precision = 0;


UInt64 is an overkill for a value that is capped at 60. Let's try UInt8 and add a regression test to see what happens when user chooses a value that exceeds it

Then we also need to change the type in src/Core/FormatFactorySettings.h in DELACRE(...

Seem like DELACRE( not support UInt8.

rienath · 2026-03-27T10:48:20Z

tests/queries/0_stateless/03400_output_format_float_precision.sql

+-- Test both Float32 and Float64  
+SET output_format_float_precision = 4;
+SELECT toFloat32(1.0/3);
+SELECT toFloat64(1.0/3);
+SELECT toFloat32(3.141592653589793);
+SELECT toFloat64(3.141592653589793);


Let's test BFloat16 too

rienath · 2026-03-27T10:53:30Z

src/Core/FormatFactorySettings.h

+Number of decimal digits after the decimal point for floating-point output (`Float32`, `Float64`, `BFloat16`).
+If set to 0 (the default), uses the shortest round-trip representation.


Suggested change

Number of decimal digits after the decimal point for floating-point output (`Float32`, `Float64`, `BFloat16`).

If set to 0 (the default), uses the shortest round-trip representation.

When non-zero, round floating-point output (`Float32`, `Float64`, `BFloat16`) to this many digits after the decimal point. When 0 (default), use the default representation.

rienath · 2026-03-27T11:40:56Z

src/IO/WriteHelpers.cpp

+    if (settings.float_precision > 60)
+        throw Exception(ErrorCodes::CANNOT_PRINT_FLOAT_OR_DOUBLE_NUMBER,
+            "Too high precision requested for Float, must not be more than 60, got {}", settings.float_precision);


It's currently hard-coded at 60. I think the library permits a higher value. Let's use some constant out of the library instead of hardcoding it if that is possible. Perhaps it will change it future. We want our code to pick up the change gracefully

rienath · 2026-03-27T11:43:47Z

src/IO/WriteHelpers.cpp

+    if (!result)
+        throw Exception(ErrorCodes::CANNOT_PRINT_FLOAT_OR_DOUBLE_NUMBER,
+            "Cannot print floating point number");


This code path should be unreachable. So let's change the error type to LOGICAL_ERROR. I understand that we can currently have a large magnitude value that will throw, but it's best to fix this case

rienath · 2026-03-27T11:44:32Z

tests/queries/0_stateless/03400_output_format_float_precision.sql

+SELECT toFloat64('inf');
+SELECT toFloat64('-inf');
+SELECT toFloat64('nan');
+SELECT toFloat32('inf');
+SELECT toFloat32('-inf');
+SELECT toFloat32('nan');


Let's add BFloat16 case too

…loat-precision-setting

clickhouse-gh · 2026-03-29T14:28:13Z

tests/queries/0_stateless/03400_output_format_float_precision.sql

+-- Test CSV
+SELECT 1.0/3 FORMAT CSV;
+
+-- Test out-of-range precision (> 100) raises a BAD_ARGUMENTS exception


The comment says > 100, but the implementation validates against DoubleToStringConverter::kMaxFixedDigitsAfterPoint (currently 60) and this test uses 101 as just one out-of-range example.

Please update the comment to avoid confusion, e.g. -- Test out-of-range precision (> 60) raises a BAD_ARGUMENTS exception.

clickhouse-gh · 2026-03-30T01:48:20Z

src/IO/WriteHelpers.cpp

+    /// ToFixed returns false for values with magnitude >= 10^kMaxFixedDigitsBeforePoint.
+    /// Fall back to the default shortest round-trip representation for such values.
+    const double x_double = static_cast<double>(x);
+    if (std::abs(x_double) >= 1e60)


writeFloatText uses a hardcoded fallback threshold 1e60 while the guard comment references DoubleToStringConverter::kMaxFixedDigitsBeforePoint.

This is brittle: if upstream double-conversion changes the max fixed digits, behavior silently diverges from the actual converter limit. Please derive the threshold from the library constant (for example, compute pow(10, kMaxFixedDigitsBeforePoint) once) instead of embedding 1e60.

clickhouse-gh · 2026-03-30T11:10:34Z

LLVM Coverage Report

Metric	Baseline	Current	Δ
Lines	84.20%	84.10%	-0.10%
Functions	90.90%	90.90%	+0.00%
Branches	76.80%	76.70%	-0.10%

Changed lines: 98.88% (88/89) · Uncovered code

Full report · Diff report

phulv94 added 2 commits March 17, 2026 17:25

Add output format float precision setting

be2d114

Merge branch 'master' into add-output-format-float-precision-setting

430ab52

rienath self-assigned this Mar 17, 2026

rienath added the can be tested Allows running workflows for external contributors label Mar 17, 2026

clickhouse-gh bot added the pr-improvement Pull request with some product improvements label Mar 17, 2026