Mathematical functions, or arithmetic functions, perform numeric calculations that are typically more complex than basic addition, subtraction, multiplication, and division. For example, these functions include trigonometric, logarithmic, and base conversion operations.

The mathematical functions operate mainly on these data types: , , , , , , and . For the operators that perform the standard operations such as addition, subtraction, multiplication, and division, see .

Functions that perform bitwise operations are explained in .

Function reference:

Impala supports the following mathematical functions:

abs(numeric_type a)

abs() function Purpose: Returns the absolute value of the argument.

Usage notes: Use this function to ensure all return values are positive. This is different than the positive() function, which returns its argument unchanged (even if the argument was negative).

acos(double a)

acos() function Purpose: Returns the arccosine of the argument.

Return type: double

asin(double a)

asin() function Purpose: Returns the arcsine of the argument.

Return type: double

atan(double a)

atan() function Purpose: Returns the arctangent of the argument.

Return type: double

atan2(double a, double b)

atan2() function Purpose: Returns the arctangent of the two arguments, with the signs of the arguments used to determine the quadrant of the result.

Return type: double

bin(bigint a)

bin() function Purpose: Returns the binary representation of an integer value, that is, a string of 0 and 1 digits.

Return type: string

ceil(double a), ceil(decimal(p,s) a), ceiling(double a), ceiling(decimal(p,s) a), dceil(double a), dceil(decimal(p,s) a)

ceil() function Purpose: Returns the smallest integer that is greater than or equal to the argument.

Return type: Same as the input value

conv(bigint num, int from_base, int to_base), conv(string num, int from_base, int to_base)

conv() function Purpose: Returns a string representation of an integer value in a particular base. The input value can be a string, for example to convert a hexadecimal number such as fce2 to decimal. To use the return value as a number (for example, when converting to base 10), use CAST() to convert to the appropriate type.

Return type: string

cos(double a)

cos() function Purpose: Returns the cosine of the argument.

Return type: double

cosh(double a)

cosh() function Purpose: Returns the hyperbolic cosine of the argument.

Return type: double

cot(double a)

cot() function Purpose: Returns the cotangent of the argument.

Return type: double

degrees(double a)

degrees() function Purpose: Converts argument value from radians to degrees.

Return type: double

e()

e() function Purpose: Returns the mathematical constant e.

Return type: double

exp(double a), dexp(double a)

exp() function Purpose: Returns the mathematical constant e raised to the power of the argument.

Return type: double

factorial(integer_type a)

factorial() function Purpose: Computes the factorial of an integer value. It works with any integer type.

Usage notes: You can use either the factorial() function or the ! operator. 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 overflows the range for a BIGINT and causes an error.

Return type: bigint

select factorial(5); +--------------+ | factorial(5) | +--------------+ | 120 | +--------------+ select 5!; +-----+ | 5! | +-----+ | 120 | +-----+ select factorial(0); +--------------+ | factorial(0) | +--------------+ | 1 | +--------------+ select factorial(-100); +-----------------+ | factorial(-100) | +-----------------+ | 1 | +-----------------+

floor(double a), floor(decimal(p,s) a), dfloor(double a), dfloor(decimal(p,s) a)

floor() function Purpose: Returns the largest integer that is less than or equal to the argument.

Return type: Same as the input type

fmod(double a, double b), fmod(float a, float b)

fmod() function Purpose: Returns the modulus of a floating-point number. Equivalent to the % arithmetic operator.

Return type: float or double, depending on type of arguments

Because this function operates on DOUBLE or FLOAT values, it is subject to potential rounding errors for values that cannot be represented precisely. Prefer to use whole numbers, or values that you know can be represented precisely by the DOUBLE or FLOAT types.

The following examples show equivalent operations with the fmod() function and the % arithmetic operator, for values not subject to any rounding error.

select fmod(10,3); +-------------+ | fmod(10, 3) | +-------------+ | 1 | +-------------+ select fmod(5.5,2); +--------------+ | fmod(5.5, 2) | +--------------+ | 1.5 | +--------------+ select 10 % 3; +--------+ | 10 % 3 | +--------+ | 1 | +--------+ select 5.5 % 2; +---------+ | 5.5 % 2 | +---------+ | 1.5 | +---------+

The following examples show operations with the fmod() function for values that cannot be represented precisely by the DOUBLE or FLOAT types, and thus are subject to rounding error. fmod(9.9,3.0) returns a value slightly different than the expected 0.9 because of rounding. fmod(9.9,3.3) returns a value quite different from the expected value of 0 because of rounding error during intermediate calculations.

select fmod(9.9,3.0); +--------------------+ | fmod(9.9, 3.0) | +--------------------+ | 0.8999996185302734 | +--------------------+ select fmod(9.9,3.3); +-------------------+ | fmod(9.9, 3.3) | +-------------------+ | 3.299999713897705 | +-------------------+

fnv_hash(type v),

fnv_hash() function Purpose: Returns a consistent 64-bit value derived from the input argument, for convenience of implementing hashing logic in an application.

Return type: BIGINT

You might use the return value in an application where you perform load balancing, bucketing, or some other technique to divide processing or storage.

Because the result can be any 64-bit value, to restrict the value to a particular range, you can use an expression that includes the ABS() function and the % (modulo) operator. For example, to produce a hash value in the range 0-9, you could use the expression ABS(FNV_HASH(x)) % 10.

This function implements the same algorithm that Impala uses internally for hashing, on systems where the CRC32 instructions are not available.

This function implements the Fowler–Noll–Vo hash function, in particular the FNV-1a variation. This is not a perfect hash function: some combinations of values could produce the same result value. It is not suitable for cryptographic use.

Similar input values of different types could produce different hash values, for example the same numeric value represented as SMALLINT or BIGINT, FLOAT or DOUBLE, or DECIMAL(5,2) or DECIMAL(20,5).

[localhost:21000] > create table h (x int, s string); [localhost:21000] > insert into h values (0, 'hello'), (1,'world'), (1234567890,'antidisestablishmentarianism'); [localhost:21000] > select x, fnv_hash(x) from h; +------------+----------------------+ | x | fnv_hash(x) | +------------+----------------------+ | 0 | -2611523532599129963 | | 1 | 4307505193096137732 | | 1234567890 | 3614724209955230832 | +------------+----------------------+ [localhost:21000] > select s, fnv_hash(s) from h; +------------------------------+---------------------+ | s | fnv_hash(s) | +------------------------------+---------------------+ | hello | 6414202926103426347 | | world | 6535280128821139475 | | antidisestablishmentarianism | -209330013948433970 | +------------------------------+---------------------+ [localhost:21000] > select s, abs(fnv_hash(s)) % 10 from h; +------------------------------+-------------------------+ | s | abs(fnv_hash(s)) % 10.0 | +------------------------------+-------------------------+ | hello | 8 | | world | 6 | | antidisestablishmentarianism | 4 | +------------------------------+-------------------------+

For short argument values, the high-order bits of the result have relatively low entropy:

[localhost:21000] > create table b (x boolean); [localhost:21000] > insert into b values (true), (true), (false), (false); [localhost:21000] > select x, fnv_hash(x) from b; +-------+---------------------+ | x | fnv_hash(x) | +-------+---------------------+ | true | 2062020650953872396 | | true | 2062020650953872396 | | false | 2062021750465500607 | | false | 2062021750465500607 | +-------+---------------------+

Added in: Impala 1.2.2

greatest(bigint a[, bigint b ...]), greatest(double a[, double b ...]), greatest(decimal(p,s) a[, decimal(p,s) b ...]), greatest(string a[, string b ...]), greatest(timestamp a[, timestamp b ...])

greatest() function Purpose: Returns the largest value from a list of expressions.

hex(bigint a), hex(string a)

hex() function Purpose: Returns the hexadecimal representation of an integer value, or of the characters in a string.

Return type: string

is_inf(double a),

is_inf() function Purpose: Tests whether a value is equal to the special value inf, signifying infinity.

Return type: boolean

is_nan(double a),

is_nan() function Purpose: Tests whether a value is equal to the special value NaN, signifying not a number.

Return type: boolean

least(bigint a[, bigint b ...]), least(double a[, double b ...]), least(decimal(p,s) a[, decimal(p,s) b ...]), least(string a[, string b ...]), least(timestamp a[, timestamp b ...])

least() function Purpose: Returns the smallest value from a list of expressions.

ln(double a), dlog1(double a)

ln() function dlog1() function Purpose: Returns the natural logarithm of the argument.

Return type: double

log(double base, double a)

log() function Purpose: Returns the logarithm of the second argument to the specified base.

Return type: double

log10(double a), dlog10(double a)

log10() function dlog10() function Purpose: Returns the logarithm of the argument to the base 10.

Return type: double

log2(double a)

log2() function Purpose: Returns the logarithm of the argument to the base 2.

Return type: double

max_int(), max_tinyint(), max_smallint(), max_bigint()

max_int() function max_tinyint() function max_smallint() function max_bigint() function Purpose: Returns the largest value of the associated integral type.

Return type: The same as the integral type being checked.

Usage notes: Use the corresponding min_ and max_ functions to check if all values in a column are within the allowed range, before copying data or altering column definitions. If not, switch to the next higher integral type or to a DECIMAL with sufficient precision.

min_int(), min_tinyint(), min_smallint(), min_bigint()

min_int() function min_tinyint() function min_smallint() function min_bigint() function Purpose: Returns the smallest value of the associated integral type (a negative number).

Return type: The same as the integral type being checked.

Usage notes: Use the corresponding min_ and max_ functions to check if all values in a column are within the allowed range, before copying data or altering column definitions. If not, switch to the next higher integral type or to a DECIMAL with sufficient precision.

mod(numeric_type a, same_type b)

mod() function Purpose: Returns the modulus of a number. Equivalent to the % arithmetic operator. Works with any size integer type, any size floating-point type, and DECIMAL with any precision and scale.

Because this function works with DECIMAL values, prefer it over fmod() when working with fractional values. It is not subject to the rounding errors that make fmod() problematic with floating-point numbers. The % arithmetic operator now uses the mod() function in cases where its arguments can be interpreted as DECIMAL values, increasing the accuracy of that operator.

The following examples show how the mod() function works for whole numbers and fractional values, and how the % operator works the same way. In the case of mod(9.9,3), the type conversion for the second argument results in the first argument being interpreted as DOUBLE, so to produce an accurate DECIMAL result requires casting the second argument or writing it as a DECIMAL literal, 3.0.

select mod(10,3); +-------------+ | fmod(10, 3) | +-------------+ | 1 | +-------------+ select mod(5.5,2); +--------------+ | fmod(5.5, 2) | +--------------+ | 1.5 | +--------------+ select 10 % 3; +--------+ | 10 % 3 | +--------+ | 1 | +--------+ select 5.5 % 2; +---------+ | 5.5 % 2 | +---------+ | 1.5 | +---------+ select mod(9.9,3.3); +---------------+ | mod(9.9, 3.3) | +---------------+ | 0.0 | +---------------+ select mod(9.9,3); +--------------------+ | mod(9.9, 3) | +--------------------+ | 0.8999996185302734 | +--------------------+ select mod(9.9, cast(3 as decimal(2,1))); +-----------------------------------+ | mod(9.9, cast(3 as decimal(2,1))) | +-----------------------------------+ | 0.9 | +-----------------------------------+ select mod(9.9,3.0); +---------------+ | mod(9.9, 3.0) | +---------------+ | 0.9 | +---------------+

murmur_hash(type v)

murmur_hash() function Purpose: Returns a consistent 64-bit value derived from the input argument, for convenience of implementing MurmurHash2 non-cryptographic hash function.

Return type: BIGINT

You might use the return value in an application where you perform load balancing, bucketing, or some other technique to divide processing or storage. This function provides a good performance for all kinds of keys such as number, ascii string and UTF-8. It can be recommended as general-purpose hashing function.

Regarding comparison of murmur_hash with fnv_hash, murmur_hash is based on Murmur2 hash algorithm and fnv_hash function is based on FNV-1a hash algorithm. Murmur2 and FNV-1a can show very good randomness and performance compared with well known other hash algorithms, but Murmur2 slightly show better randomness and performance than FNV-1a. See [1][2][3] for details.

Similar input values of different types could produce different hash values, for example the same numeric value represented as SMALLINT or BIGINT, FLOAT or DOUBLE, or DECIMAL(5,2) or DECIMAL(20,5).

[localhost:21000] > create table h (x int, s string); [localhost:21000] > insert into h values (0, 'hello'), (1,'world'), (1234567890,'antidisestablishmentarianism'); [localhost:21000] > select x, murmur_hash(x) from h; +------------+----------------------+ | x | murmur_hash(x) | +------------+----------------------+ | 0 | 6960269033020761575 | | 1 | -780611581681153783 | | 1234567890 | -5754914572385924334 | +------------+----------------------+ [localhost:21000] > select s, murmur_hash(s) from h; +------------------------------+----------------------+ | s | murmur_hash(s) | +------------------------------+----------------------+ | hello | 2191231550387646743 | | world | 5568329560871645431 | | antidisestablishmentarianism | -2261804666958489663 | +------------------------------+----------------------+

For short argument values, the high-order bits of the result have relatively higher entropy than fnv_hash:

[localhost:21000] > create table b (x boolean); [localhost:21000] > insert into b values (true), (true), (false), (false); [localhost:21000] > select x, murmur_hash(x) from b; +-------+----------------------+ | x | murmur_hash(x) | +-------+---------------------++ | true | -5720937396023583481 | | true | -5720937396023583481 | | false | 6351753276682545529 | | false | 6351753276682545529 | +-------+--------------------+-+

Added in: Impala 2.12.0

negative(numeric_type a)

negative() function Purpose: Returns the argument with the sign reversed; returns a positive value if the argument was already negative.

Usage notes: Use -abs(a) instead if you need to ensure all return values are negative.

pi()

pi() function Purpose: Returns the constant pi.

Return type: double

pmod(bigint a, bigint b), pmod(double a, double b)

pmod() function Purpose: Returns the positive modulus of a number. Primarily for HiveQL compatibility.

Return type: int or double, depending on type of arguments

The following examples show how the fmod() function sometimes returns a negative value depending on the sign of its arguments, and the pmod() function returns the same value as fmod(), but sometimes with the sign flipped.

select fmod(-5,2); +-------------+ | fmod(-5, 2) | +-------------+ | -1 | +-------------+ select pmod(-5,2); +-------------+ | pmod(-5, 2) | +-------------+ | 1 | +-------------+ select fmod(-5,-2); +--------------+ | fmod(-5, -2) | +--------------+ | -1 | +--------------+ select pmod(-5,-2); +--------------+ | pmod(-5, -2) | +--------------+ | -1 | +--------------+ select fmod(5,-2); +-------------+ | fmod(5, -2) | +-------------+ | 1 | +-------------+ select pmod(5,-2); +-------------+ | pmod(5, -2) | +-------------+ | -1 | +-------------+

positive(numeric_type a)

positive() function Purpose: Returns the original argument unchanged (even if the argument is negative).

Usage notes: Use abs() instead if you need to ensure all return values are positive.

pow(double a, double p), power(double a, double p), dpow(double a, double p), fpow(double a, double p)

pow() function power() function dpow() function fpow() function Purpose: Returns the first argument raised to the power of the second argument.

Return type: double

precision(numeric_expression)

precision() function Purpose: Computes the precision (number of decimal digits) needed to represent the type of the argument expression as a DECIMAL value.

Typically used in combination with the scale() function, to determine the appropriate DECIMAL(precision,scale) type to declare in a CREATE TABLE statement or CAST() function.

Return type: int

quotient(bigint numerator, bigint denominator), quotient(double numerator, double denominator)

quotient() function Purpose: Returns the first argument divided by the second argument, discarding any fractional part. Avoids promoting integer arguments to DOUBLE as happens with the / SQL operator. Also includes an overload that accepts DOUBLE arguments, discards the fractional part of each argument value before dividing, and again returns BIGINT. With integer arguments, this function works the same as the DIV operator.

Return type: bigint

radians(double a)

radians() function Purpose: Converts argument value from degrees to radians.

Return type: double

rand(), rand(int seed), random(), random(int seed)

rand() function Purpose: Returns a random value between 0 and 1. After rand() is called with a seed argument, it produces a consistent random sequence based on the seed value.

Return type: double

Usage notes: Currently, the random sequence is reset after each query, and multiple calls to rand() within the same query return the same value each time. For different number sequences that are different for each query, pass a unique seed value to each call to rand(). For example, select rand(unix_timestamp()) from ...

The following examples show how rand() can produce sequences of varying predictability, so that you can reproduce query results involving random values or generate unique sequences of random values for each query. When rand() is called with no argument, it generates the same sequence of values each time, regardless of the ordering of the result set. When rand() is called with a constant integer, it generates a different sequence of values, but still always the same sequence for the same seed value. If you pass in a seed value that changes, such as the return value of the expression unix_timestamp(now()), each query will use a different sequence of random values, potentially more useful in probability calculations although more difficult to reproduce at a later time. Therefore, the final two examples with an unpredictable seed value also include the seed in the result set, to make it possible to reproduce the same random sequence later.

select x, rand() from three_rows; +---+-----------------------+ | x | rand() | +---+-----------------------+ | 1 | 0.0004714746030380365 | | 2 | 0.5895895192351144 | | 3 | 0.4431900859080209 | +---+-----------------------+ select x, rand() from three_rows order by x desc; +---+-----------------------+ | x | rand() | +---+-----------------------+ | 3 | 0.0004714746030380365 | | 2 | 0.5895895192351144 | | 1 | 0.4431900859080209 | +---+-----------------------+ select x, rand(1234) from three_rows order by x; +---+----------------------+ | x | rand(1234) | +---+----------------------+ | 1 | 0.7377511392057646 | | 2 | 0.009428468537250751 | | 3 | 0.208117277924026 | +---+----------------------+ select x, rand(1234) from three_rows order by x desc; +---+----------------------+ | x | rand(1234) | +---+----------------------+ | 3 | 0.7377511392057646 | | 2 | 0.009428468537250751 | | 1 | 0.208117277924026 | +---+----------------------+ select x, unix_timestamp(now()), rand(unix_timestamp(now())) from three_rows order by x; +---+-----------------------+-----------------------------+ | x | unix_timestamp(now()) | rand(unix_timestamp(now())) | +---+-----------------------+-----------------------------+ | 1 | 1440777752 | 0.002051228658320023 | | 2 | 1440777752 | 0.5098743483004506 | | 3 | 1440777752 | 0.9517714925817081 | +---+-----------------------+-----------------------------+ select x, unix_timestamp(now()), rand(unix_timestamp(now())) from three_rows order by x desc; +---+-----------------------+-----------------------------+ | x | unix_timestamp(now()) | rand(unix_timestamp(now())) | +---+-----------------------+-----------------------------+ | 3 | 1440777761 | 0.9985985015512437 | | 2 | 1440777761 | 0.3251255333074953 | | 1 | 1440777761 | 0.02422675025846192 | +---+-----------------------+-----------------------------+

round(double a), round(double a, int d), round(decimal a, int_type d), dround(double a), dround(double a, int d), dround(decimal(p,s) a, int_type d)

round() function dround() function Purpose: Rounds a floating-point value. By default (with a single argument), rounds to the nearest integer. Values ending in .5 are rounded up for positive numbers, down for negative numbers (that is, away from zero). The optional second argument specifies how many digits to leave after the decimal point; values greater than zero produce a floating-point return value rounded to the requested number of digits to the right of the decimal point.

Return type: Same as the input type

scale(numeric_expression)

scale() function Purpose: Computes the scale (number of decimal digits to the right of the decimal point) needed to represent the type of the argument expression as a DECIMAL value.

Typically used in combination with the precision() function, to determine the appropriate DECIMAL(precision,scale) type to declare in a CREATE TABLE statement or CAST() function.

Return type: int

sign(double a)

sign() function Purpose: Returns -1, 0, or 1 to indicate the signedness of the argument value.

Return type: int

sin(double a)

sin() function Purpose: Returns the sine of the argument.

Return type: double

sinh(double a)

sinh() function Purpose: Returns the hyperbolic sine of the argument.

Return type: double

sqrt(double a), dsqrt(double a)

sqrt() function dsqrt() function Purpose: Returns the square root of the argument.

Return type: double

tan(double a)

tan() function Purpose: Returns the tangent of the argument.

Return type: double

tanh(double a)

tanh() function Purpose: Returns the hyperbolic tangent of the argument.

Return type: double

truncate(double_or_decimal a[, digits_to_leave]), dtrunc(double_or_decimal a[, digits_to_leave]), trunc(double_or_decimal a[, digits_to_leave])

truncate() function dtrunc() function trunc() function Purpose: Removes some or all fractional digits from a numeric value.

Arguments: With a single floating-point argument, removes all fractional digits, leaving an integer value. The optional second argument specifies the number of fractional digits to include in the return value, and only applies when the argument type is DECIMAL. A second argument of 0 truncates to a whole integer value. A second argument of negative N sets N digits to 0 on the left side of the decimal

Scale argument: The scale argument applies only when truncating DECIMAL values. It is an integer specifying how many significant digits to leave to the right of the decimal point. A scale argument of 0 truncates to a whole integer value. A scale argument of negative N sets N digits to 0 on the left side of the decimal point.

truncate(), dtrunc(), and trunc() are aliases for the same function.

Return type: Same as the input type

Added in: The trunc() alias was added in .

You can also pass a DOUBLE argument, or DECIMAL argument with optional scale, to the dtrunc() or truncate functions. Using the trunc() function for numeric values is common with other industry-standard database systems, so you might find such trunc() calls in code that you are porting to Impala.

The trunc() function also has a signature that applies to TIMESTAMP values. See for details.

The following examples demonstrate the truncate() and dtrunc() signatures for this function:

select truncate(3.45); +----------------+ | truncate(3.45) | +----------------+ | 3 | +----------------+ select truncate(-3.45); +-----------------+ | truncate(-3.45) | +-----------------+ | -3 | +-----------------+ select truncate(3.456,1); +--------------------+ | truncate(3.456, 1) | +--------------------+ | 3.4 | +--------------------+ select dtrunc(3.456,1); +------------------+ | dtrunc(3.456, 1) | +------------------+ | 3.4 | +------------------+ select truncate(3.456,2); +--------------------+ | truncate(3.456, 2) | +--------------------+ | 3.45 | +--------------------+ select truncate(3.456,7); +--------------------+ | truncate(3.456, 7) | +--------------------+ | 3.4560000 | +--------------------+

The following examples demonstrate using trunc() with DECIMAL or DOUBLE values, and with an optional scale argument for DECIMAL values. (The behavior is the same for the truncate() and dtrunc() aliases also.)

create table t1 (d decimal(20,7)); -- By default, no digits to the right of the decimal point. insert into t1 values (1.1), (2.22), (3.333), (4.4444), (5.55555); select trunc(d) from t1 order by d; +----------+ | trunc(d) | +----------+ | 1 | | 2 | | 3 | | 4 | | 5 | +----------+ -- 1 digit to the right of the decimal point. select trunc(d,1) from t1 order by d; +-------------+ | trunc(d, 1) | +-------------+ | 1.1 | | 2.2 | | 3.3 | | 4.4 | | 5.5 | +-------------+ -- 2 digits to the right of the decimal point, -- including trailing zeroes if needed. select trunc(d,2) from t1 order by d; +-------------+ | trunc(d, 2) | +-------------+ | 1.10 | | 2.22 | | 3.33 | | 4.44 | | 5.55 | +-------------+ insert into t1 values (9999.9999), (8888.8888); -- Negative scale truncates digits to the left -- of the decimal point. select trunc(d,-2) from t1 where d > 100 order by d; +--------------+ | trunc(d, -2) | +--------------+ | 8800 | | 9900 | +--------------+ -- The scale of the result is adjusted to match the -- scale argument. select trunc(d,2), precision(trunc(d,2)) as p, scale(trunc(d,2)) as s from t1 order by d; +-------------+----+---+ | trunc(d, 2) | p | s | +-------------+----+---+ | 1.10 | 15 | 2 | | 2.22 | 15 | 2 | | 3.33 | 15 | 2 | | 4.44 | 15 | 2 | | 5.55 | 15 | 2 | | 8888.88 | 15 | 2 | | 9999.99 | 15 | 2 | +-------------+----+---+ create table dbl (d double); insert into dbl values (1.1), (2.22), (3.333), (4.4444), (5.55555), (8888.8888), (9999.9999); -- With double values, there is no optional scale argument. select trunc(d) from dbl order by d; +----------+ | trunc(d) | +----------+ | 1 | | 2 | | 3 | | 4 | | 5 | | 8888 | | 9999 | +----------+

unhex(string a)

unhex() function Purpose: Returns a string of characters with ASCII values corresponding to pairs of hexadecimal digits in the argument.

Return type: string