CREATE [ OR REPLACE ] FUNCTION
name( [ [argmode] [argname]argtype[ { DEFAULT | = }default_expr] [,...] ] )
[ RETURNSrettype
| RETURNS TABLE (column_namecolumn_type[,...] ) ]
{ LANGUAGElang_name
| WINDOW
| IMMUTABLE | STABLE | VOLATILE
| CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
| [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER
| COSTexecution_cost
| ROWSresult_rows
| SETconfiguration_parameter{ TOvalue| =value| FROM CURRENT }
| AS 'definition'
| AS 'obj_file','link_symbol'
} ...
[ WITH (attribute[,...] ) ]
描述CREATE FUNCTION定义一个新的函数。CREATE OR REPLACE FUNCTION将要么创建一个新函数,要么替换现有的定义。
如果包含了一个模式名,那么函数就在指定的模式中创建。否则它会在当前模式中创建。新函数的名字不能和同一个模式中的任何带有同样参数类型的函数同名。不过,参数类型不同的函数可以同名(这叫做重载)。
要更新一个现有函数的定义,使用CREATE OR REPLACEFUNCTION。我们不能用这个方法修改一个函数的名字或者参数类型(如果你这么干,那么你就会创建一个新的,不同的函数)。同样,CREATEOR REPLACE FUNCTION也不会允许你修改一个现有函数的返回类型。要做这些事情,你必须删除并重新创建函数。(如果使用OUT参数,那就意味着除了删除函数,你不能修改任何OUT参数的类型或者名字。)
如果你删除然后重建一个函数,新函数和旧的将是不同的实体;你就需要删除现有引用了老函数的规则,视图,触发器等等。 使用CREATE OR REPLACE FUNCTION可以在不破坏引用该函数的对象的前提下修改函数定义。
参数
- name
-
要创建的函数名字(可以用模式修饰)。
- argmode
-
参数的模式:是IN、OUT、或者INOUT。 如果省略,缺省是IN。
- argname
-
一个参数的名字。有些语言(目前只有PL/pgsql)允许你在函数体里使用参数名字。对于其它语言,这个参数名字只是额外的文档。但是输出参数的名字是非常重要的,因为它定义了结果行类型的字段名。(如果你省略了一个输出参数的参数名,那么系统会选取缺省的字段名。)
- argtype
-
该函数的数据类型(可以有模式修饰)。如果有的话,参数类型可以是基本类型,也可以是复合类型,域类型,或者可以引用一个现有字段相同的类型。
根据实现语言的不同,我们还可以在这上面声明 "伪类型", 比如cstring。伪类型表示实际的参数类型要么是没有完整地声明,要么是在普通的 sql数据类型之外。
一个字段的类型是用tablename.columnname%TYPE表示的;使用这个东西可以帮助函数独立于表定义的修改。
- rettype
-
返回数据类型。输出类型可以声明为一个基本类型,复合类型,域类型,或者引用一个表的现有字段。根据实现语言的不同,我们还可以在这上面声明"伪类型", 比如cstring。
如果存在OUT或者INOUT参数,则可以省略RETURNS子句。如果出现了,那么它必须和输出参数隐含的结果类型兼容:如果有多个输出参数,必须是RECORD, 如果只有一个输出参数,则与其相同。
SETOF修饰词表示该函数将返回一套条目, 而不是一条条目。
一个字段的类型是通过写tablename.columnname%TYPE来引用的。
- langname
-
用以实现函数的语言的名字。 可以是sql,C,internal,或者是用户定义的过程语言名字。为了保持向下兼容,该名字可以用单引号包围。
-
IMMUTABLE
STABLE
VOLATILE -
这些属性告诉系统把对该函数的多次调用替换成一次是否安全。 主要用于运行时优化。至少应该声明一个选择。如果任何一个都没有出现,那么VOLATILE是缺省假设。
IMMUTABLE表示该函数在给出同样的参数值时总是返回相同的结果;也就是说,它不做数据库查找或者是使用那些并没有直接出现在其参数列表里面的信息。如果给出这个选项,那么任何带着全部是常量参数对该函数的调用都将立即替换为该函数的值。
STABLE表示在一次表扫描里,对相同参数值,该函数将稳定返回相同的值,但是它的结果可能在不同 sql语句之间变化。这个选项对那些结果倚赖数据库查找,参数变量(比如当前时区),等等的函数是很合适的。 还要注意current_timestamp族函数是 stable(稳定)的,因为它们的值在一次事务中不会变化。
VOLATILE表示该函数值甚至可以在一次表扫描内改变,因此不会做任何优化。很少数据库函数在这个概念上是易变的; 一些例子是random(),currval(),timeofday()。请注意任何有副作用的函数都必需列为易变类,即使其结果相当有规律也应该这样,这样才能避免它被优化;一个例子就是setval()。
-
CALLED ON NULL INPUT
RETURNS NULL ON NULL INPUT
STRICT -
CALLED ON NULL INPUT(缺省)表明该函数在自己的某些参数是空值的时候还是可以按照正常的方式调用。剩下的事情是函数的作者必须负责检查空值以及相应地做出反应。
RETURNS NULL ON NULL INPUT或STRICT表明如果它的任何参数是 NULL,此函数总是返回 NULL。如果声明了这个参数,则如果存在NULL 参数时不会执行该函数; 而只是自动假设一个 NULL 结果。
-
[EXTERNAL] SECURITY INVOKER
[EXTERNAL] SECURITY DEFINER -
SECURITY INVOKER表明该函数将带着调用它的用户的权限执行。这是缺省。SECURITY DEFINER声明该函数将以创建它的用户的权限执行。
- definition
-
一个定义函数的字串常量;含义取决于语言。它可以是一个内部函数名字, 一个指向某个目标文件的路径,一个 SQL查询,或者一个用过程语言写的文本。
- obj_file,link_symbol
-
这个形式的AS子句用于在函数的 C 源文件里的函数名字和 sql函数的名字不同的时候可动态装载 C 语言函数。 字串obj_file是包含可动态装载的对象的文件名,而link_symbol是函数的链接符号,也就是该函数在 C源文件里的名字。如果省略了链接符号,那么就假设它和被定义的 sql 函数同名。
- attribute
-
- isStrict
-
等效于STRICT或者RETURNS NULL ON NULL INPUT
- isCachable
-
isCachable是IMMUTABLE的过时的等效物;不过出于向下兼容,我们仍然接受它。
属性名是大小写无关的。
这里是一些简单的例子,用于帮助你开始掌握这个命令。
CREATE FUNCTION add(integer,integer) RETURNS integer
AS 'select $1 + $2;'
LANGUAGE sql
IMMUTABLE
RETURNS NULL ON NULL INPUT;
用 PL/pgsql 自增一个整数,利用参数名:
CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$
BEGIN
RETURN i + 1;
END;
$$ LANGUAGE plpgsql;
返回一个包含多个输出参数的记录:
CREATE FUNCTION dup(in int,out f1 int,out f2 text)
AS
LANGUAGE sql;
SELECT * FROM dup(42);
你可以通过命名明确的复合类型的方法冗长地干同样的事情:
CREATE TYPE dup_result AS (f1 int,f2 text);
CREATE FUNCTION dup(int) RETURNS dup_result