ClickHouse/docs/en/sql-reference/functions/math-functions.md

714 lines
11 KiB
Markdown
Raw Normal View History

2020-04-03 13:23:32 +00:00
---
2022-08-28 14:53:34 +00:00
slug: /en/sql-reference/functions/math-functions
2023-04-19 17:05:55 +00:00
sidebar_position: 125
sidebar_label: Mathematical
2020-04-03 13:23:32 +00:00
---
2022-06-02 10:55:18 +00:00
# Mathematical Functions
2023-04-19 20:33:39 +00:00
All the functions return a Float64 number. Results are generally as close to the actual result as possible, but in some cases less precise than the machine-representable number.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## e
2023-04-19 20:33:39 +00:00
Returns e.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
```sql
e()
```
## pi
Returns π.
**Syntax**
```sql
pi()
```
## exp
Returns e to the power of the given argument.
**Syntax**
```sql
exp(x)
```
## log
Returns the natural logarithm of the argument.
**Syntax**
```sql
log(x)
```
Alias: `ln(x)`
## exp2
2023-06-02 11:30:05 +00:00
Returns 2 to the power of the given argument
2023-04-19 20:33:39 +00:00
**Syntax**
```sql
exp2(x)
```
## intExp2
2023-04-19 20:33:39 +00:00
Like `exp` but returns a UInt64.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
intExp2(x)
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## log2
2023-04-19 20:33:39 +00:00
Returns the binary logarithm of the argument.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
log2(x)
```
## exp10
2017-04-03 19:49:50 +00:00
2023-06-02 13:27:56 +00:00
Returns 10 to the power of the given argument.
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
exp10(x)
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## intExp10
2023-04-19 20:33:39 +00:00
Like `exp10` but returns a UInt64.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
intExp10(x)
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## log10
2023-04-19 20:33:39 +00:00
Returns the decimal logarithm of the argument.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
log10(x)
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## sqrt
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
Returns the square root of the argument.
```sql
sqrt(x)
```
## cbrt
Returns the cubic root of the argument.
```sql
cbrt(x)
```
## erf
If `x` is non-negative, then `erf(x / σ√2)` is the probability that a random variable having a normal distribution with standard deviation `σ` takes the value that is separated from the expected value by more than `x`.
**Syntax**
```sql
erf(x)
```
**Example**
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
(three sigma rule)
2017-04-03 19:49:50 +00:00
2020-03-20 10:10:48 +00:00
``` sql
SELECT erf(3 / sqrt(2));
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
```result
┌─erf(divide(3, sqrt(2)))─┐
│ 0.9973002039367398 │
└─────────────────────────┘
```
CLICKHOUSE-2720: progress on website (#865) * update presentations * CLICKHOUSE-2936: redirect from clickhouse.yandex.ru and clickhouse.yandex.com * update submodule * lost files * CLICKHOUSE-2981: prefer sphinx docs over original reference * CLICKHOUSE-2981: docs styles more similar to main website + add flags to switch language links * update presentations * Less confusing directory structure (docs -> doc/reference/) * Minify sphinx docs too * Website release script: fail fast + pass docker hash on deploy * Do not underline links in docs * shorter * cleanup docker images * tune nginx config * CLICKHOUSE-3043: get rid of habrastorage links * Lost translation * CLICKHOUSE-2936: temporary client-side redirect * behaves weird in test * put redirect back * CLICKHOUSE-3047: copy docs txts to public too * move to proper file * remove old pages to avoid confusion * Remove reference redirect warning for now * Refresh README.md * Yellow buttons in docs * Use svg flags instead of unicode ones in docs * fix test website instance * Put flags to separate files * wrong flag * Copy Yandex.Metrica introduction from main page to docs * Yet another home page structure change, couple new blocks (CLICKHOUSE-3045) * Update Contacts section * CLICKHOUSE-2849: more detailed legal information * CLICKHOUSE-2978 preparation - split by files * More changes in Contacts block * Tune texts on index page * update presentations * One more benchmark * Add usage sections to index page, adapted from slides * Get the roadmap started, based on slides from last ClickHouse Meetup * CLICKHOUSE-2977: some rendering tuning * Get rid of excessive section in the end of getting started * Make headers linkable * CLICKHOUSE-2981: links to editing reference - https://github.com/yandex/ClickHouse/issues/849 * CLICKHOUSE-2981: fix mobile styles in docs * Ban crawling of duplicating docs * Open some external links in new tab * Ban old docs too * Lots of trivial fixes in english docs * Lots of trivial fixes in russian docs * Remove getting started copies in markdown * Add Yandex.Webmaster * Fix some sphinx warnings * More warnings fixed in english docs * More sphinx warnings fixed * Add code-block:: text * More code-block:: text * These headers look not that well * Better switch between documentation languages * merge use_case.rst into ya_metrika_task.rst * Edit the agg_functions.rst texts * Add lost empty lines
2017-06-13 04:15:47 +00:00
2023-04-19 20:33:39 +00:00
## erfc
CLICKHOUSE-2720: progress on website (#865) * update presentations * CLICKHOUSE-2936: redirect from clickhouse.yandex.ru and clickhouse.yandex.com * update submodule * lost files * CLICKHOUSE-2981: prefer sphinx docs over original reference * CLICKHOUSE-2981: docs styles more similar to main website + add flags to switch language links * update presentations * Less confusing directory structure (docs -> doc/reference/) * Minify sphinx docs too * Website release script: fail fast + pass docker hash on deploy * Do not underline links in docs * shorter * cleanup docker images * tune nginx config * CLICKHOUSE-3043: get rid of habrastorage links * Lost translation * CLICKHOUSE-2936: temporary client-side redirect * behaves weird in test * put redirect back * CLICKHOUSE-3047: copy docs txts to public too * move to proper file * remove old pages to avoid confusion * Remove reference redirect warning for now * Refresh README.md * Yellow buttons in docs * Use svg flags instead of unicode ones in docs * fix test website instance * Put flags to separate files * wrong flag * Copy Yandex.Metrica introduction from main page to docs * Yet another home page structure change, couple new blocks (CLICKHOUSE-3045) * Update Contacts section * CLICKHOUSE-2849: more detailed legal information * CLICKHOUSE-2978 preparation - split by files * More changes in Contacts block * Tune texts on index page * update presentations * One more benchmark * Add usage sections to index page, adapted from slides * Get the roadmap started, based on slides from last ClickHouse Meetup * CLICKHOUSE-2977: some rendering tuning * Get rid of excessive section in the end of getting started * Make headers linkable * CLICKHOUSE-2981: links to editing reference - https://github.com/yandex/ClickHouse/issues/849 * CLICKHOUSE-2981: fix mobile styles in docs * Ban crawling of duplicating docs * Open some external links in new tab * Ban old docs too * Lots of trivial fixes in english docs * Lots of trivial fixes in russian docs * Remove getting started copies in markdown * Add Yandex.Webmaster * Fix some sphinx warnings * More warnings fixed in english docs * More sphinx warnings fixed * Add code-block:: text * More code-block:: text * These headers look not that well * Better switch between documentation languages * merge use_case.rst into ya_metrika_task.rst * Edit the agg_functions.rst texts * Add lost empty lines
2017-06-13 04:15:47 +00:00
2023-04-19 20:33:39 +00:00
Returns a number close to `1 - erf(x)` without loss of precision for large x values.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
erfc(x)
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## lgamma
2023-04-19 20:33:39 +00:00
Returns the logarithm of the gamma function.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
lgamma(x)
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## tgamma
2023-04-19 20:33:39 +00:00
Returns the gamma function.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
gamma(x)
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## sin
2023-04-19 20:33:39 +00:00
Returns the sine of the argument
2023-04-19 20:33:39 +00:00
**Syntax**
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
```sql
sin(x)
```
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
## cos
2023-04-19 20:33:39 +00:00
Returns the cosine of the argument.
2017-04-03 19:49:50 +00:00
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
cos(x)
```
2023-04-19 20:33:39 +00:00
## tan
2023-04-19 20:33:39 +00:00
Returns the tangent of the argument.
2023-04-19 20:33:39 +00:00
**Syntax**
2023-04-19 20:33:39 +00:00
```sql
tan(x)
```
## asin
Returns the arc sine of the argument.
**Syntax**
```sql
asin(x)
```
2023-04-19 20:33:39 +00:00
## acos
2023-04-19 20:33:39 +00:00
Returns the arc cosine of the argument.
**Syntax**
```sql
acos(x)
```
## atan
Returns the arc tangent of the argument.
**Syntax**
```sql
atan(x)
```
## pow
Returns `x` to the power of `y`.
**Syntax**
```sql
pow(x, y)
```
Alias: `power(x, y)`
## cosh
Returns the [hyperbolic cosine](https://in.mathworks.com/help/matlab/ref/cosh.html) of the argument.
**Syntax**
``` sql
cosh(x)
```
**Arguments**
- `x` — The angle, in radians. Values from the interval: `-∞ < x < +∞`. [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Returned value**
- Values from the interval: `1 <= cosh(x) < +∞`.
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT cosh(0);
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌─cosh(0)──┐
│ 1 │
└──────────┘
```
2023-04-19 20:33:39 +00:00
## acosh
2023-04-19 20:33:39 +00:00
Returns the [inverse hyperbolic cosine](https://www.mathworks.com/help/matlab/ref/acosh.html).
**Syntax**
``` sql
acosh(x)
```
**Arguments**
- `x` — Hyperbolic cosine of angle. Values from the interval: `1 <= x < +∞`. [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Returned value**
- The angle, in radians. Values from the interval: `0 <= acosh(x) < +∞`.
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT acosh(1);
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌─acosh(1)─┐
│ 0 │
└──────────┘
```
2023-04-19 20:33:39 +00:00
## sinh
2023-04-19 20:33:39 +00:00
Returns the [hyperbolic sine](https://www.mathworks.com/help/matlab/ref/sinh.html).
**Syntax**
``` sql
sinh(x)
```
**Arguments**
- `x` — The angle, in radians. Values from the interval: `-∞ < x < +∞`. [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Returned value**
- Values from the interval: `-∞ < sinh(x) < +∞`.
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT sinh(0);
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌─sinh(0)──┐
│ 0 │
└──────────┘
```
2023-04-19 20:33:39 +00:00
## asinh
2023-04-19 20:33:39 +00:00
Returns the [inverse hyperbolic sine](https://www.mathworks.com/help/matlab/ref/asinh.html).
**Syntax**
``` sql
asinh(x)
```
**Arguments**
- `x` — Hyperbolic sine of angle. Values from the interval: `-∞ < x < +∞`. [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Returned value**
- The angle, in radians. Values from the interval: `-∞ < asinh(x) < +∞`.
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT asinh(0);
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌─asinh(0)─┐
│ 0 │
└──────────┘
```
2023-04-19 20:33:39 +00:00
## atanh
2023-04-19 20:33:39 +00:00
Returns the [inverse hyperbolic tangent](https://www.mathworks.com/help/matlab/ref/atanh.html).
**Syntax**
``` sql
atanh(x)
```
**Arguments**
- `x` — Hyperbolic tangent of angle. Values from the interval: `1 < x < 1`. [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Returned value**
- The angle, in radians. Values from the interval: `-∞ < atanh(x) < +∞`.
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT atanh(0);
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌─atanh(0)─┐
│ 0 │
└──────────┘
```
2023-04-19 20:33:39 +00:00
## atan2
2023-04-19 20:33:39 +00:00
Returns the [atan2](https://en.wikipedia.org/wiki/Atan2) as the angle in the Euclidean plane, given in radians, between the positive x axis and the ray to the point `(x, y) ≠ (0, 0)`.
**Syntax**
``` sql
atan2(y, x)
```
**Arguments**
- `y` — y-coordinate of the point through which the ray passes. [Float64](../../sql-reference/data-types/float.md#float32-float64).
- `x` — x-coordinate of the point through which the ray passes. [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Returned value**
- The angle `θ` such that `−π < θ ≤ π`, in radians.
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT atan2(1, 1);
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌────────atan2(1, 1)─┐
│ 0.7853981633974483 │
└────────────────────┘
```
2023-04-19 20:33:39 +00:00
## hypot
2023-04-19 20:33:39 +00:00
Returns the length of the hypotenuse of a right-angle triangle. [Hypot](https://en.wikipedia.org/wiki/Hypot) avoids problems that occur when squaring very large or very small numbers.
**Syntax**
``` sql
hypot(x, y)
```
**Arguments**
- `x` — The first cathetus of a right-angle triangle. [Float64](../../sql-reference/data-types/float.md#float32-float64).
- `y` — The second cathetus of a right-angle triangle. [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Returned value**
- The length of the hypotenuse of a right-angle triangle.
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT hypot(1, 1);
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌────────hypot(1, 1)─┐
│ 1.4142135623730951 │
└────────────────────┘
```
2023-04-19 20:33:39 +00:00
## log1p
2023-04-19 20:33:39 +00:00
Calculates `log(1+x)`. The [calculation](https://en.wikipedia.org/wiki/Natural_logarithm#lnp1) `log1p(x)` is more accurate than `log(1+x)` for small values of x.
**Syntax**
``` sql
log1p(x)
```
**Arguments**
- `x` — Values from the interval: `-1 < x < +∞`. [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Returned value**
- Values from the interval: `-∞ < log1p(x) < +∞`.
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT log1p(0);
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌─log1p(0)─┐
│ 0 │
└──────────┘
```
2023-04-19 20:33:39 +00:00
## sign
2021-01-24 09:15:47 +00:00
Returns the sign of a real number.
2021-01-24 09:15:47 +00:00
**Syntax**
``` sql
sign(x)
```
**Arguments**
2021-01-24 09:15:47 +00:00
- `x` — Values from `-∞` to `+∞`. Support all numeric types in ClickHouse.
2021-01-24 09:15:47 +00:00
**Returned value**
- -1 for `x < 0`
2023-04-19 16:10:51 +00:00
- 0 for `x = 0`
- 1 for `x > 0`
2021-01-24 09:15:47 +00:00
2021-03-06 11:13:14 +00:00
**Examples**
2021-01-24 09:15:47 +00:00
2021-03-06 11:13:14 +00:00
Sign for the zero value:
2021-01-24 09:15:47 +00:00
``` sql
SELECT sign(0);
```
Result:
2023-04-19 20:33:39 +00:00
```result
2021-01-24 09:15:47 +00:00
┌─sign(0)─┐
│ 0 │
└─────────┘
```
2021-03-06 11:13:14 +00:00
Sign for the positive value:
2021-01-24 09:15:47 +00:00
``` sql
SELECT sign(1);
```
Result:
2023-04-19 20:33:39 +00:00
```result
2021-01-24 09:15:47 +00:00
┌─sign(1)─┐
│ 1 │
└─────────┘
```
2021-03-06 11:13:14 +00:00
Sign for the negative value:
2021-01-24 09:15:47 +00:00
``` sql
SELECT sign(-1);
```
Result:
2023-04-19 20:33:39 +00:00
```result
2021-01-24 09:15:47 +00:00
┌─sign(-1)─┐
│ -1 │
└──────────┘
```
2023-04-19 20:33:39 +00:00
## degrees
2022-01-19 23:31:04 +00:00
2023-04-19 20:33:39 +00:00
Converts radians to degrees.
2022-01-19 23:31:04 +00:00
**Syntax**
``` sql
degrees(x)
```
**Arguments**
- `x` — Input in radians. [Float64](../../sql-reference/data-types/float.md#float32-float64).
2022-01-19 23:31:04 +00:00
**Returned value**
- Value in degrees.
2022-01-19 23:31:04 +00:00
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT degrees(3.141592653589793);
```
Result:
2023-04-19 20:33:39 +00:00
```result
2022-01-19 23:31:04 +00:00
┌─degrees(3.141592653589793)─┐
│ 180 │
└────────────────────────────┘
```
2023-04-19 20:33:39 +00:00
## radians
2022-01-19 23:31:04 +00:00
2023-04-19 20:33:39 +00:00
Converts degrees to radians.
2022-01-19 23:31:04 +00:00
**Syntax**
``` sql
radians(x)
```
**Arguments**
- `x` — Input in degrees. [Float64](../../sql-reference/data-types/float.md#float32-float64).
2022-01-19 23:31:04 +00:00
**Returned value**
- Value in radians.
2022-01-19 23:31:04 +00:00
Type: [Float64](../../sql-reference/data-types/float.md#float32-float64).
**Example**
``` sql
SELECT radians(180);
```
Result:
2023-04-19 20:33:39 +00:00
```result
2022-01-19 23:31:04 +00:00
┌──────radians(180)─┐
│ 3.141592653589793 │
└───────────────────┘
```
2022-11-10 08:03:11 +00:00
2023-04-19 20:33:39 +00:00
## factorial
2022-11-10 08:03:11 +00:00
2023-04-19 20:33:39 +00:00
Computes the factorial of an integer value. Works with any native integer type including UInt(8|16|32|64) and Int(8|16|32|64). The return type is UInt64.
2022-11-10 08:03:11 +00:00
2022-11-16 01:34:04 +00:00
The factorial of 0 is 1. Likewise, the factorial() function returns 1 for any negative value. The maximum positive value for the input argument is 20, a value of 21 or greater will cause exception throw.
2022-11-10 08:03:11 +00:00
**Syntax**
``` sql
factorial(n)
```
**Example**
``` sql
SELECT factorial(10);
```
Result:
2023-04-19 20:33:39 +00:00
```result
2022-11-10 08:03:11 +00:00
┌─factorial(10)─┐
│ 3628800 │
└───────────────┘
```
2023-02-24 00:05:40 +00:00
2023-04-19 20:33:39 +00:00
## width_bucket
2023-02-24 00:05:40 +00:00
Returns the number of the bucket in which `operand` falls in a histogram having `count` equal-width buckets spanning the range `low` to `high`. Returns `0` if `operand < low`, and returns `count+1` if `operand >= high`.
`operand`, `low`, `high` can be any native number type. `count` can only be unsigned native integer and its value cannot be zero.
**Syntax**
```sql
widthBucket(operand, low, high, count)
```
2023-04-19 20:33:39 +00:00
Alias: `WIDTH_BUCKET`
2023-02-24 00:05:40 +00:00
**Example**
``` sql
SELECT widthBucket(10.15, -8.6, 23, 18);
2023-02-24 00:05:40 +00:00
```
Result:
2023-04-19 20:33:39 +00:00
```result
┌─widthBucket(10.15, -8.6, 23, 18)─┐
│ 11 │
└──────────────────────────────────┘
```