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

   1
   2 10.3. Functions #
   3
   4    The specific function that is referenced by a function call is
   5    determined using the following procedure.
   6
   7    Function Type Resolution
   8     1. Select the functions to be considered from the pg_proc system
   9        catalog. If a non-schema-qualified function name was used, the
  10        functions considered are those with the matching name and argument
  11        count that are visible in the current search path (see
  12        Section 5.10.3). If a qualified function name was given, only
  13        functions in the specified schema are considered.
  14          a. If the search path finds multiple functions of identical
  15             argument types, only the one appearing earliest in the path is
  16             considered. Functions of different argument types are
  17             considered on an equal footing regardless of search path
  18             position.
  19          b. If a function is declared with a VARIADIC array parameter, and
  20             the call does not use the VARIADIC keyword, then the function
  21             is treated as if the array parameter were replaced by one or
  22             more occurrences of its element type, as needed to match the
  23             call. After such expansion the function might have effective
  24             argument types identical to some non-variadic function. In
  25             that case the function appearing earlier in the search path is
  26             used, or if the two functions are in the same schema, the
  27             non-variadic one is preferred.
  28             This creates a security hazard when calling, via qualified
  29             name ^[10], a variadic function found in a schema that permits
  30             untrusted users to create objects. A malicious user can take
  31             control and execute arbitrary SQL functions as though you
  32             executed them. Substitute a call bearing the VARIADIC keyword,
  33             which bypasses this hazard. Calls populating VARIADIC "any"
  34             parameters often have no equivalent formulation containing the
  35             VARIADIC keyword. To issue those calls safely, the function's
  36             schema must permit only trusted users to create objects.
  37          c. Functions that have default values for parameters are
  38             considered to match any call that omits zero or more of the
  39             defaultable parameter positions. If more than one such
  40             function matches a call, the one appearing earliest in the
  41             search path is used. If there are two or more such functions
  42             in the same schema with identical parameter types in the
  43             non-defaulted positions (which is possible if they have
  44             different sets of defaultable parameters), the system will not
  45             be able to determine which to prefer, and so an “ambiguous
  46             function call” error will result if no better match to the
  47             call can be found.
  48             This creates an availability hazard when calling, via
  49             qualified name^[10], any function found in a schema that
  50             permits untrusted users to create objects. A malicious user
  51             can create a function with the name of an existing function,
  52             replicating that function's parameters and appending novel
  53             parameters having default values. This precludes new calls to
  54             the original function. To forestall this hazard, place
  55             functions in schemas that permit only trusted users to create
  56             objects.
  57     2. Check for a function accepting exactly the input argument types. If
  58        one exists (there can be only one exact match in the set of
  59        functions considered), use it. Lack of an exact match creates a
  60        security hazard when calling, via qualified name^[10], a function
  61        found in a schema that permits untrusted users to create objects.
  62        In such situations, cast arguments to force an exact match. (Cases
  63        involving unknown will never find a match at this step.)
  64     3. If no exact match is found, see if the function call appears to be
  65        a special type conversion request. This happens if the function
  66        call has just one argument and the function name is the same as the
  67        (internal) name of some data type. Furthermore, the function
  68        argument must be either an unknown-type literal, or a type that is
  69        binary-coercible to the named data type, or a type that could be
  70        converted to the named data type by applying that type's I/O
  71        functions (that is, the conversion is either to or from one of the
  72        standard string types). When these conditions are met, the function
  73        call is treated as a form of CAST specification. ^[11]
  74     4. Look for the best match.
  75          a. Discard candidate functions for which the input types do not
  76             match and cannot be converted (using an implicit conversion)
  77             to match. unknown literals are assumed to be convertible to
  78             anything for this purpose. If only one candidate remains, use
  79             it; else continue to the next step.
  80          b. If any input argument is of a domain type, treat it as being
  81             of the domain's base type for all subsequent steps. This
  82             ensures that domains act like their base types for purposes of
  83             ambiguous-function resolution.
  84          c. Run through all candidates and keep those with the most exact
  85             matches on input types. Keep all candidates if none have exact
  86             matches. If only one candidate remains, use it; else continue
  87             to the next step.
  88          d. Run through all candidates and keep those that accept
  89             preferred types (of the input data type's type category) at
  90             the most positions where type conversion will be required.
  91             Keep all candidates if none accept preferred types. If only
  92             one candidate remains, use it; else continue to the next step.
  93          e. If any input arguments are unknown, check the type categories
  94             accepted at those argument positions by the remaining
  95             candidates. At each position, select the string category if
  96             any candidate accepts that category. (This bias towards string
  97             is appropriate since an unknown-type literal looks like a
  98             string.) Otherwise, if all the remaining candidates accept the
  99             same type category, select that category; otherwise fail
 100             because the correct choice cannot be deduced without more
 101             clues. Now discard candidates that do not accept the selected
 102             type category. Furthermore, if any candidate accepts a
 103             preferred type in that category, discard candidates that
 104             accept non-preferred types for that argument. Keep all
 105             candidates if none survive these tests. If only one candidate
 106             remains, use it; else continue to the next step.
 107          f. If there are both unknown and known-type arguments, and all
 108             the known-type arguments have the same type, assume that the
 109             unknown arguments are also of that type, and check which
 110             candidates can accept that type at the unknown-argument
 111             positions. If exactly one candidate passes this test, use it.
 112             Otherwise, fail.
 113
 114    Note that the “best match” rules are identical for operator and
 115    function type resolution. Some examples follow.
 116
 117    Example 10.6. Rounding Function Argument Type Resolution
 118
 119    There is only one round function that takes two arguments; it takes a
 120    first argument of type numeric and a second argument of type integer.
 121    So the following query automatically converts the first argument of
 122    type integer to numeric:
 123 SELECT round(4, 4);
 124
 125  round
 126 --------
 127  4.0000
 128 (1 row)
 129
 130    That query is actually transformed by the parser to:
 131 SELECT round(CAST (4 AS numeric), 4);
 132
 133    Since numeric constants with decimal points are initially assigned the
 134    type numeric, the following query will require no type conversion and
 135    therefore might be slightly more efficient:
 136 SELECT round(4.0, 4);
 137
 138    Example 10.7. Variadic Function Resolution
 139
 140 CREATE FUNCTION public.variadic_example(VARIADIC numeric[]) RETURNS int
 141   LANGUAGE sql AS 'SELECT 1';
 142 CREATE FUNCTION
 143
 144    This function accepts, but does not require, the VARIADIC keyword. It
 145    tolerates both integer and numeric arguments:
 146 SELECT public.variadic_example(0),
 147        public.variadic_example(0.0),
 148        public.variadic_example(VARIADIC array[0.0]);
 149  variadic_example | variadic_example | variadic_example
 150 ------------------+------------------+------------------
 151                 1 |                1 |                1
 152 (1 row)
 153
 154    However, the first and second calls will prefer more-specific
 155    functions, if available:
 156 CREATE FUNCTION public.variadic_example(numeric) RETURNS int
 157   LANGUAGE sql AS 'SELECT 2';
 158 CREATE FUNCTION
 159
 160 CREATE FUNCTION public.variadic_example(int) RETURNS int
 161   LANGUAGE sql AS 'SELECT 3';
 162 CREATE FUNCTION
 163
 164 SELECT public.variadic_example(0),
 165        public.variadic_example(0.0),
 166        public.variadic_example(VARIADIC array[0.0]);
 167  variadic_example | variadic_example | variadic_example
 168 ------------------+------------------+------------------
 169                 3 |                2 |                1
 170 (1 row)
 171
 172    Given the default configuration and only the first function existing,
 173    the first and second calls are insecure. Any user could intercept them
 174    by creating the second or third function. By matching the argument type
 175    exactly and using the VARIADIC keyword, the third call is secure.
 176
 177    Example 10.8. Substring Function Type Resolution
 178
 179    There are several substr functions, one of which takes types text and
 180    integer. If called with a string constant of unspecified type, the
 181    system chooses the candidate function that accepts an argument of the
 182    preferred category string (namely of type text).
 183 SELECT substr('1234', 3);
 184
 185  substr
 186 --------
 187      34
 188 (1 row)
 189
 190    If the string is declared to be of type varchar, as might be the case
 191    if it comes from a table, then the parser will try to convert it to
 192    become text:
 193 SELECT substr(varchar '1234', 3);
 194
 195  substr
 196 --------
 197      34
 198 (1 row)
 199
 200    This is transformed by the parser to effectively become:
 201 SELECT substr(CAST (varchar '1234' AS text), 3);
 202
 203 Note
 204
 205    The parser learns from the pg_cast catalog that text and varchar are
 206    binary-compatible, meaning that one can be passed to a function that
 207    accepts the other without doing any physical conversion. Therefore, no
 208    type conversion call is really inserted in this case.
 209
 210    And, if the function is called with an argument of type integer, the
 211    parser will try to convert that to text:
 212 SELECT substr(1234, 3);
 213 ERROR:  function substr(integer, integer) does not exist
 214 HINT:  No function matches the given name and argument types. You might need
 215 to add explicit type casts.
 216
 217    This does not work because integer does not have an implicit cast to
 218    text. An explicit cast will work, however:
 219 SELECT substr(CAST (1234 AS text), 3);
 220
 221  substr
 222 --------
 223      34
 224 (1 row)
 225
 226    ^[10] The hazard does not arise with a non-schema-qualified name,
 227    because a search path containing schemas that permit untrusted users to
 228    create objects is not a secure schema usage pattern.
 229
 230    ^[11] The reason for this step is to support function-style cast
 231    specifications in cases where there is not an actual cast function. If
 232    there is a cast function, it is conventionally named after its output
 233    type, and so there is no need to have a special case. See CREATE CAST
 234    for additional commentary.