<!--
-$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.92 2004/12/30 21:45:37 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.93 2005/01/07 22:40:46 tgl Exp $
-->
<sect1 id="xfunc">
<type>void</>, the last statement must be a <command>SELECT</>.
</para>
+ <para>
+ Any collection of commands in the <acronym>SQL</acronym>
+ language can be packaged together and defined as a function.
+ Besides <command>SELECT</command> queries, the commands can include data
+ modification queries (<command>INSERT</command>,
+ <command>UPDATE</command>, and <command>DELETE</command>), as well as
+ other SQL commands. (The only exception is that you can't put
+ <command>BEGIN</>, <command>COMMIT</>, <command>ROLLBACK</>, or
+ <command>SAVEPOINT</> commands into a <acronym>SQL</acronym> function.)
+ However, the final command
+ must be a <command>SELECT</command> that returns whatever is
+ specified as the function's return type. Alternatively, if you
+ want to define a SQL function that performs actions but has no
+ useful value to return, you can define it as returning <type>void</>.
+ In that case, the function body must not end with a <command>SELECT</command>.
+ For example, this function removes rows with negative salaries from
+ the <literal>emp</> table:
+
+<screen>
+CREATE FUNCTION clean_emp() RETURNS void AS '
+ DELETE FROM emp
+ WHERE salary < 0;
+' LANGUAGE SQL;
+
+SELECT clean_emp();
+
+ clean_emp
+-----------
+
+(1 row)
+</screen>
+ </para>
+
<para>
The syntax of the <command>CREATE FUNCTION</command> command requires
the function body to be written as a string constant. It is usually
which adjusts the balance and returns the new balance.
</para>
-
- <para>
- Any collection of commands in the <acronym>SQL</acronym>
- language can be packaged together and defined as a function.
- Besides <command>SELECT</command> queries,
- the commands can include data modification (i.e.,
- <command>INSERT</command>, <command>UPDATE</command>, and
- <command>DELETE</command>). However, the final command
- must be a <command>SELECT</command> that returns whatever is
- specified as the function's return type. Alternatively, if you
- want to define a SQL function that performs actions but has no
- useful value to return, you can define it as returning <type>void</>.
- In that case, the function body must not end with a <command>SELECT</command>.
- For example:
-
-<screen>
-CREATE FUNCTION clean_emp() RETURNS void AS $$
- DELETE FROM emp
- WHERE salary <= 0;
-$$ LANGUAGE SQL;
-
-SELECT clean_emp();
-
- clean_emp
------------
-
-(1 row)
-</screen>
- </para>
</sect2>
<sect2>
name | dream
------+-------
- Sam | 2400
+ Bill | 8400
</screen>
</para>
on-the-fly. This can be done with the <literal>ROW</> construct.
For example, we could adjust the data being passed to the function:
<screen>
-SELECT name, double_salary(row(name, salary*1.1, age, cubicle)) AS dream
+SELECT name, double_salary(ROW(name, salary*1.1, age, cubicle)) AS dream
FROM emp;
</screen>
</para>
<programlisting>
CREATE FUNCTION new_emp() RETURNS emp AS $$
SELECT text 'None' AS name,
- 1000 AS salary,
+ 1000.0 AS salary,
25 AS age,
point '(2,2)' AS cubicle;
$$ LANGUAGE SQL;
</para>
<para>
- When you call a function that returns a row (composite type) in a
- SQL expression, you might want only one field (attribute) from its
- result. You can do that with syntax like this:
+ A different way to define the same function is:
+
+<programlisting>
+CREATE FUNCTION new_emp() RETURNS emp AS $$
+ SELECT ROW('None', 1000.0, 25, '(2,2)')::emp;
+$$ LANGUAGE SQL;
+</programlisting>
+
+ Here we wrote a <command>SELECT</> that returns just a single
+ column of the correct composite type. This isn't really better
+ in this situation, but it is a handy alternative in some cases
+ — for example, if we need to compute the result by calling
+ another function that returns the desired composite value.
+ </para>
+
+ <para>
+ We could call this function directly in either of two ways:
+
+<screen>
+SELECT new_emp();
+
+ new_emp
+--------------------------
+ (None,1000.0,25,"(2,2)")
+
+SELECT * FROM new_emp();
+
+ name | salary | age | cubicle
+------+--------+-----+---------
+ None | 1000.0 | 25 | (2,2)
+</screen>
+
+ The second way is described more fully in <xref
+ linkend="xfunc-sql-table-functions">.
+ </para>
+
+ <para>
+ When you use a function that returns a composite type,
+ you might want only one field (attribute) from its result.
+ You can do that with syntax like this:
<screen>
SELECT (new_emp()).name;
<screen>
-- This is the same as:
--- SELECT emp.name AS youngster FROM emp WHERE emp.age < 30
+-- SELECT emp.name AS youngster FROM emp WHERE emp.age < 30;
-SELECT name(emp) AS youngster
- FROM emp
- WHERE age(emp) < 30;
+SELECT name(emp) AS youngster FROM emp WHERE age(emp) < 30;
youngster
-----------
Sam
+ Andy
</screen>
</para>
</para>
</sect2>
- <sect2>
+ <sect2 id="xfunc-sql-table-functions">
<title><acronym>SQL</acronym> Functions as Table Sources</title>
<para>