Rounding functions

floor

Returns the largest rounded number less than or equal x. A rounded number is a multiple of 1 / 10 * N, or the nearest number of the appropriate data type if 1 / 10 * N isn't exact.

Integer arguments may be rounded with negative N argument, with non-negative N the function returns x, i.e. does nothing.

If rounding causes an overflow (for example, floor(-128, -1)), the result is undefined.

Syntax

floor(x[, N])

Parameters

• x - The value to round. Float*, Decimal*, or (U)Int*.
• N . (U)Int*. The default is zero, which means rounding to an integer. Can be negative.

Returned value

A rounded number of the same type as x.

Examples

Query:

SELECT floor(123.45, 1) AS rounded

Result:

┌─rounded─┐
│   123.4 │
└─────────┘

Query:

SELECT floor(123.45, -1)

Result:

┌─rounded─┐
│     120 │
└─────────┘

ceiling

Like floor but returns the smallest rounded number greater than or equal x.

Syntax

ceiling(x[, N])

Alias: ceil

truncate

Like floor but returns the rounded number with largest absolute value that has an absolute value less than or equal to x's.

Syntax

truncate(x[, N])

Alias: trunc.

Example

Query:

SELECT truncate(123.499, 1) AS res;

┌───res─┐
│ 123.4 │
└───────┘

round

Rounds a value to a specified number of decimal places.

The function returns the nearest number of the specified order. If the input value has equal distance to two neighboring numbers, the function uses banker's rounding for Float* inputs and rounds away from zero for the other number types (Decimal*.

Syntax

round(x[, N])

Arguments

• x — A number to round. Float*, Decimal*, or (U)Int*.
• N — The number of decimal places to round to. Integer. Defaults to 0.
  • If N > 0, the function rounds to the right of the decimal point.
  • If N < 0, the function rounds to the left of the decimal point.
  • If N = 0, the function rounds to the next integer.

Returned value:

A rounded number of the same type as x.

Examples

Example with Float inputs:

SELECT number / 2 AS x, round(x) FROM system.numbers LIMIT 3;

┌───x─┬─round(divide(number, 2))─┐
│   0 │                        0 │
│ 0.5 │                        0 │
│   1 │                        1 │
└─────┴──────────────────────────┘

Example with Decimal inputs:

SELECT cast(number / 2 AS  Decimal(10,4)) AS x, round(x) FROM system.numbers LIMIT 3;

┌───x─┬─round(CAST(divide(number, 2), 'Decimal(10, 4)'))─┐
│   0 │                                                0 │
│ 0.5 │                                                1 │
│   1 │                                                1 │
└─────┴──────────────────────────────────────────────────┘

To retain trailing zeros, enable setting output_format_decimal_trailing_zeros:

SELECT cast(number / 2 AS  Decimal(10,4)) AS x, round(x) FROM system.numbers LIMIT 3 settings output_format_decimal_trailing_zeros=1;

┌──────x─┬─round(CAST(divide(number, 2), 'Decimal(10, 4)'))─┐
│ 0.0000 │                                           0.0000 │
│ 0.5000 │                                           1.0000 │
│ 1.0000 │                                           1.0000 │
└────────┴──────────────────────────────────────────────────┘

Examples of rounding to the nearest number:

round(3.2, 0) = 3
round(4.1267, 2) = 4.13
round(22,-1) = 20
round(467,-2) = 500
round(-467,-2) = -500

Banker's rounding.

round(3.5) = 4
round(4.5) = 4
round(3.55, 1) = 3.6
round(3.65, 1) = 3.6

See Also

• roundBankers

roundBankers

Rounds a number to a specified decimal position.

If the rounding number is halfway between two numbers, the function uses banker's rounding. Banker's rounding is a method of rounding fractional numbers When the rounding number is halfway between two numbers, it's rounded to the nearest even digit at the specified decimal position. For example: 3.5 rounds up to 4, 2.5 rounds down to 2. It's the default rounding method for floating point numbers defined in IEEE 754. The round function performs the same rounding for floating point numbers. The roundBankers function also rounds integers the same way, for example, roundBankers(45, -1) = 40.

In other cases, the function rounds numbers to the nearest integer.

Using banker's rounding, you can reduce the effect that rounding numbers has on the results of summing or subtracting these numbers.

For example, sum numbers 1.5, 2.5, 3.5, 4.5 with different rounding:

• No rounding: 1.5 + 2.5 + 3.5 + 4.5 = 12.
• Banker's rounding: 2 + 2 + 4 + 4 = 12.
• Rounding to the nearest integer: 2 + 3 + 4 + 5 = 14.

Syntax

roundBankers(x [, N])

Arguments

• N > 0 — The function rounds the number to the given position right of the decimal point. Example: roundBankers(3.55, 1) = 3.6.

• N < 0 — The function rounds the number to the given position left of the decimal point. Example: roundBankers(24.55, -1) = 20.

• N = 0 — The function rounds the number to an integer. In this case the argument can be omitted. Example: roundBankers(2.5) = 2.

• x — A number to round. Float*, Decimal*, or (U)Int*.

• N — The number of decimal places to round to. Integer. Defaults to 0.

  • If N > 0, the function rounds to the right of the decimal point.
  • If N < 0, the function rounds to the left of the decimal point.
  • If N = 0, the function rounds to the next integer.

Returned value

A value rounded by the banker's rounding method.

Examples

Query:

 SELECT number / 2 AS x, roundBankers(x, 0) AS b FROM system.numbers LIMIT 10

Result:

┌───x─┬─b─┐
│   0 │ 0 │
│ 0.5 │ 0 │
│   1 │ 1 │
│ 1.5 │ 2 │
│   2 │ 2 │
│ 2.5 │ 2 │
│   3 │ 3 │
│ 3.5 │ 4 │
│   4 │ 4 │
│ 4.5 │ 4 │
└─────┴───┘

Examples of Banker's rounding:

roundBankers(0.4) = 0
roundBankers(-3.5) = -4
roundBankers(4.5) = 4
roundBankers(3.55, 1) = 3.6
roundBankers(3.65, 1) = 3.6
roundBankers(10.35, 1) = 10.4
roundBankers(10.755, 2) = 10.76

See Also

• round

roundToExp2

Accepts a number. If the number is less than one, it returns 0. Otherwise, it rounds the number down to the nearest (whole non-negative) degree of two.

Syntax

roundToExp2(num)

Parameters

• num: A number to round. UInt/Float.

Returned value

• 0, for num $\lt 1$. UInt8.
• num rounded down to the nearest (whole non-negative) degree of two. UInt/Float equivalent to the input type.

Example

Query:

SELECT *, roundToExp2(*) FROM system.numbers WHERE number IN (0, 2, 5, 10, 19, 50)

Result:

┌─number─┬─roundToExp2(number)─┐
│      0 │                   0 │
│      2 │                   2 │
│      5 │                   4 │
│     10 │                   8 │
│     19 │                  16 │
│     50 │                  32 │
└────────┴─────────────────────┘

roundDuration

Accepts a number. If the number is less than one, it returns 0. Otherwise, it rounds the number down to numbers from the set of commonly used durations: 1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000.

Syntax

roundDuration(num)

Parameters

• num: A number to round to one of the numbers in the set of common durations. UInt/Float.

Returned value

• 0, for num $\lt 1$.
• Otherwise, one of: 1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000. UInt16.

Example

Query:

SELECT *, roundDuration(*) FROM system.numbers WHERE number IN (0, 9, 19, 47, 101, 149, 205, 271, 421, 789, 1423, 2345, 4567, 9876, 24680, 42573)

Result:

┌─number─┬─roundDuration(number)─┐
│      0 │                     0 │
│      9 │                     1 │
│     19 │                    10 │
│     47 │                    30 │
│    101 │                    60 │
│    149 │                   120 │
│    205 │                   180 │
│    271 │                   240 │
│    421 │                   300 │
│    789 │                   600 │
│   1423 │                  1200 │
│   2345 │                  1800 │
│   4567 │                  3600 │
│   9876 │                  7200 │
│  24680 │                 18000 │
│  42573 │                 36000 │
└────────┴───────────────────────┘

roundAge

Accepts a number within various commonly used ranges of human age and returns either a maximum or a minimum within that range.

Syntax

roundAge(num)

Parameters

• age: A number representing an age in years. UInt/Float.

Returned value

• Returns 0, for $age \lt 1$.
• Returns 17, for $1 \leq age \leq 17$.
• Returns 18, for $18 \leq age \leq 24$.
• Returns 25, for $25 \leq age \leq 34$.
• Returns 35, for $35 \leq age \leq 44$.
• Returns 45, for $45 \leq age \leq 54$.
• Returns 55, for $age \geq 55$.

Type: UInt8.

Example

Query:

SELECT *, roundAge(*) FROM system.numbers WHERE number IN (0, 5, 20, 31, 37, 54, 72);

Result:

┌─number─┬─roundAge(number)─┐
│      0 │                0 │
│      5 │               17 │
│     20 │               18 │
│     31 │               25 │
│     37 │               35 │
│     54 │               45 │
│     72 │               55 │
└────────┴──────────────────┘

roundDown

Accepts a number and rounds it down to an element in the specified array. If the value is less than the lowest bound, the lowest bound is returned.

Syntax

roundDown(num, arr)

Parameters

• num: A number to round down. Numeric.
• arr: Array of elements to round age down to. Array of UInt/Float type.

Returned value

• Number rounded down to an element in arr. If the value is less than the lowest bound, the lowest bound is returned. UInt/Float type deduced from the type of arr.

Example

Query:

SELECT *, roundDown(*, [3, 4, 5]) FROM system.numbers WHERE number IN (0, 1, 2, 3, 4, 5)

Result:

┌─number─┬─roundDown(number, [3, 4, 5])─┐
│      0 │                            3 │
│      1 │                            3 │
│      2 │                            3 │
│      3 │                            3 │
│      4 │                            4 │
│      5 │                            5 │
└────────┴──────────────────────────────┘

ceil

Introduced in: v1.1

Like floor but returns the smallest rounded number greater than or equal to x. If rounding causes an overflow (for example, ceiling(255, -1)), the result is undefined.

Syntax

ceiling(x[, N])

Arguments

• x — The value to round. Float* or Decimal* or (U)Int*
• N — Optional. The number of decimal places to round to. Defaults to zero, which means rounding to an integer. Can be negative. (U)Int*

Returned value

Returns a rounded number of the same type as x. Float* or Decimal* or (U)Int*

Examples

Basic usage

SELECT ceiling(123.45, 1) AS rounded

┌─rounded─┐
│   123.5 │
└─────────┘

Negative precision

SELECT ceiling(123.45, -1)

┌─ceiling(123.45, -1)─┐
│                 130 │
└─────────────────────┘

floor

Introduced in: v1.1

Returns the largest rounded number less than or equal to x, where the rounded number is a multiple of 1 / 10 * N, or the nearest number of the appropriate data type if 1 / 10 * N isn't exact.

Integer arguments may be rounded with a negative N argument. With non-negative N the function returns x.

If rounding causes an overflow (for example, floor(-128, -1)), the result is undefined.

Syntax

floor(x[, N])

Arguments

• x — The value to round. Float* or Decimal* or (U)Int*
• N — Optional. The number of decimal places to round to. Defaults to zero, which means rounding to an integer. Can be negative. (U)Int*

Returned value

Returns a rounded number of the same type as x. Float* or Decimal* or (U)Int*

Examples

Usage example

SELECT floor(123.45, 1) AS rounded

┌─rounded─┐
│   123.4 │
└─────────┘

Negative precision

SELECT floor(123.45, -1)

┌─floor(123.45, -1)─┐
│               120 │
└───────────────────┘

round

Introduced in: v1.1

Rounds a value to a specified number of decimal places N.

• If N > 0, the function rounds to the right of the decimal point.
• If N < 0, the function rounds to the left of the decimal point.
• If N = 0, the function rounds to the next integer.

The function returns the nearest number of the specified order. If the input value has equal distance to two neighboring numbers, the function uses banker's rounding for Float* inputs and rounds away from zero for the other number types (Decimal*).

If rounding causes an overflow (for example, round(255, -1)), the result is undefined.

Syntax

round(x[, N])

Arguments

• x — A number to round. Float* or Decimal* or (U)Int*
• N — Optional. The number of decimal places to round to. Defaults to 0. (U)Int*

Returned value

Returns a rounded number of the same type as x. Float* or Decimal* or (U)Int*

Examples

Float inputs

SELECT number / 2 AS x, round(x) FROM system.numbers LIMIT 3;

┌───x─┬─round(x)─┐
│   0 │        0 │
│ 0.5 │        0 │
│   1 │        1 │
└─────┴──────────┘

Decimal inputs

SELECT cast(number / 2 AS  Decimal(10,4)) AS x, round(x) FROM system.numbers LIMIT 3;

┌───x─┬─round(x)─┐
│   0 │        0 │
│ 0.5 │        1 │
│   1 │        1 │
└─────┴──────────┘

roundAge

Introduced in: v1.1

Takes a number representing a human age, compares it to standard age ranges, and returns either the highest or lowest value of the range the number falls within.

• Returns 0, for age < 1.
• Returns 17, for 1 ≤ age ≤ 17.
• Returns 18, for 18 ≤ age ≤ 24.
• Returns 25, for 25 ≤ age ≤ 34.
• Returns 35, for 35 ≤ age ≤ 44.
• Returns 45, for 45 ≤ age ≤ 54.
• Returns 55, for age ≥ 55.

Syntax

roundAge(num)

Arguments

• age — A number representing an age in years. (U)Int* or Float*

Returned value

Returns either the highest or lowest age of the range age falls within. UInt8

Examples

Usage example

SELECT *, roundAge(*) FROM system.numbers WHERE number IN (0, 5, 20, 31, 37, 54, 72);

┌─number─┬─roundAge(number)─┐
│      0 │                0 │
│      5 │               17 │
│     20 │               18 │
│     31 │               25 │
│     37 │               35 │
│     54 │               45 │
│     72 │               55 │
└────────┴──────────────────┘

roundBankers

Introduced in: v20.1

Rounds a number to a specified decimal position N. If the rounding number is halfway between two numbers, the function uses a method of rounding called banker's rounding, which is the default rounding method for floating point numbers defined in IEEE 754.

• If N > 0, the function rounds to the right of the decimal point
• If N < 0, the function rounds to the left of the decimal point
• If N = 0, the function rounds to the next integer

Notes

• When the rounding number is halfway between two numbers, it's rounded to the nearest even digit at the specified decimal position. For example: 3.5 rounds up to 4, 2.5 rounds down to 2.
• The round function performs the same rounding for floating point numbers.
• The roundBankers function also rounds integers the same way, for example, roundBankers(45, -1) = 40.
• In other cases, the function rounds numbers to the nearest integer.

Use banker's rounding for summation or subtraction of numbers

Using banker's rounding, you can reduce the effect that rounding numbers has on the results of summing or subtracting these numbers.

For example, sum numbers 1.5, 2.5, 3.5, 4.5 with different rounding:

• No rounding: 1.5 + 2.5 + 3.5 + 4.5 = 12.
• Banker's rounding: 2 + 2 + 4 + 4 = 12.
• Rounding to the nearest integer: 2 + 3 + 4 + 5 = 14.

Syntax

roundBankers(x[, N])

Arguments

• x — A number to round. (U)Int* or Decimal* or Float*
• [, N] — Optional. The number of decimal places to round to. Defaults to 0. (U)Int*

Returned value

Returns a value rounded by the banker's rounding method. (U)Int* or Decimal* or Float*

Examples

Basic usage

SELECT number / 2 AS x, roundBankers(x, 0) AS b FROM system.numbers LIMIT 10

┌───x─┬─b─┐
│   0 │ 0 │
│ 0.5 │ 0 │
│   1 │ 1 │
│ 1.5 │ 2 │
│   2 │ 2 │
│ 2.5 │ 2 │
│   3 │ 3 │
│ 3.5 │ 4 │
│   4 │ 4 │
│ 4.5 │ 4 │
└─────┴───┘

roundDown

Introduced in: v20.1

Rounds a number down to an element in the specified array. If the value is less than the lower bound, the lower bound is returned.

Syntax

roundDown(num, arr)

Arguments

• num — A number to round down. (U)Int* or Decimal* or Float*
• arr — Array of elements to round num down to. Array((U)Int*) or Array(Float*)

Returned value

Returns a number rounded down to an element in arr. If the value is less than the lowest bound, the lowest bound is returned. (U)Int* or Float*

Examples

Usage example

SELECT *, roundDown(*, [3, 4, 5]) FROM system.numbers WHERE number IN (0, 1, 2, 3, 4, 5)

┌─number─┬─roundDown(number, [3, 4, 5])─┐
│      0 │                            3 │
│      1 │                            3 │
│      2 │                            3 │
│      3 │                            3 │
│      4 │                            4 │
│      5 │                            5 │
└────────┴──────────────────────────────┘

roundDuration

Introduced in: v1.1

Rounds a number down to the closest from a set of commonly used durations: 1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000. If the number is less than one, it returns 0.

Syntax

roundDuration(num)

Arguments

• num — A number to round to one of the numbers in the set of common durations. (U)Int* or Float*

Returned value

Returns 0, for num < 1. Otherwise, one of: 1, 10, 30, 60, 120, 180, 240, 300, 600, 1200, 1800, 3600, 7200, 18000, 36000. UInt16

Examples

Usage example

SELECT *, roundDuration(*) FROM system.numbers WHERE number IN (0, 9, 19, 47, 101, 149, 205, 271, 421, 789, 1423, 2345, 4567, 9876, 24680, 42573)

┌─number─┬─roundDuration(number)─┐
│      0 │                     0 │
│      9 │                     1 │
│     19 │                    10 │
│     47 │                    30 │
│    101 │                    60 │
│    149 │                   120 │
│    205 │                   180 │
│    271 │                   240 │
│    421 │                   300 │
│    789 │                   600 │
│   1423 │                  1200 │
│   2345 │                  1800 │
│   4567 │                  3600 │
│   9876 │                  7200 │
│  24680 │                 18000 │
│  42573 │                 36000 │
└────────┴───────────────────────┘

roundToExp2

Introduced in: v1.1

Rounds a number down to the nearest (whole non-negative) power of two. If the number is less than one, it returns 0.

Syntax

roundToExp2(num)

Arguments

• num — A number to round. (U)Int* or Float*

Returned value

Returns num rounded down to the nearest (whole non-negative) power of two, otherwise 0 for num < 1. (U)Int* or Float*

Examples

Usage example

SELECT *, roundToExp2(*) FROM system.numbers WHERE number IN (0, 2, 5, 10, 19, 50)

┌─number─┬─roundToExp2(number)─┐
│      0 │                   0 │
│      2 │                   2 │
│      5 │                   4 │
│     10 │                   8 │
│     19 │                  16 │
│     50 │                  32 │
└────────┴─────────────────────┘

trunc

Introduced in: v1.1

Like floor but returns the rounded number with the largest absolute value less than or equal to that of x.

Syntax

truncate(x[, N])

Arguments

• x — The value to round. Float* or Decimal* or (U)Int*
• N — Optional. The number of decimal places to round to. Defaults to zero, which means rounding to an integer. (U)Int*

Returned value

Returns a rounded number of the same type as x. Float* or Decimal* or (U)Int*

Examples

Basic usage

SELECT truncate(123.499, 1) AS res;

┌───res─┐
│ 123.4 │
└───────┘