begriffs open source - ai-pg/blob - full-docs/txt/sql-syntax-calling-funcs.txt

   1
   2 4.3. Calling Functions #
   3
   4    4.3.1. Using Positional Notation
   5    4.3.2. Using Named Notation
   6    4.3.3. Using Mixed Notation
   7
   8    PostgreSQL allows functions that have named parameters to be called
   9    using either positional or named notation. Named notation is especially
  10    useful for functions that have a large number of parameters, since it
  11    makes the associations between parameters and actual arguments more
  12    explicit and reliable. In positional notation, a function call is
  13    written with its argument values in the same order as they are defined
  14    in the function declaration. In named notation, the arguments are
  15    matched to the function parameters by name and can be written in any
  16    order. For each notation, also consider the effect of function argument
  17    types, documented in Section 10.3.
  18
  19    In either notation, parameters that have default values given in the
  20    function declaration need not be written in the call at all. But this
  21    is particularly useful in named notation, since any combination of
  22    parameters can be omitted; while in positional notation parameters can
  23    only be omitted from right to left.
  24
  25    PostgreSQL also supports mixed notation, which combines positional and
  26    named notation. In this case, positional parameters are written first
  27    and named parameters appear after them.
  28
  29    The following examples will illustrate the usage of all three
  30    notations, using the following function definition:
  31 CREATE FUNCTION concat_lower_or_upper(a text, b text, uppercase boolean DEFAULT
  32 false)
  33 RETURNS text
  34 AS
  35 $$
  36  SELECT CASE
  37         WHEN $3 THEN UPPER($1 || ' ' || $2)
  38         ELSE LOWER($1 || ' ' || $2)
  39         END;
  40 $$
  41 LANGUAGE SQL IMMUTABLE STRICT;
  42
  43    Function concat_lower_or_upper has two mandatory parameters, a and b.
  44    Additionally there is one optional parameter uppercase which defaults
  45    to false. The a and b inputs will be concatenated, and forced to either
  46    upper or lower case depending on the uppercase parameter. The remaining
  47    details of this function definition are not important here (see
  48    Chapter 36 for more information).
  49
  50 4.3.1. Using Positional Notation #
  51
  52    Positional notation is the traditional mechanism for passing arguments
  53    to functions in PostgreSQL. An example is:
  54 SELECT concat_lower_or_upper('Hello', 'World', true);
  55  concat_lower_or_upper
  56 -----------------------
  57  HELLO WORLD
  58 (1 row)
  59
  60    All arguments are specified in order. The result is upper case since
  61    uppercase is specified as true. Another example is:
  62 SELECT concat_lower_or_upper('Hello', 'World');
  63  concat_lower_or_upper
  64 -----------------------
  65  hello world
  66 (1 row)
  67
  68    Here, the uppercase parameter is omitted, so it receives its default
  69    value of false, resulting in lower case output. In positional notation,
  70    arguments can be omitted from right to left so long as they have
  71    defaults.
  72
  73 4.3.2. Using Named Notation #
  74
  75    In named notation, each argument's name is specified using => to
  76    separate it from the argument expression. For example:
  77 SELECT concat_lower_or_upper(a => 'Hello', b => 'World');
  78  concat_lower_or_upper
  79 -----------------------
  80  hello world
  81 (1 row)
  82
  83    Again, the argument uppercase was omitted so it is set to false
  84    implicitly. One advantage of using named notation is that the arguments
  85    may be specified in any order, for example:
  86 SELECT concat_lower_or_upper(a => 'Hello', b => 'World', uppercase => true);
  87  concat_lower_or_upper
  88 -----------------------
  89  HELLO WORLD
  90 (1 row)
  91
  92 SELECT concat_lower_or_upper(a => 'Hello', uppercase => true, b => 'World');
  93  concat_lower_or_upper
  94 -----------------------
  95  HELLO WORLD
  96 (1 row)
  97
  98    An older syntax based on ":=" is supported for backward compatibility:
  99 SELECT concat_lower_or_upper(a := 'Hello', uppercase := true, b := 'World');
 100  concat_lower_or_upper
 101 -----------------------
 102  HELLO WORLD
 103 (1 row)
 104
 105 4.3.3. Using Mixed Notation #
 106
 107    The mixed notation combines positional and named notation. However, as
 108    already mentioned, named arguments cannot precede positional arguments.
 109    For example:
 110 SELECT concat_lower_or_upper('Hello', 'World', uppercase => true);
 111  concat_lower_or_upper
 112 -----------------------
 113  HELLO WORLD
 114 (1 row)
 115
 116    In the above query, the arguments a and b are specified positionally,
 117    while uppercase is specified by name. In this example, that adds little
 118    except documentation. With a more complex function having numerous
 119    parameters that have default values, named or mixed notation can save a
 120    great deal of writing and reduce chances for error.
 121
 122 Note
 123
 124    Named and mixed call notations currently cannot be used when calling an
 125    aggregate function (but they do work when an aggregate function is used
 126    as a window function).