302291e17b
- Consider byteswap injective. - Make function case-insensitive. - Add in-code documentation and copy-paste it to the markdown docs.
12 KiB
| slug | sidebar_position | sidebar_label |
|---|---|---|
| /en/sql-reference/functions/math-functions | 125 | Mathematical |
Mathematical Functions
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.
e
Returns e.
Syntax
e()
pi
Returns π.
Syntax
pi()
exp
Returns e to the power of the given argument.
Syntax
exp(x)
log
Returns the natural logarithm of the argument.
Syntax
log(x)
Alias: ln(x)
exp2
Returns 2 to the power of the given argument
Syntax
exp2(x)
intExp2
Like exp but returns a UInt64.
Syntax
intExp2(x)
log2
Returns the binary logarithm of the argument.
Syntax
log2(x)
exp10
Returns 10 to the power of the given argument.
Syntax
exp10(x)
intExp10
Like exp10 but returns a UInt64.
Syntax
intExp10(x)
log10
Returns the decimal logarithm of the argument.
Syntax
log10(x)
sqrt
Returns the square root of the argument.
sqrt(x)
cbrt
Returns the cubic root of the argument.
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
erf(x)
Example
(three sigma rule)
SELECT erf(3 / sqrt(2));
┌─erf(divide(3, sqrt(2)))─┐
│ 0.9973002039367398 │
└─────────────────────────┘
erfc
Returns a number close to 1 - erf(x) without loss of precision for large ‘x’ values.
Syntax
erfc(x)
lgamma
Returns the logarithm of the gamma function.
Syntax
lgamma(x)
tgamma
Returns the gamma function.
Syntax
gamma(x)
sin
Returns the sine of the argument
Syntax
sin(x)
cos
Returns the cosine of the argument.
Syntax
cos(x)
tan
Returns the tangent of the argument.
Syntax
tan(x)
asin
Returns the arc sine of the argument.
Syntax
asin(x)
acos
Returns the arc cosine of the argument.
Syntax
acos(x)
atan
Returns the arc tangent of the argument.
Syntax
atan(x)
pow
Returns x to the power of y.
Syntax
pow(x, y)
Alias: power(x, y)
cosh
Returns the hyperbolic cosine of the argument.
Syntax
cosh(x)
Arguments
x— The angle, in radians. Values from the interval:-∞ < x < +∞. Float64.
Returned value
- Values from the interval:
1 <= cosh(x) < +∞.
Type: Float64.
Example
SELECT cosh(0);
Result:
┌─cosh(0)──┐
│ 1 │
└──────────┘
acosh
Returns the inverse hyperbolic cosine.
Syntax
acosh(x)
Arguments
x— Hyperbolic cosine of angle. Values from the interval:1 <= x < +∞. Float64.
Returned value
- The angle, in radians. Values from the interval:
0 <= acosh(x) < +∞.
Type: Float64.
Example
SELECT acosh(1);
Result:
┌─acosh(1)─┐
│ 0 │
└──────────┘
sinh
Returns the hyperbolic sine.
Syntax
sinh(x)
Arguments
x— The angle, in radians. Values from the interval:-∞ < x < +∞. Float64.
Returned value
- Values from the interval:
-∞ < sinh(x) < +∞.
Type: Float64.
Example
SELECT sinh(0);
Result:
┌─sinh(0)──┐
│ 0 │
└──────────┘
asinh
Returns the inverse hyperbolic sine.
Syntax
asinh(x)
Arguments
x— Hyperbolic sine of angle. Values from the interval:-∞ < x < +∞. Float64.
Returned value
- The angle, in radians. Values from the interval:
-∞ < asinh(x) < +∞.
Type: Float64.
Example
SELECT asinh(0);
Result:
┌─asinh(0)─┐
│ 0 │
└──────────┘
atanh
Returns the inverse hyperbolic tangent.
Syntax
atanh(x)
Arguments
x— Hyperbolic tangent of angle. Values from the interval:–1 < x < 1. Float64.
Returned value
- The angle, in radians. Values from the interval:
-∞ < atanh(x) < +∞.
Type: Float64.
Example
SELECT atanh(0);
Result:
┌─atanh(0)─┐
│ 0 │
└──────────┘
atan2
Returns the 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
atan2(y, x)
Arguments
y— y-coordinate of the point through which the ray passes. Float64.x— x-coordinate of the point through which the ray passes. Float64.
Returned value
- The angle
θsuch that−π < θ ≤ π, in radians.
Type: Float64.
Example
SELECT atan2(1, 1);
Result:
┌────────atan2(1, 1)─┐
│ 0.7853981633974483 │
└────────────────────┘
hypot
Returns the length of the hypotenuse of a right-angle triangle. Hypot avoids problems that occur when squaring very large or very small numbers.
Syntax
hypot(x, y)
Arguments
x— The first cathetus of a right-angle triangle. Float64.y— The second cathetus of a right-angle triangle. Float64.
Returned value
- The length of the hypotenuse of a right-angle triangle.
Type: Float64.
Example
SELECT hypot(1, 1);
Result:
┌────────hypot(1, 1)─┐
│ 1.4142135623730951 │
└────────────────────┘
log1p
Calculates log(1+x). The calculation log1p(x) is more accurate than log(1+x) for small values of x.
Syntax
log1p(x)
Arguments
x— Values from the interval:-1 < x < +∞. Float64.
Returned value
- Values from the interval:
-∞ < log1p(x) < +∞.
Type: Float64.
Example
SELECT log1p(0);
Result:
┌─log1p(0)─┐
│ 0 │
└──────────┘
sign
Returns the sign of a real number.
Syntax
sign(x)
Arguments
x— Values from-∞to+∞. Support all numeric types in ClickHouse.
Returned value
- -1 for
x < 0 - 0 for
x = 0 - 1 for
x > 0
Examples
Sign for the zero value:
SELECT sign(0);
Result:
┌─sign(0)─┐
│ 0 │
└─────────┘
Sign for the positive value:
SELECT sign(1);
Result:
┌─sign(1)─┐
│ 1 │
└─────────┘
Sign for the negative value:
SELECT sign(-1);
Result:
┌─sign(-1)─┐
│ -1 │
└──────────┘
degrees
Converts radians to degrees.
Syntax
degrees(x)
Arguments
x— Input in radians. Float64.
Returned value
- Value in degrees.
Type: Float64.
Example
SELECT degrees(3.141592653589793);
Result:
┌─degrees(3.141592653589793)─┐
│ 180 │
└────────────────────────────┘
radians
Converts degrees to radians.
Syntax
radians(x)
Arguments
x— Input in degrees. Float64.
Returned value
- Value in radians.
Type: Float64.
Example
SELECT radians(180);
Result:
┌──────radians(180)─┐
│ 3.141592653589793 │
└───────────────────┘
factorial
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.
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.
Syntax
factorial(n)
Example
SELECT factorial(10);
Result:
┌─factorial(10)─┐
│ 3628800 │
└───────────────┘
width_bucket
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
widthBucket(operand, low, high, count)
Alias: WIDTH_BUCKET
Example
SELECT widthBucket(10.15, -8.6, 23, 18);
Result:
┌─widthBucket(10.15, -8.6, 23, 18)─┐
│ 11 │
└──────────────────────────────────┘
byteSwap
Accepts an unsigned integer operand and returns the integer which is obtained by swapping the endianness of operand i.e. reversing the bytes of the operand.
Currently, this is implemented for UInt8, UInt16, UInt32 and UInt64.
Example
byteSwap(3351772109)
Result:
┌─byteSwap(3351772109)─┐
│ 3455829959 │
└──────────────────────┘
The above example can be worked out in the following manner:
- First, convert the integer operand (base 10) to its equivalent hexadecimal interpretation (base 16) in big-endian format i.e. 3351772109 -> C7 C7 FB CD (4 bytes)
- Then, reverse the bytes i.e. C7 C7 FB CD -> CD FB C7 C7
- Finally, the convert the hexadecimal number back to an integer assuming big-endian i.e. CD FB C7 C7 -> 3455829959
Note that, in step#1, one can also choose to convert the operand to bytes in little-endian as long as one also assumes little-endian when converting back to integer in step#3.
One use-case of this function is reversing IPv4s:
┌─toIPv4(3351772109)─┐
│ 199.199.251.205 │
└────────────────────┘
┌─toIPv4(byteSwap(3351772109))─┐
│ 205.251.199.199 │
└──────────────────────────────┘