Impala Conditional Functions

Impala supports the following conditional functions for testing equality, comparison operators, and nullity:

CASE a WHEN b THEN c [WHEN d THEN e]... [ELSE f] END

Purpose: Compares an expression to one or more possible values, and returns a corresponding result when a match is found.

Return type: same as the initial argument value, except that integer values are promoted to BIGINT and floating-point values are promoted to DOUBLE; use CAST() when inserting into a smaller numeric column

Usage notes:

In this form of the CASE expression, the initial value A being evaluated for each row it typically a column reference, or an expression involving a column. This form can only compare against a set of specified values, not ranges, multi-value comparisons such as BETWEEN or IN, regular expressions, or NULL.

Examples:

Although this example is split across multiple lines, you can put any or all parts of a CASE expression on a single line, with no punctuation or other separators between the WHEN, ELSE, and END clauses.

  1. select case x
  2.     when 1 then 'one'
  3.     when 2 then 'two'
  4.     when 0 then 'zero'
  5.     else 'out of range'
  6.   end
  7.     from t1;

CASE WHEN a THEN b [WHEN c THEN d]... [ELSE e] END

Purpose: Tests whether any of a sequence of expressions is true, and returns a corresponding result for the first true expression.

Return type: same as the initial argument value, except that integer values are promoted to BIGINT and floating-point values are promoted to DOUBLE; use CAST() when inserting into a smaller numeric column

Usage notes:

CASE expressions without an initial test value have more flexibility. For example, they can test different columns in different WHEN clauses, or use comparison operators such as BETWEEN, IN and IS NULL rather than comparing against discrete values.

CASE expressions are often the foundation of long queries that summarize and format results for easy-to-read reports. For example, you might use a CASE function call to turn values from a numeric column into category strings corresponding to integer values, or labels such as “Small”, “Medium” and “Large” based on ranges. Then subsequent parts of the query might aggregate based on the transformed values, such as how many values are classified as small, medium, or large. You can also use CASE to signal problems with out-of-bounds values, NULL values, and so on.

By using operators such as OR, IN, REGEXP, and so on in CASE expressions, you can build extensive tests and transformations into a single query. Therefore, applications that construct SQL statements often rely heavily on CASE calls in the generated SQL code.

Because this flexible form of the CASE expressions allows you to perform many comparisons and call multiple functions when evaluating each row, be careful applying elaborate CASE expressions to queries that process large amounts of data. For example, when practical, evaluate and transform values through CASE after applying operations such as aggregations that reduce the size of the result set; transform numbers to strings after performing joins with the original numeric values.

Examples:

Although this example is split across multiple lines, you can put any or all parts of a CASE expression on a single line, with no punctuation or other separators between the WHEN, ELSE, and END clauses.

  1. select case
  2.     when dayname(now()) in ('Saturday','Sunday') then 'result undefined on weekends'
  3.     when x > y then 'x greater than y'
  4.     when x = y then 'x and y are equal'
  5.     when x is null or y is null then 'one of the columns is null'
  6.     else null
  7.   end
  8.     from t1;

coalesce(type v1, type v2, ...)

Purpose: Returns the first specified argument that is not NULL, or NULL if all arguments are NULL.

Return type: same as the initial argument value, except that integer values are promoted to BIGINT and floating-point values are promoted to DOUBLE; use CAST() when inserting into a smaller numeric column

decode(type expression, type search1, type result1 [, type search2, type result2 ...] [, type default] )

Purpose: Compares an expression to one or more possible values, and returns a corresponding result when a match is found.

Return type: same as the initial argument value, except that integer values are promoted to BIGINT and floating-point values are promoted to DOUBLE; use CAST() when inserting into a smaller numeric column

Usage notes:

Can be used as shorthand for a CASE expression.

The original expression and the search expressions must of the same type or convertible types. The result expression can be a different type, but all result expressions must be of the same type.

Returns a successful match If the original expression is NULL and a search expression is also NULL. the

Returns NULL if the final default value is omitted and none of the search expressions match the original expression.

Examples:

The following example translates numeric day values into descriptive names:

  1. SELECT event, decode(day_of_week, 1, "Monday", 2, "Tuesday", 3, "Wednesday",
  2.   4, "Thursday", 5, "Friday", 6, "Saturday", 7, "Sunday", "Unknown day")
  3.   FROM calendar;

if(boolean condition, type ifTrue, type ifFalseOrNull)

Purpose: Tests an expression and returns a corresponding result depending on whether the result is true, false, or NULL.

Return type: Same as the ifTrue argument value

ifnull(type a, type ifNull)

Purpose: Alias for the isnull() function, with the same behavior. To simplify porting SQL with vendor extensions to Impala.

Added in: Impala 1.3.0

isfalse(boolean)

Purpose: Tests if a Boolean expression is false or not. Returns true if so. If the argument is NULL, returns false. Identical to isnottrue(), except it returns the opposite value for a NULL argument.

Return type: BOOLEAN

Added in: Impala 2.2.0

Usage notes:

In Impala 2.11 and higher, you can use the operators IS [NOT] TRUE and IS [NOT] FALSE as equivalents for the built-in functions istrue(), isnottrue(), isfalse(), and isnotfalse().

isnotfalse(boolean)

Purpose: Tests if a Boolean expression is not false (that is, either true or NULL). Returns true if so. If the argument is NULL, returns true. Identical to istrue(), except it returns the opposite value for a NULL argument.

Return type: BOOLEAN

Usage notes: Primarily for compatibility with code containing industry extensions to SQL.

Added in: Impala 2.2.0

Usage notes:

In Impala 2.11 and higher, you can use the operators IS [NOT] TRUE and IS [NOT] FALSE as equivalents for the built-in functions istrue(), isnottrue(), isfalse(), and isnotfalse().

isnottrue(boolean)

Purpose: Tests if a Boolean expression is not true (that is, either false or NULL). Returns true if so. If the argument is NULL, returns true. Identical to isfalse(), except it returns the opposite value for a NULL argument.

Return type: BOOLEAN

Added in: Impala 2.2.0

Usage notes:

In Impala 2.11 and higher, you can use the operators IS [NOT] TRUE and IS [NOT] FALSE as equivalents for the built-in functions istrue(), isnottrue(), isfalse(), and isnotfalse().

isnull(type a, type ifNull)

Purpose: Tests if an expression is NULL, and returns the expression result value if not. If the first argument is NULL, returns the second argument.

Compatibility notes: Equivalent to the nvl() function from Oracle Database or ifnull() from MySQL. The nvl() and ifnull() functions are also available in Impala.

Return type: Same as the first argument value

istrue(boolean)

Purpose: Tests if a Boolean expression is true or not. Returns true if so. If the argument is NULL, returns false. Identical to isnotfalse(), except it returns the opposite value for a NULL argument.

Return type: BOOLEAN

Usage notes: Primarily for compatibility with code containing industry extensions to SQL.

Added in: Impala 2.2.0

Usage notes:

In Impala 2.11 and higher, you can use the operators IS [NOT] TRUE and IS [NOT] FALSE as equivalents for the built-in functions istrue(), isnottrue(), isfalse(), and isnotfalse().

nonnullvalue(expression)

Purpose: Tests if an expression (of any type) is NULL or not. Returns false if so. The converse of nullvalue().

Return type: BOOLEAN

Usage notes: Primarily for compatibility with code containing industry extensions to SQL.

Added in: Impala 2.2.0

nullif(expr1,expr2)

Purpose: Returns NULL if the two specified arguments are equal. If the specified arguments are not equal, returns the value of expr1. The data types of the expressions must be compatible, according to the conversion rules from Data Types. You cannot use an expression that evaluates to NULL for expr1; that way, you can distinguish a return value of NULL from an argument value of NULL, which would never match expr2.

Usage notes: This function is effectively shorthand for a CASE expression of the form:

  1. CASE
  2.   WHEN expr1 = expr2 THEN NULL
  3.   ELSE expr1
  4. END

It is commonly used in division expressions, to produce a NULL result instead of a divide-by-zero error when the divisor is equal to zero:

  1. select 1.0 / nullif(c1,0) as reciprocal from t1;

You might also use it for compatibility with other database systems that support the same NULLIF() function.

Return type: same as the initial argument value, except that integer values are promoted to BIGINT and floating-point values are promoted to DOUBLE; use CAST() when inserting into a smaller numeric column

Added in: Impala 1.3.0

nullifzero(numeric_expr)

Purpose: Returns NULL if the numeric expression evaluates to 0, otherwise returns the result of the expression.

Usage notes: Used to avoid error conditions such as divide-by-zero in numeric calculations. Serves as shorthand for a more elaborate CASE expression, to simplify porting SQL with vendor extensions to Impala.

Return type: same as the initial argument value, except that integer values are promoted to BIGINT and floating-point values are promoted to DOUBLE; use CAST() when inserting into a smaller numeric column

Added in: Impala 1.3.0

nullvalue(expression)

Purpose: Tests if an expression (of any type) is NULL or not. Returns true if so. The converse of nonnullvalue().

Return type: BOOLEAN

Usage notes: Primarily for compatibility with code containing industry extensions to SQL.

Added in: Impala 2.2.0

nvl(type a, type ifNull)

Purpose: Alias for the isnull() function. Tests if an expression is NULL, and returns the expression result value if not. If the first argument is NULL, returns the second argument. Equivalent to the nvl() function from Oracle Database or ifnull() from MySQL.

Return type: Same as the first argument value

Added in: Impala 1.1

nvl2(type a, type ifNull, type ifNotNull)

Purpose: Enhanced variant of the nvl() function. Tests an expression and returns different result values depending on whether it is NULL or not. If the first argument is NULL, returns the second argument. If the first argument is not NULL, returns the third argument. Equivalent to the nvl2() function from Oracle Database.

Return type: Same as the first argument value

Added in: Impala 2.9.0

Examples:

The following examples show how a query can use special indicator values to represent null and not-null expression values. The first example tests an INT column and so uses special integer values. The second example tests a STRING column and so uses special string values.

  2. select x, nvl2(x, 999, 0) from nvl2_demo;
  3. +------+---------------------------+
  4. | x    | if(x is not null, 999, 0) |
  5. +------+---------------------------+
  6. | NULL | 0                         |
  7. | 1    | 999                       |
  8. | NULL | 0                         |
  9. | 2    | 999                       |
  10. +------+---------------------------+
  12. select s, nvl2(s, 'is not null', 'is null') from nvl2_demo;
  13. +------+---------------------------------------------+
  14. | s    | if(s is not null, 'is not null', 'is null') |
  15. +------+---------------------------------------------+
  16. | NULL | is null                                     |
  17. | one  | is not null                                 |
  18. | NULL | is null                                     |
  19. | two  | is not null                                 |
  20. +------+---------------------------------------------+

zeroifnull(numeric_expr)

Purpose: Returns 0 if the numeric expression evaluates to NULL, otherwise returns the result of the expression.

Usage notes: Used to avoid unexpected results due to unexpected propagation of NULL values in numeric calculations. Serves as shorthand for a more elaborate CASE expression, to simplify porting SQL with vendor extensions to Impala.

Return type: same as the initial argument value, except that integer values are promoted to BIGINT and floating-point values are promoted to DOUBLE; use CAST() when inserting into a smaller numeric column

Added in: Impala 1.3.0

Parent topic: Impala Built-In Functions