begriffs open source - ai-pg/blob - full-docs/txt/typeconv-oper.txt

   1
   2 10.2. Operators #
   3
   4    The specific operator that is referenced by an operator expression is
   5    determined using the following procedure. Note that this procedure is
   6    indirectly affected by the precedence of the operators involved, since
   7    that will determine which sub-expressions are taken to be the inputs of
   8    which operators. See Section 4.1.6 for more information.
   9
  10    Operator Type Resolution
  11     1. Select the operators to be considered from the pg_operator system
  12        catalog. If a non-schema-qualified operator name was used (the
  13        usual case), the operators considered are those with the matching
  14        name and argument count that are visible in the current search path
  15        (see Section 5.10.3). If a qualified operator name was given, only
  16        operators in the specified schema are considered.
  17          a. If the search path finds multiple operators with identical
  18             argument types, only the one appearing earliest in the path is
  19             considered. Operators with different argument types are
  20             considered on an equal footing regardless of search path
  21             position.
  22     2. Check for an operator accepting exactly the input argument types.
  23        If one exists (there can be only one exact match in the set of
  24        operators considered), use it. Lack of an exact match creates a
  25        security hazard when calling, via qualified name ^[9] (not
  26        typical), any operator found in a schema that permits untrusted
  27        users to create objects. In such situations, cast arguments to
  28        force an exact match.
  29          a. If one argument of a binary operator invocation is of the
  30             unknown type, then assume it is the same type as the other
  31             argument for this check. Invocations involving two unknown
  32             inputs, or a prefix operator with an unknown input, will never
  33             find a match at this step.
  34          b. If one argument of a binary operator invocation is of the
  35             unknown type and the other is of a domain type, next check to
  36             see if there is an operator accepting exactly the domain's
  37             base type on both sides; if so, use it.
  38     3. Look for the best match.
  39          a. Discard candidate operators for which the input types do not
  40             match and cannot be converted (using an implicit conversion)
  41             to match. unknown literals are assumed to be convertible to
  42             anything for this purpose. If only one candidate remains, use
  43             it; else continue to the next step.
  44          b. If any input argument is of a domain type, treat it as being
  45             of the domain's base type for all subsequent steps. This
  46             ensures that domains act like their base types for purposes of
  47             ambiguous-operator resolution.
  48          c. Run through all candidates and keep those with the most exact
  49             matches on input types. Keep all candidates if none have exact
  50             matches. If only one candidate remains, use it; else continue
  51             to the next step.
  52          d. Run through all candidates and keep those that accept
  53             preferred types (of the input data type's type category) at
  54             the most positions where type conversion will be required.
  55             Keep all candidates if none accept preferred types. If only
  56             one candidate remains, use it; else continue to the next step.
  57          e. If any input arguments are unknown, check the type categories
  58             accepted at those argument positions by the remaining
  59             candidates. At each position, select the string category if
  60             any candidate accepts that category. (This bias towards string
  61             is appropriate since an unknown-type literal looks like a
  62             string.) Otherwise, if all the remaining candidates accept the
  63             same type category, select that category; otherwise fail
  64             because the correct choice cannot be deduced without more
  65             clues. Now discard candidates that do not accept the selected
  66             type category. Furthermore, if any candidate accepts a
  67             preferred type in that category, discard candidates that
  68             accept non-preferred types for that argument. Keep all
  69             candidates if none survive these tests. If only one candidate
  70             remains, use it; else continue to the next step.
  71          f. If there are both unknown and known-type arguments, and all
  72             the known-type arguments have the same type, assume that the
  73             unknown arguments are also of that type, and check which
  74             candidates can accept that type at the unknown-argument
  75             positions. If exactly one candidate passes this test, use it.
  76             Otherwise, fail.
  77
  78    Some examples follow.
  79
  80    Example 10.1. Square Root Operator Type Resolution
  81
  82    There is only one square root operator (prefix |/) defined in the
  83    standard catalog, and it takes an argument of type double precision.
  84    The scanner assigns an initial type of integer to the argument in this
  85    query expression:
  86 SELECT |/ 40 AS "square root of 40";
  87  square root of 40
  88 -------------------
  89  6.324555320336759
  90 (1 row)
  91
  92    So the parser does a type conversion on the operand and the query is
  93    equivalent to:
  94 SELECT |/ CAST(40 AS double precision) AS "square root of 40";
  95
  96    Example 10.2. String Concatenation Operator Type Resolution
  97
  98    A string-like syntax is used for working with string types and for
  99    working with complex extension types. Strings with unspecified type are
 100    matched with likely operator candidates.
 101
 102    An example with one unspecified argument:
 103 SELECT text 'abc' || 'def' AS "text and unknown";
 104
 105  text and unknown
 106 ------------------
 107  abcdef
 108 (1 row)
 109
 110    In this case the parser looks to see if there is an operator taking
 111    text for both arguments. Since there is, it assumes that the second
 112    argument should be interpreted as type text.
 113
 114    Here is a concatenation of two values of unspecified types:
 115 SELECT 'abc' || 'def' AS "unspecified";
 116
 117  unspecified
 118 -------------
 119  abcdef
 120 (1 row)
 121
 122    In this case there is no initial hint for which type to use, since no
 123    types are specified in the query. So, the parser looks for all
 124    candidate operators and finds that there are candidates accepting both
 125    string-category and bit-string-category inputs. Since string category
 126    is preferred when available, that category is selected, and then the
 127    preferred type for strings, text, is used as the specific type to
 128    resolve the unknown-type literals as.
 129
 130    Example 10.3. Absolute-Value and Negation Operator Type Resolution
 131
 132    The PostgreSQL operator catalog has several entries for the prefix
 133    operator @, all of which implement absolute-value operations for
 134    various numeric data types. One of these entries is for type float8,
 135    which is the preferred type in the numeric category. Therefore,
 136    PostgreSQL will use that entry when faced with an unknown input:
 137 SELECT @ '-4.5' AS "abs";
 138  abs
 139 -----
 140  4.5
 141 (1 row)
 142
 143    Here the system has implicitly resolved the unknown-type literal as
 144    type float8 before applying the chosen operator. We can verify that
 145    float8 and not some other type was used:
 146 SELECT @ '-4.5e500' AS "abs";
 147
 148 ERROR:  "-4.5e500" is out of range for type double precision
 149
 150    On the other hand, the prefix operator ~ (bitwise negation) is defined
 151    only for integer data types, not for float8. So, if we try a similar
 152    case with ~, we get:
 153 SELECT ~ '20' AS "negation";
 154
 155 ERROR:  operator is not unique: ~ "unknown"
 156 HINT:  Could not choose a best candidate operator. You might need to add
 157 explicit type casts.
 158
 159    This happens because the system cannot decide which of the several
 160    possible ~ operators should be preferred. We can help it out with an
 161    explicit cast:
 162 SELECT ~ CAST('20' AS int8) AS "negation";
 163
 164  negation
 165 ----------
 166       -21
 167 (1 row)
 168
 169    Example 10.4. Array Inclusion Operator Type Resolution
 170
 171    Here is another example of resolving an operator with one known and one
 172    unknown input:
 173 SELECT array[1,2] <@ '{1,2,3}' as "is subset";
 174
 175  is subset
 176 -----------
 177  t
 178 (1 row)
 179
 180    The PostgreSQL operator catalog has several entries for the infix
 181    operator <@, but the only two that could possibly accept an integer
 182    array on the left-hand side are array inclusion (anyarray <@ anyarray)
 183    and range inclusion (anyelement <@ anyrange). Since none of these
 184    polymorphic pseudo-types (see Section 8.21) are considered preferred,
 185    the parser cannot resolve the ambiguity on that basis. However, Step
 186    3.f tells it to assume that the unknown-type literal is of the same
 187    type as the other input, that is, integer array. Now only one of the
 188    two operators can match, so array inclusion is selected. (Had range
 189    inclusion been selected, we would have gotten an error, because the
 190    string does not have the right format to be a range literal.)
 191
 192    Example 10.5. Custom Operator on a Domain Type
 193
 194    Users sometimes try to declare operators applying just to a domain
 195    type. This is possible but is not nearly as useful as it might seem,
 196    because the operator resolution rules are designed to select operators
 197    applying to the domain's base type. As an example consider
 198 CREATE DOMAIN mytext AS text CHECK(...);
 199 CREATE FUNCTION mytext_eq_text (mytext, text) RETURNS boolean AS ...;
 200 CREATE OPERATOR = (procedure=mytext_eq_text, leftarg=mytext, rightarg=text);
 201 CREATE TABLE mytable (val mytext);
 202
 203 SELECT * FROM mytable WHERE val = 'foo';
 204
 205    This query will not use the custom operator. The parser will first see
 206    if there is a mytext = mytext operator (Step 2.a), which there is not;
 207    then it will consider the domain's base type text, and see if there is
 208    a text = text operator (Step 2.b), which there is; so it resolves the
 209    unknown-type literal as text and uses the text = text operator. The
 210    only way to get the custom operator to be used is to explicitly cast
 211    the literal:
 212 SELECT * FROM mytable WHERE val = text 'foo';
 213
 214    so that the mytext = text operator is found immediately according to
 215    the exact-match rule. If the best-match rules are reached, they
 216    actively discriminate against operators on domain types. If they did
 217    not, such an operator would create too many ambiguous-operator
 218    failures, because the casting rules always consider a domain as
 219    castable to or from its base type, and so the domain operator would be
 220    considered usable in all the same cases as a similarly-named operator
 221    on the base type.
 222
 223    ^[9] The hazard does not arise with a non-schema-qualified name,
 224    because a search path containing schemas that permit untrusted users to
 225    create objects is not a secure schema usage pattern.