begriffs open source - ai-pg/blob - full-docs/src/sgml/html/sql-syntax-calling-funcs.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>4.3. Calling Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-expressions.html" title="4.2. Value Expressions" /><link rel="next" href="ddl.html" title="Chapter 5. Data Definition" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">4.3. Calling Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-expressions.html" title="4.2. Value Expressions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Up</a></td><th width="60%" align="center">Chapter 4. SQL Syntax</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="ddl.html" title="Chapter 5. Data Definition">Next</a></td></tr></table><hr /></div><div class="sect1" id="SQL-SYNTAX-CALLING-FUNCS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">4.3. Calling Functions <a href="#SQL-SYNTAX-CALLING-FUNCS" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-POSITIONAL">4.3.1. Using Positional Notation</a></span></dt><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-NAMED">4.3.2. Using Named Notation</a></span></dt><dt><span class="sect2"><a href="sql-syntax-calling-funcs.html#SQL-SYNTAX-CALLING-FUNCS-MIXED">4.3.3. Using Mixed Notation</a></span></dt></dl></div><a id="id-1.5.3.7.2" class="indexterm"></a><p>
   3     <span class="productname">PostgreSQL</span> allows functions that have named
   4     parameters to be called using either <em class="firstterm">positional</em> or
   5     <em class="firstterm">named</em> notation.  Named notation is especially
   6     useful for functions that have a large number of parameters, since it
   7     makes the associations between parameters and actual arguments more
   8     explicit and reliable.
   9     In positional notation, a function call is written with
  10     its argument values in the same order as they are defined in the function
  11     declaration.  In named notation, the arguments are matched to the
  12     function parameters by name and can be written in any order.
  13     For each notation, also consider the effect of function argument types,
  14     documented in <a class="xref" href="typeconv-func.html" title="10.3. Functions">Section 10.3</a>.
  15    </p><p>
  16     In either notation, parameters that have default values given in the
  17     function declaration need not be written in the call at all.  But this
  18     is particularly useful in named notation, since any combination of
  19     parameters can be omitted; while in positional notation parameters can
  20     only be omitted from right to left.
  21    </p><p>
  22     <span class="productname">PostgreSQL</span> also supports
  23     <em class="firstterm">mixed</em> notation, which combines positional and
  24     named notation.  In this case, positional parameters are written first
  25     and named parameters appear after them.
  26    </p><p>
  27     The following examples will illustrate the usage of all three
  28     notations, using the following function definition:
  29 </p><pre class="programlisting">
  30 CREATE FUNCTION concat_lower_or_upper(a text, b text, uppercase boolean DEFAULT false)
  31 RETURNS text
  32 AS
  33 $$
  34  SELECT CASE
  35         WHEN $3 THEN UPPER($1 || ' ' || $2)
  36         ELSE LOWER($1 || ' ' || $2)
  37         END;
  38 $$
  39 LANGUAGE SQL IMMUTABLE STRICT;
  40 </pre><p>
  41     Function <code class="function">concat_lower_or_upper</code> has two mandatory
  42     parameters, <code class="literal">a</code> and <code class="literal">b</code>.  Additionally
  43     there is one optional parameter <code class="literal">uppercase</code> which defaults
  44     to <code class="literal">false</code>.  The <code class="literal">a</code> and
  45     <code class="literal">b</code> inputs will be concatenated, and forced to either
  46     upper or lower case depending on the <code class="literal">uppercase</code>
  47     parameter.  The remaining details of this function
  48     definition are not important here (see <a class="xref" href="extend.html" title="Chapter 36. Extending SQL">Chapter 36</a> for
  49     more information).
  50    </p><div class="sect2" id="SQL-SYNTAX-CALLING-FUNCS-POSITIONAL"><div class="titlepage"><div><div><h3 class="title">4.3.1. Using Positional Notation <a href="#SQL-SYNTAX-CALLING-FUNCS-POSITIONAL" class="id_link">#</a></h3></div></div></div><a id="id-1.5.3.7.7.2" class="indexterm"></a><p>
  51      Positional notation is the traditional mechanism for passing arguments
  52      to functions in <span class="productname">PostgreSQL</span>.  An example is:
  53 </p><pre class="screen">
  54 SELECT concat_lower_or_upper('Hello', 'World', true);
  55  concat_lower_or_upper
  56 -----------------------
  57  HELLO WORLD
  58 (1 row)
  59 </pre><p>
  60      All arguments are specified in order.  The result is upper case since
  61      <code class="literal">uppercase</code> is specified as <code class="literal">true</code>.
  62      Another example is:
  63 </p><pre class="screen">
  64 SELECT concat_lower_or_upper('Hello', 'World');
  65  concat_lower_or_upper
  66 -----------------------
  67  hello world
  68 (1 row)
  69 </pre><p>
  70      Here, the <code class="literal">uppercase</code> parameter is omitted, so it
  71      receives its default value of <code class="literal">false</code>, resulting in
  72      lower case output.  In positional notation, arguments can be omitted
  73      from right to left so long as they have defaults.
  74     </p></div><div class="sect2" id="SQL-SYNTAX-CALLING-FUNCS-NAMED"><div class="titlepage"><div><div><h3 class="title">4.3.2. Using Named Notation <a href="#SQL-SYNTAX-CALLING-FUNCS-NAMED" class="id_link">#</a></h3></div></div></div><a id="id-1.5.3.7.8.2" class="indexterm"></a><p>
  75      In named notation, each argument's name is specified using
  76      <code class="literal">=&gt;</code> to separate it from the argument expression.
  77      For example:
  78 </p><pre class="screen">
  79 SELECT concat_lower_or_upper(a =&gt; 'Hello', b =&gt; 'World');
  80  concat_lower_or_upper
  81 -----------------------
  82  hello world
  83 (1 row)
  84 </pre><p>
  85      Again, the argument <code class="literal">uppercase</code> was omitted
  86      so it is set to <code class="literal">false</code> implicitly.  One advantage of
  87      using named notation is that the arguments may be specified in any
  88      order, for example:
  89 </p><pre class="screen">
  90 SELECT concat_lower_or_upper(a =&gt; 'Hello', b =&gt; 'World', uppercase =&gt; true);
  91  concat_lower_or_upper
  92 -----------------------
  93  HELLO WORLD
  94 (1 row)
  95
  96 SELECT concat_lower_or_upper(a =&gt; 'Hello', uppercase =&gt; true, b =&gt; 'World');
  97  concat_lower_or_upper
  98 -----------------------
  99  HELLO WORLD
 100 (1 row)
 101 </pre><p>
 102     </p><p>
 103       An older syntax based on ":=" is supported for backward compatibility:
 104 </p><pre class="screen">
 105 SELECT concat_lower_or_upper(a := 'Hello', uppercase := true, b := 'World');
 106  concat_lower_or_upper
 107 -----------------------
 108  HELLO WORLD
 109 (1 row)
 110 </pre><p>
 111     </p></div><div class="sect2" id="SQL-SYNTAX-CALLING-FUNCS-MIXED"><div class="titlepage"><div><div><h3 class="title">4.3.3. Using Mixed Notation <a href="#SQL-SYNTAX-CALLING-FUNCS-MIXED" class="id_link">#</a></h3></div></div></div><a id="id-1.5.3.7.9.2" class="indexterm"></a><p>
 112     The mixed notation combines positional and named notation. However, as
 113     already mentioned, named arguments cannot precede positional arguments.
 114     For example:
 115 </p><pre class="screen">
 116 SELECT concat_lower_or_upper('Hello', 'World', uppercase =&gt; true);
 117  concat_lower_or_upper
 118 -----------------------
 119  HELLO WORLD
 120 (1 row)
 121 </pre><p>
 122     In the above query, the arguments <code class="literal">a</code> and
 123     <code class="literal">b</code> are specified positionally, while
 124     <code class="literal">uppercase</code> is specified by name.  In this example,
 125     that adds little except documentation.  With a more complex function
 126     having numerous parameters that have default values, named or mixed
 127     notation can save a great deal of writing and reduce chances for error.
 128    </p><div class="note"><h3 class="title">Note</h3><p>
 129      Named and mixed call notations currently cannot be used when calling an
 130      aggregate function (but they do work when an aggregate function is used
 131      as a window function).
 132     </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-expressions.html" title="4.2. Value Expressions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-syntax.html" title="Chapter 4. SQL Syntax">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ddl.html" title="Chapter 5. Data Definition">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.2. Value Expressions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Data Definition</td></tr></table></div></body></html>