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

   1
   2 9.2. Comparison Functions and Operators #
   3
   4    The usual comparison operators are available, as shown in Table 9.1.
   5
   6    Table 9.1. Comparison Operators
   7               Operator                  Description
   8    datatype < datatype → boolean  Less than
   9    datatype > datatype → boolean  Greater than
  10    datatype <= datatype → boolean Less than or equal to
  11    datatype >= datatype → boolean Greater than or equal to
  12    datatype = datatype → boolean  Equal
  13    datatype <> datatype → boolean Not equal
  14    datatype != datatype → boolean Not equal
  15
  16 Note
  17
  18    <> is the standard SQL notation for “not equal”. != is an alias, which
  19    is converted to <> at a very early stage of parsing. Hence, it is not
  20    possible to implement != and <> operators that do different things.
  21
  22    These comparison operators are available for all built-in data types
  23    that have a natural ordering, including numeric, string, and date/time
  24    types. In addition, arrays, composite types, and ranges can be compared
  25    if their component data types are comparable.
  26
  27    It is usually possible to compare values of related data types as well;
  28    for example integer > bigint will work. Some cases of this sort are
  29    implemented directly by “cross-type” comparison operators, but if no
  30    such operator is available, the parser will coerce the less-general
  31    type to the more-general type and apply the latter's comparison
  32    operator.
  33
  34    As shown above, all comparison operators are binary operators that
  35    return values of type boolean. Thus, expressions like 1 < 2 < 3 are not
  36    valid (because there is no < operator to compare a Boolean value with
  37    3). Use the BETWEEN predicates shown below to perform range tests.
  38
  39    There are also some comparison predicates, as shown in Table 9.2. These
  40    behave much like operators, but have special syntax mandated by the SQL
  41    standard.
  42
  43    Table 9.2. Comparison Predicates
  44
  45    Predicate
  46
  47    Description
  48
  49    Example(s)
  50
  51    datatype BETWEEN datatype AND datatype → boolean
  52
  53    Between (inclusive of the range endpoints).
  54
  55    2 BETWEEN 1 AND 3 → t
  56
  57    2 BETWEEN 3 AND 1 → f
  58
  59    datatype NOT BETWEEN datatype AND datatype → boolean
  60
  61    Not between (the negation of BETWEEN).
  62
  63    2 NOT BETWEEN 1 AND 3 → f
  64
  65    datatype BETWEEN SYMMETRIC datatype AND datatype → boolean
  66
  67    Between, after sorting the two endpoint values.
  68
  69    2 BETWEEN SYMMETRIC 3 AND 1 → t
  70
  71    datatype NOT BETWEEN SYMMETRIC datatype AND datatype → boolean
  72
  73    Not between, after sorting the two endpoint values.
  74
  75    2 NOT BETWEEN SYMMETRIC 3 AND 1 → f
  76
  77    datatype IS DISTINCT FROM datatype → boolean
  78
  79    Not equal, treating null as a comparable value.
  80
  81    1 IS DISTINCT FROM NULL → t (rather than NULL)
  82
  83    NULL IS DISTINCT FROM NULL → f (rather than NULL)
  84
  85    datatype IS NOT DISTINCT FROM datatype → boolean
  86
  87    Equal, treating null as a comparable value.
  88
  89    1 IS NOT DISTINCT FROM NULL → f (rather than NULL)
  90
  91    NULL IS NOT DISTINCT FROM NULL → t (rather than NULL)
  92
  93    datatype IS NULL → boolean
  94
  95    Test whether value is null.
  96
  97    1.5 IS NULL → f
  98
  99    datatype IS NOT NULL → boolean
 100
 101    Test whether value is not null.
 102
 103    'null' IS NOT NULL → t
 104
 105    datatype ISNULL → boolean
 106
 107    Test whether value is null (nonstandard syntax).
 108
 109    datatype NOTNULL → boolean
 110
 111    Test whether value is not null (nonstandard syntax).
 112
 113    boolean IS TRUE → boolean
 114
 115    Test whether boolean expression yields true.
 116
 117    true IS TRUE → t
 118
 119    NULL::boolean IS TRUE → f (rather than NULL)
 120
 121    boolean IS NOT TRUE → boolean
 122
 123    Test whether boolean expression yields false or unknown.
 124
 125    true IS NOT TRUE → f
 126
 127    NULL::boolean IS NOT TRUE → t (rather than NULL)
 128
 129    boolean IS FALSE → boolean
 130
 131    Test whether boolean expression yields false.
 132
 133    true IS FALSE → f
 134
 135    NULL::boolean IS FALSE → f (rather than NULL)
 136
 137    boolean IS NOT FALSE → boolean
 138
 139    Test whether boolean expression yields true or unknown.
 140
 141    true IS NOT FALSE → t
 142
 143    NULL::boolean IS NOT FALSE → t (rather than NULL)
 144
 145    boolean IS UNKNOWN → boolean
 146
 147    Test whether boolean expression yields unknown.
 148
 149    true IS UNKNOWN → f
 150
 151    NULL::boolean IS UNKNOWN → t (rather than NULL)
 152
 153    boolean IS NOT UNKNOWN → boolean
 154
 155    Test whether boolean expression yields true or false.
 156
 157    true IS NOT UNKNOWN → t
 158
 159    NULL::boolean IS NOT UNKNOWN → f (rather than NULL)
 160
 161    The BETWEEN predicate simplifies range tests:
 162 a BETWEEN x AND y
 163
 164    is equivalent to
 165 a >= x AND a <= y
 166
 167    Notice that BETWEEN treats the endpoint values as included in the
 168    range. BETWEEN SYMMETRIC is like BETWEEN except there is no requirement
 169    that the argument to the left of AND be less than or equal to the
 170    argument on the right. If it is not, those two arguments are
 171    automatically swapped, so that a nonempty range is always implied.
 172
 173    The various variants of BETWEEN are implemented in terms of the
 174    ordinary comparison operators, and therefore will work for any data
 175    type(s) that can be compared.
 176
 177 Note
 178
 179    The use of AND in the BETWEEN syntax creates an ambiguity with the use
 180    of AND as a logical operator. To resolve this, only a limited set of
 181    expression types are allowed as the second argument of a BETWEEN
 182    clause. If you need to write a more complex sub-expression in BETWEEN,
 183    write parentheses around the sub-expression.
 184
 185    Ordinary comparison operators yield null (signifying “unknown”), not
 186    true or false, when either input is null. For example, 7 = NULL yields
 187    null, as does 7 <> NULL. When this behavior is not suitable, use the IS
 188    [ NOT ] DISTINCT FROM predicates:
 189 a IS DISTINCT FROM b
 190 a IS NOT DISTINCT FROM b
 191
 192    For non-null inputs, IS DISTINCT FROM is the same as the <> operator.
 193    However, if both inputs are null it returns false, and if only one
 194    input is null it returns true. Similarly, IS NOT DISTINCT FROM is
 195    identical to = for non-null inputs, but it returns true when both
 196    inputs are null, and false when only one input is null. Thus, these
 197    predicates effectively act as though null were a normal data value,
 198    rather than “unknown”.
 199
 200    To check whether a value is or is not null, use the predicates:
 201 expression IS NULL
 202 expression IS NOT NULL
 203
 204    or the equivalent, but nonstandard, predicates:
 205 expression ISNULL
 206 expression NOTNULL
 207
 208    Do not write expression = NULL because NULL is not “equal to” NULL.
 209    (The null value represents an unknown value, and it is not known
 210    whether two unknown values are equal.)
 211
 212 Tip
 213
 214    Some applications might expect that expression = NULL returns true if
 215    expression evaluates to the null value. It is highly recommended that
 216    these applications be modified to comply with the SQL standard.
 217    However, if that cannot be done the transform_null_equals configuration
 218    variable is available. If it is enabled, PostgreSQL will convert x =
 219    NULL clauses to x IS NULL.
 220
 221    If the expression is row-valued, then IS NULL is true when the row
 222    expression itself is null or when all the row's fields are null, while
 223    IS NOT NULL is true when the row expression itself is non-null and all
 224    the row's fields are non-null. Because of this behavior, IS NULL and IS
 225    NOT NULL do not always return inverse results for row-valued
 226    expressions; in particular, a row-valued expression that contains both
 227    null and non-null fields will return false for both tests. For example:
 228 SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
 229
 230 SELECT ROW(table.*) IS NULL FROM table;  -- detect all-null rows
 231
 232 SELECT ROW(table.*) IS NOT NULL FROM table;  -- detect all-non-null rows
 233
 234 SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in
 235 rows
 236
 237    In some cases, it may be preferable to write row IS DISTINCT FROM NULL
 238    or row IS NOT DISTINCT FROM NULL, which will simply check whether the
 239    overall row value is null without any additional tests on the row
 240    fields.
 241
 242    Boolean values can also be tested using the predicates
 243 boolean_expression IS TRUE
 244 boolean_expression IS NOT TRUE
 245 boolean_expression IS FALSE
 246 boolean_expression IS NOT FALSE
 247 boolean_expression IS UNKNOWN
 248 boolean_expression IS NOT UNKNOWN
 249
 250    These will always return true or false, never a null value, even when
 251    the operand is null. A null input is treated as the logical value
 252    “unknown”. Notice that IS UNKNOWN and IS NOT UNKNOWN are effectively
 253    the same as IS NULL and IS NOT NULL, respectively, except that the
 254    input expression must be of Boolean type.
 255
 256    Some comparison-related functions are also available, as shown in
 257    Table 9.3.
 258
 259    Table 9.3. Comparison Functions
 260
 261    Function
 262
 263    Description
 264
 265    Example(s)
 266
 267    num_nonnulls ( VARIADIC "any" ) → integer
 268
 269    Returns the number of non-null arguments.
 270
 271    num_nonnulls(1, NULL, 2) → 2
 272
 273    num_nulls ( VARIADIC "any" ) → integer
 274
 275    Returns the number of null arguments.
 276
 277    num_nulls(1, NULL, 2) → 1