begriffs open source - ai-pg/blob - full-docs/txt/functions-conditional.txt

   1
   2 9.18. Conditional Expressions #
   3
   4    9.18.1. CASE
   5    9.18.2. COALESCE
   6    9.18.3. NULLIF
   7    9.18.4. GREATEST and LEAST
   8
   9    This section describes the SQL-compliant conditional expressions
  10    available in PostgreSQL.
  11
  12 Tip
  13
  14    If your needs go beyond the capabilities of these conditional
  15    expressions, you might want to consider writing a server-side function
  16    in a more expressive programming language.
  17
  18 Note
  19
  20    Although COALESCE, GREATEST, and LEAST are syntactically similar to
  21    functions, they are not ordinary functions, and thus cannot be used
  22    with explicit VARIADIC array arguments.
  23
  24 9.18.1. CASE #
  25
  26    The SQL CASE expression is a generic conditional expression, similar to
  27    if/else statements in other programming languages:
  28 CASE WHEN condition THEN result
  29      [WHEN ...]
  30      [ELSE result]
  31 END
  32
  33    CASE clauses can be used wherever an expression is valid. Each
  34    condition is an expression that returns a boolean result. If the
  35    condition's result is true, the value of the CASE expression is the
  36    result that follows the condition, and the remainder of the CASE
  37    expression is not processed. If the condition's result is not true, any
  38    subsequent WHEN clauses are examined in the same manner. If no WHEN
  39    condition yields true, the value of the CASE expression is the result
  40    of the ELSE clause. If the ELSE clause is omitted and no condition is
  41    true, the result is null.
  42
  43    An example:
  44 SELECT * FROM test;
  45
  46  a
  47 ---
  48  1
  49  2
  50  3
  51
  52
  53 SELECT a,
  54        CASE WHEN a=1 THEN 'one'
  55             WHEN a=2 THEN 'two'
  56             ELSE 'other'
  57        END
  58     FROM test;
  59
  60  a | case
  61 ---+-------
  62  1 | one
  63  2 | two
  64  3 | other
  65
  66    The data types of all the result expressions must be convertible to a
  67    single output type. See Section 10.5 for more details.
  68
  69    There is a “simple” form of CASE expression that is a variant of the
  70    general form above:
  71 CASE expression
  72     WHEN value THEN result
  73     [WHEN ...]
  74     [ELSE result]
  75 END
  76
  77    The first expression is computed, then compared to each of the value
  78    expressions in the WHEN clauses until one is found that is equal to it.
  79    If no match is found, the result of the ELSE clause (or a null value)
  80    is returned. This is similar to the switch statement in C.
  81
  82    The example above can be written using the simple CASE syntax:
  83 SELECT a,
  84        CASE a WHEN 1 THEN 'one'
  85               WHEN 2 THEN 'two'
  86               ELSE 'other'
  87        END
  88     FROM test;
  89
  90  a | case
  91 ---+-------
  92  1 | one
  93  2 | two
  94  3 | other
  95
  96    A CASE expression does not evaluate any subexpressions that are not
  97    needed to determine the result. For example, this is a possible way of
  98    avoiding a division-by-zero failure:
  99 SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
 100
 101 Note
 102
 103    As described in Section 4.2.14, there are various situations in which
 104    subexpressions of an expression are evaluated at different times, so
 105    that the principle that “CASE evaluates only necessary subexpressions”
 106    is not ironclad. For example a constant 1/0 subexpression will usually
 107    result in a division-by-zero failure at planning time, even if it's
 108    within a CASE arm that would never be entered at run time.
 109
 110 9.18.2. COALESCE #
 111
 112 COALESCE(value [, ...])
 113
 114    The COALESCE function returns the first of its arguments that is not
 115    null. Null is returned only if all arguments are null. It is often used
 116    to substitute a default value for null values when data is retrieved
 117    for display, for example:
 118 SELECT COALESCE(description, short_description, '(none)') ...
 119
 120    This returns description if it is not null, otherwise short_description
 121    if it is not null, otherwise (none).
 122
 123    The arguments must all be convertible to a common data type, which will
 124    be the type of the result (see Section 10.5 for details).
 125
 126    Like a CASE expression, COALESCE only evaluates the arguments that are
 127    needed to determine the result; that is, arguments to the right of the
 128    first non-null argument are not evaluated. This SQL-standard function
 129    provides capabilities similar to NVL and IFNULL, which are used in some
 130    other database systems.
 131
 132 9.18.3. NULLIF #
 133
 134 NULLIF(value1, value2)
 135
 136    The NULLIF function returns a null value if value1 equals value2;
 137    otherwise it returns value1. This can be used to perform the inverse
 138    operation of the COALESCE example given above:
 139 SELECT NULLIF(value, '(none)') ...
 140
 141    In this example, if value is (none), null is returned, otherwise the
 142    value of value is returned.
 143
 144    The two arguments must be of comparable types. To be specific, they are
 145    compared exactly as if you had written value1 = value2, so there must
 146    be a suitable = operator available.
 147
 148    The result has the same type as the first argument — but there is a
 149    subtlety. What is actually returned is the first argument of the
 150    implied = operator, and in some cases that will have been promoted to
 151    match the second argument's type. For example, NULLIF(1, 2.2) yields
 152    numeric, because there is no integer = numeric operator, only numeric =
 153    numeric.
 154
 155 9.18.4. GREATEST and LEAST #
 156
 157 GREATEST(value [, ...])
 158
 159 LEAST(value [, ...])
 160
 161    The GREATEST and LEAST functions select the largest or smallest value
 162    from a list of any number of expressions. The expressions must all be
 163    convertible to a common data type, which will be the type of the result
 164    (see Section 10.5 for details).
 165
 166    NULL values in the argument list are ignored. The result will be NULL
 167    only if all the expressions evaluate to NULL. (This is a deviation from
 168    the SQL standard. According to the standard, the return value is NULL
 169    if any argument is NULL. Some other databases behave this way.)