functions-and-operators: correct the approximate-value rounding rule

[sary8]

First-time contributors' checklist

• I've signed the Contributor License Agreement, which is required for the repository owners to accept my contribution.

What is changed, added, or deleted? (Required)

Two fixes in functions-and-operators/precision-math.md.

1. The approximate-value rounding rule is out of date.

The "Rounding behavior" section says that ROUND() on approximate-value numbers behaves differently in TiDB than in MySQL, and the example shows ROUND(25E-1) returning 3.

That description predates v4.0.11. pingcap/tidb#21324 changed approximate-value rounding to "round to nearest even" specifically to match MySQL, and it was included in v5.0.0. The change was backported to the 4.0 line as pingcap/tidb#21628, which shipped in v4.0.11 and is listed in the v4.0.11 release notes in this repository. Since v4.0.11, TiDB returns 2 for this example.

I ran the example on both servers:

-- MySQL 8.0.46
mysql> SELECT ROUND(2.5), ROUND(-2.5), ROUND(25E-1);
+------------+-------------+--------------+
| ROUND(2.5) | ROUND(-2.5) | ROUND(25E-1) |
+------------+-------------+--------------+
|          3 |          -3 |            2 |
+------------+-------------+--------------+

-- TiDB v8.5.8
mysql> SELECT ROUND(2.5), ROUND(-2.5), ROUND(25E-1);
+------------+-------------+--------------+
| ROUND(2.5) | ROUND(-2.5) | ROUND(25E-1) |
+------------+-------------+--------------+
|          3 |          -3 |            2 |
+------------+-------------+--------------+

They agree on the wider set too. ROUND(35E-1) is 4, ROUND(45E-1) is 4, ROUND(55E-1) is 6, and ROUND(-25E-1) is -2 on both, which is round-to-nearest-even in each case. TiDB's own test expectations record the same result for the example in tests/integrationtest/r/expression/builtin.result.

The stale sentence also contradicted the opening line of the same page, which states that precision math support in TiDB is consistent with MySQL.

The replacement states the rule TiDB applies and keeps the MySQL nuance: MySQL delegates approximate-value rounding to the C library, so it is not guaranteed on every platform. I left the exact-value bullet untouched. I also moved the example out of the list, because its first column illustrates the exact-value rule and its second column the approximate-value one.

The equivalent page in pingcap/docs-cn still contains the stale rounding statement and example; this PR only updates the English documentation.

2. A mismatched quote makes an example fail when copied.

SET sql_mode = 'TRADITIONAL`;

The string opens with ' and closes with a backtick, so copying the statement produces a syntax error. I confirmed the corrected form runs on TiDB v8.5.8. The same line is already correct in pingcap/docs-cn, so this one is specific to the English page.

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

• master (the latest development version)
• v9.0 (TiDB 9.0 versions)
• v8.5 (TiDB 8.5 versions)
• v8.1 (TiDB 8.1 versions)
• v7.5 (TiDB 7.5 versions)
• v7.1 (TiDB 7.1 versions)
• v6.5 (TiDB 6.5 versions)

Master only, since this corrects an inaccurate description and an example value rather than documenting a version-specific behavior change.

The same stale text is present in release-8.5, release-8.1, release-7.5, release-7.1, and release-6.5, and the change can be cherry-picked to those branches without version-specific wording. This page is also referenced from TOC-tidb-cloud.md, and both errors are currently published on the TiDB Cloud copy of this page, so the correction is relevant there as well.

What is the related PR or file link(s)?

• Related code change PR links (if applicable): pingcap/tidb#21324 and its backport pingcap/tidb#21628 are the changes that made this page out of date.
• This PR is translated from:
• Other reference link(s): Rounding Behavior in the MySQL 8.0 manual. I found this stale description while working on my TiDB fix pingcap/tidb#71119, which addresses exact-value integer rounding. This documentation fix is independent of that PR and does not change the exact-value rule.

AI agent involvement

• The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

• Delete files
• Change aliases
• Need modification after applied to another branch
• Might cause conflicts after applied to another branch

Summary by CodeRabbit

• Documentation
  • Corrected the SQL mode example formatting.
  • Clarified ROUND() behavior for approximate-value numbers in TiDB.
  • Updated the rounding example to show ROUND(25E-1) returning 2.
  • Added a note that MySQL rounding results may vary by platform.

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign oreoxmt for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[ti-chi-bot]

Hi @sary8. Thanks for your PR.

I'm waiting for a pingcap member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[ti-chi-bot]

Welcome @sary8!

It looks like this is your first PR to pingcap/docs 🎉.

I'm the bot to help you request reviewers, add labels and more, See available commands.

We want to make sure your contribution gets all the attention it needs!



Thank you, and welcome to pingcap/docs. 😃

[pingcap-cla-assistant]

All committers have signed the CLA.

[coderabbitai]

📝 Walkthrough

Walkthrough

The precision math reference fixes a SQL mode example and updates the documented ROUND() behavior for approximate-value numbers in TiDB and MySQL.

Changes

Precision Math Documentation

Layer / File(s)	Summary
SQL example and approximate rounding reference functions-and-operators/precision-math.md	The SQL mode example now uses a closing single quote. The ROUND() section documents round-to-nearest-even behavior in TiDB, updates the ROUND(25E-1) result to 2, and notes that MySQL results can vary by platform.

Priority: ➖ Normal

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other · Severity of issue fixed: Medium

Merge Risk: 🔵 Low · up to 53456

Users of older TiDB releases may apply the documented rounding rule incorrectly; the fix is small and localized.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Issue #71119 requires an integer ROUND() implementation that rounds exact integers half away from zero, preserves values above 2^53, detects overflow, and keeps row, vectorized, and TiFlash results …	Include the integer ROUND() implementation and the required unit and integration coverage for precision, half-away-from-zero rounding, overflow, row/vectorized evaluation, and TiFlash consistency. If that implementation already exists out…
Out of Scope Changes check	⚠️ Warning	The approximate-value ROUND() documentation supports the rounding compatibility context in issue #71119. The correction to the unrelated SET sql_mode = 'TRADITIONAL'; example has no demonstrated c…	Remove the unrelated sql_mode quote correction from this pull request or move it to a separate documentation change.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Title check	✅ Passed	The title clearly identifies the main change: correcting the approximate-value rounding rule in the precision-math documentation.
Description check	✅ Passed	The description is complete and relevant. It explains both documentation fixes, provides validation details and references, identifies the affected version, and addresses all template sections.

Full details: Linked Issues check

Explanation

Issue #71119 requires an integer ROUND() implementation that rounds exact integers half away from zero, preserves values above 2^53, detects overflow, and keeps row, vectorized, and TiFlash results consistent. It also requires unit and integration tests. The reviewed changes only update functions-and-operators/precision-math.md; they document approximate-value behavior and do not implement or test the integer behavior.

Resolution

Include the integer ROUND() implementation and the required unit and integration coverage for precision, half-away-from-zero rounding, overflow, row/vectorized evaluation, and TiFlash consistency. If that implementation already exists outside this pull request, provide reviewable evidence for each requirement.

Full details: Out of Scope Changes check

Explanation

The approximate-value ROUND() documentation supports the rounding compatibility context in issue #71119. The correction to the unrelated SET sql_mode = 'TRADITIONAL'; example has no demonstrated connection to that issue and is an unrelated documentation change.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: eff58eca-8a2e-4895-9fb5-0ea5cb7c1246

📥 Commits

Reviewing files that changed from the base of the PR and between 478793a and 53456ae.

📒 Files selected for processing (1)

• functions-and-operators/precision-math.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.