459 lines
9.0 KiB
Plaintext
459 lines
9.0 KiB
Plaintext
[role="xpack"]
|
||
[testenv="basic"]
|
||
[[sql-functions-conditional]]
|
||
=== Conditional Functions And Expressions
|
||
|
||
Functions that return one of their arguments by evaluating in an if-else manner.
|
||
|
||
[[sql-functions-conditional-case]]
|
||
==== `CASE`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
CASE WHEN condition THEN result
|
||
[WHEN ...]
|
||
[ELSE default_result]
|
||
END
|
||
----
|
||
|
||
*Input*:
|
||
|
||
One or multiple _WHEN *condition* THEN *result_* clauses are used and the expression can optionally have
|
||
an _ELSE *default_result_* clause. Every *condition* should be a boolean expression.
|
||
|
||
*Output*: one of the *result* expressions if the corresponding _WHEN *condition_* evaluates to `true` or
|
||
the *default_result* if all _WHEN *condition_* clauses evaluate to `false`. If the optional _ELSE *default_result_*
|
||
clause is missing and all _WHEN *condition_* clauses evaluate to `false` then `null` is returned.
|
||
|
||
.Description
|
||
|
||
The CASE expression is a generic conditional expression which simulates if/else statements of other programming languages
|
||
If the condition’s result is true, the value of the result expression that follows the condition will be the returned
|
||
the subsequent when clauses will be skipped and not processed.
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[case]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[caseReturnNull]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[caseWithElse]
|
||
----
|
||
|
||
|
||
As a variant, a case expression can be expressed with a syntax similar to *switch-case* of other programming languages:
|
||
[source, sql]
|
||
----
|
||
CASE expression
|
||
WHEN value1 THEN result1
|
||
[WHEN value2 THEN result2]
|
||
[WHEN ...]
|
||
[ELSE default_result]
|
||
END
|
||
----
|
||
|
||
In this case it's transformed internally to:
|
||
[source, sql]
|
||
----
|
||
CASE WHEN expression = value1 THEN result1
|
||
[WHEN expression = value2 THEN result2]
|
||
[WHEN ...]
|
||
[ELSE default_result]
|
||
END
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[caseWithOperand]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[caseWithOperandAndElse]
|
||
----
|
||
|
||
[NOTE]
|
||
===============================
|
||
All result expressions must be of compatible data types. More specifically all result
|
||
expressions should have a compatible data type with the 1st _non-null_ result expression.
|
||
E.g.:
|
||
|
||
for the following query:
|
||
|
||
[source, sql]
|
||
CASE WHEN a = 1 THEN null
|
||
WHEN a > 2 THEN 10
|
||
WHEN a > 5 THEN 'foo'
|
||
END
|
||
|
||
an error message would be returned, mentioning that *'foo'* is of data type *keyword*,
|
||
which does not match the expected data type *integer* (based on result *10*).
|
||
===============================
|
||
|
||
[[sql-functions-conditional-case-groupby-custom-buckets]]
|
||
===== Conditional bucketing
|
||
|
||
CASE can be used as a GROUP BY key in a query to facilitate custom bucketing
|
||
and assign descriptive names to those buckets. If, for example, the values
|
||
for a key are too many or, simply, ranges of those values are more
|
||
interesting than every single value, CASE can create custom buckets as in the
|
||
following example:
|
||
|
||
[source, sql]
|
||
SELECT count(*) AS count,
|
||
CASE WHEN NVL(languages, 0) = 0 THEN 'zero'
|
||
WHEN languages = 1 THEN 'one'
|
||
WHEN languages = 2 THEN 'bilingual'
|
||
WHEN languages = 3 THEN 'trilingual'
|
||
ELSE 'multilingual'
|
||
END as lang_skills
|
||
FROM employees
|
||
GROUP BY lang_skills
|
||
ORDER BY lang_skills;
|
||
|
||
With this query, one can create normal grouping buckets for values _0, 1, 2, 3_ with
|
||
descriptive names, and every value _>= 4_ falls into the _multilingual_ bucket.
|
||
|
||
[[sql-functions-conditional-coalesce]]
|
||
==== `COALESCE`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
COALESCE(
|
||
expression, <1>
|
||
expression, <2>
|
||
...)
|
||
----
|
||
|
||
*Input*:
|
||
|
||
<1> 1st expression
|
||
|
||
<2> 2nd expression
|
||
|
||
...
|
||
|
||
**N**th expression
|
||
|
||
COALESCE can take an arbitrary number of arguments.
|
||
|
||
*Output*: one of the expressions or `null`
|
||
|
||
.Description
|
||
|
||
Returns the first of its arguments that is not null.
|
||
If all arguments are null, then it returns `null`.
|
||
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[coalesceReturnNonNull]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[coalesceReturnNull]
|
||
----
|
||
|
||
[[sql-functions-conditional-greatest]]
|
||
==== `GREATEST`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
GREATEST(
|
||
expression, <1>
|
||
expression, <2>
|
||
...)
|
||
----
|
||
|
||
*Input*:
|
||
|
||
<1> 1st expression
|
||
|
||
<2> 2nd expression
|
||
|
||
...
|
||
|
||
**N**th expression
|
||
|
||
GREATEST can take an arbitrary number of arguments and
|
||
all of them must be of the same data type.
|
||
|
||
*Output*: one of the expressions or `null`
|
||
|
||
.Description
|
||
|
||
Returns the argument that has the largest value which is not null.
|
||
If all arguments are null, then it returns `null`.
|
||
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNonNull]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[greatestReturnNull]
|
||
----
|
||
|
||
[[sql-functions-conditional-ifnull]]
|
||
==== `IFNULL`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
IFNULL(
|
||
expression, <1>
|
||
expression) <2>
|
||
----
|
||
|
||
*Input*:
|
||
|
||
<1> 1st expression
|
||
|
||
<2> 2nd expression
|
||
|
||
|
||
*Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
|
||
|
||
.Description
|
||
|
||
Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
|
||
Returns the first of its arguments that is not null.
|
||
If all arguments are null, then it returns `null`.
|
||
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[ifNullReturnFirst]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[ifNullReturnSecond]
|
||
----
|
||
|
||
[[sql-functions-conditional-iif]]
|
||
==== `IFF`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
IIF(expression, <1>
|
||
expression, <2>
|
||
[expression]) <3>
|
||
----
|
||
|
||
*Input*:
|
||
|
||
<1> boolean condition to check
|
||
|
||
<2> return value if the boolean condition evaluates to `true`
|
||
|
||
<3> return value if the boolean condition evaluates `false`; optional
|
||
|
||
*Output*: 2nd expression if 1st expression (condition) evaluates to `true`. If it evaluates to `false`
|
||
return 3rd expression. If 3rd expression is not provided return `null`.
|
||
|
||
.Description
|
||
|
||
Conditional function that implements the standard _IF <condition> THEN <result1> ELSE <result2>_
|
||
logic of programming languages. If the 3rd expression is not provided and the condition evaluates to `false`,
|
||
`null` is returned.
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[iifWithDefaultValue]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[iifWithoutDefaultValue]
|
||
----
|
||
|
||
[TIP]
|
||
=================
|
||
*IIF* functions can be combined to implement more complex logic simulating the <<sql-functions-conditional-case>>
|
||
expression. E.g.:
|
||
|
||
[source, sql]
|
||
IIF(a = 1, 'one', IIF(a = 2, 'two', IIF(a = 3, 'three', 'many')))
|
||
=================
|
||
|
||
|
||
[[sql-functions-conditional-isnull]]
|
||
==== `ISNULL`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
ISNULL(
|
||
expression, <1>
|
||
expression) <2>
|
||
----
|
||
|
||
*Input*:
|
||
|
||
<1> 1st expression
|
||
|
||
<2> 2nd expression
|
||
|
||
|
||
*Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
|
||
|
||
.Description
|
||
|
||
Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
|
||
Returns the first of its arguments that is not null.
|
||
If all arguments are null, then it returns `null`.
|
||
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[isNullReturnFirst]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[isNullReturnSecond]
|
||
----
|
||
|
||
|
||
[[sql-functions-conditional-least]]
|
||
==== `LEAST`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
LEAST(
|
||
expression, <1>
|
||
expression, <2>
|
||
...)
|
||
----
|
||
|
||
*Input*:
|
||
|
||
<1> 1st expression
|
||
|
||
<2> 2nd expression
|
||
|
||
...
|
||
|
||
**N**th expression
|
||
|
||
LEAST can take an arbitrary number of arguments and
|
||
all of them must be of the same data type.
|
||
|
||
*Output*: one of the expressions or `null`
|
||
|
||
.Description
|
||
|
||
Returns the argument that has the smallest value which is not null.
|
||
If all arguments are null, then it returns `null`.
|
||
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNonNull]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[leastReturnNull]
|
||
----
|
||
|
||
|
||
[[sql-functions-conditional-nullif]]
|
||
==== `NULLIF`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
NULLIF(
|
||
expression, <1>
|
||
expression) <2>
|
||
----
|
||
|
||
*Input*:
|
||
|
||
<1> 1st expression
|
||
|
||
<2> 2nd expression
|
||
|
||
|
||
*Output*: `null` if the 2 expressions are equal, otherwise the 1st expression.
|
||
|
||
.Description
|
||
|
||
Returns `null` when the two input expressions are equal and
|
||
if not, it returns the 1st expression.
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnFirst]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[nullIfReturnNull]
|
||
----
|
||
|
||
|
||
[[sql-functions-conditional-nvl]]
|
||
==== `NVL`
|
||
|
||
.Synopsis:
|
||
[source, sql]
|
||
----
|
||
NVL(
|
||
expression, <1>
|
||
expression) <2>
|
||
----
|
||
|
||
*Input*:
|
||
|
||
<1> 1st expression
|
||
|
||
<2> 2nd expression
|
||
|
||
|
||
*Output*: 2nd expression if 1st expression is null, otherwise 1st expression.
|
||
|
||
.Description
|
||
|
||
Variant of <<sql-functions-conditional-coalesce>> with only two arguments.
|
||
Returns the first of its arguments that is not null.
|
||
If all arguments are null, then it returns `null`.
|
||
|
||
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnFirst]
|
||
----
|
||
|
||
[source, sql]
|
||
----
|
||
include-tagged::{sql-specs}/docs/docs.csv-spec[nvlReturnSecond]
|
||
----
|
||
|
||
|