CREATE FUNCTION 中文man页面

NAME

CREATE FUNCTION - 定义一个新函数

SYNOPSIS

CREATE [ OR REPLACE ] FUNCTION name ( [ argtype [, ...] ] )
    RETURNS rettype
  { LANGUAGE langname
    | IMMUTABLE | STABLE | VOLATILE
    | CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
    | [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER
    | AS 'definition'
    | AS 'obj_file', 'link_symbol'
  } ...
    [ WITH ( attribute [, ...] ) ]

DESCRIPTION 描述

CREATE FUNCTION 定义一个新的函数。 CREATE OR REPLACE FUNCTION 将要么创建一个新函数， 要么替换现有的定义。

 如果包含了一个模式名，那么函数就在指定的模式中创建。否则它会在当前模式中创建。 新函数的名字不能和同一个模式中的任何带有同样参数类型的函数同名。 不过，参数类型不同的函数可以同名（这叫做重载）。

 要更新一个现有函数的定义，使用 CREATE OR REPLACE FUNCTION。 我们不能用这个方法修改一个函数的名字或者参数类型（如果你这么干，那么你就会创建一个新的，不同的函数）。 同样，CREATE OR REPLACE FUNCTION 也不会允许你修改一个现有函数的返回类型。 要做这些事情，你必须删除并重新创建函数。

 如果你删除然后重建一个函数，新函数和旧的将是不同的实体；你会破坏现有规则，视图，触发器等等。 使用 CREATE OR REPLACE FUNCTION 可以在不破坏引用该函数的对象的前提下修改函数定义。

 创建这个函数的用户成为函数的所有者。  

PARAMETERS 参数

name

 要创建的函数名字。

argtype

 该函数的数据类型（可以有模式修饰）。如果有的话，参数类型可以是基本类型，也可以是复合类型，域类型，或者和一个现有字段相同的类型。

 一个字段的类型是用 tablename.columnname%TYPE  表示的；使用这个东西可以帮助函数独立于表定义的修改。

 根据实现语言的不同，我们还可以在这上面声明 "伪类型"， 比如 cstring。伪类型表示实际的参数类型要么是没有完整地声明，要么是在普通的 SQL 数据类型之外。

rettype

 返回数据类型。输出类型可以声明为一个基本类型，复合类型，域类型， 或者从现有字段拷贝。参阅上面 argtype 的描述获取如何引用一个现有类型的信息。

 根据实现语言的不同，我们还可以在这上面声明 "伪类型"， 比如 cstring。 SETOF 修饰词表示该函数将返回一套条目， 而不是一条条目。

langname

 用以实现函数的语言的名字。 可以是 SQL，C， internal，或者是用户定义的过程语言名字。 （又见 createlang。 ） 为了保持向下兼容，该名字可以用单引号包围。 

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 声明该函数将以创建它的用户的权限执行。

 关键字 EXTERNAL 的目的是和 SQL 兼容， 但是我们和 SQL 不同的是，这个特性不仅仅适用于外部的函数， 所以它是可选的。

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 的过时的等效物；不过出于向下兼容，我们仍然接受它。

 属性名是大小写无关的。  

NOTES 注意

 请参阅 ``User-Defined Functions'' 获取更多关于书写函数的信息。

 我们允许你将完整的 SQL 类型语法用于输入参数和返回值。 不过，有些类型声明的细节（比如，numeric 类型的精度域）是由下层函数实现负责的， 并且会被 CREATE FUNCTION 命令悄悄地吞掉。 （也就是说，不再被识别或强制）。

PostgreSQL 允许函数重载； 也就是说，同一个函数名可以用于几个不同的函数， 只要它们的参数可以区分它们。不过，所有函数的 C 名字必须不同， 也就是说你必须给予重载的 C 函数不同的 C 名字（比如，使用参数类型作为 C 名字的一部分）。

 如果重复调用 CREATE FUNCTION，并且都指向同一个目标文件， 那么该文件只装载一次。要卸载和恢复装载该文件（可能是在开发过程中），你可以使用 LOAD [load(7)] 命令。

 使用 DROP FUNCTION 删除一个用户定义函数。

 函数定义里面的任何单引号或者反斜杠都必须用写双份的方式逃逸。

 要能定义函数，用户必须对该语言有 USAGE  权限。  

EXAMPLES 例子

 这里是一个简单的例子，用于帮助你开始掌握这个命令。 更多信息和例子，参阅 ``User-Defined Functions''。

CREATE FUNCTION add(integer, integer) RETURNS integer
    AS 'select $1 + $2;'
    LANGUAGE SQL
    IMMUTABLE
    RETURNS NULL ON NULL INPUT;

COMPATIBILITY 兼容性

 在 SQL99 里的确定义了一个CREATE FUNCTION  PostgreSQL 的和它类似但是不兼容。 这个属性是不可移植的，可以使用的不同语言也是如此。  

SEE ALSO 参见

ALTER FUNCTION [alter_function(7)], DROP FUNCTION [drop_function(7)], GRANT [grant(7)], LOAD [load(7)], REVOKE [revoke(7)], createlang(1)  

#p#

NAME

CREATE FUNCTION - define a new function

SYNOPSIS

CREATE [ OR REPLACE ] FUNCTION name ( [ argtype [, ...] ] )
    RETURNS rettype
  { LANGUAGE langname
    | IMMUTABLE | STABLE | VOLATILE
    | CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
    | [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER
    | AS 'definition'
    | AS 'obj_file', 'link_symbol'
  } ...
    [ WITH ( attribute [, ...] ) ]

DESCRIPTION

CREATE FUNCTION defines a new function. CREATE OR REPLACE FUNCTION will either create a new function, or replace an existing definition.

If a schema name is included, then the function is created in the specified schema. Otherwise it is created in the current schema. The name of the new function must not match any existing function with the same argument types in the same schema. However, functions of different argument types may share a name (this is called overloading).

To update the definition of an existing function, use CREATE OR REPLACE FUNCTION. It is not possible to change the name or argument types of a function this way (if you tried, you'd just be creating a new, distinct function). Also, CREATE OR REPLACE FUNCTION will not let you change the return type of an existing function. To do that, you must drop and recreate the function.

If you drop and then recreate a function, the new function is not the same entity as the old; you will break existing rules, views, triggers, etc. that referred to the old function. Use CREATE OR REPLACE FUNCTION to change a function definition without breaking objects that refer to the function.

The user that creates the function becomes the owner of the function.  

PARAMETERS

name

The name of a function to create.

argtype

The data type(s) of the function's arguments (optionally schema-qualified), if any. The argument types may be base, complex, or domain types, or copy the type of an existing column.

The type of a column is referenced by writing tablename.columnname%TYPE; using this can sometimes help make a function independent from changes to the definition of a table.

Depending on the implementation language it may also be allowed to specify ``pseudotypes'' such as cstring. Pseudotypes indicate that the actual argument type is either incompletely specified, or outside the set of ordinary SQL data types.

rettype

The return data type (optionally schema-qualified). The return type may be specified as a base, complex, or domain type, or may copy the type of an existing column. See the description under argtype above on how to reference the type of an existing column.

Depending on the implementation language it may also be allowed to specify ``pseudotypes'' such as cstring. The SETOF modifier indicates that the function will return a set of items, rather than a single item.

langname

The name of the language that the function is implemented in. May be SQL, C, internal, or the name of a user-defined procedural language. (See also createlang [createlang(1)].) For backward compatibility, the name may be enclosed by single quotes.

IMMUTABLE

STABLE

VOLATILE

These attributes inform the system whether it is safe to replace multiple evaluations of the function with a single evaluation, for run-time optimization. At most one choice should be specified. If none of these appear, VOLATILE is the default assumption.

IMMUTABLE indicates that the function always returns the same result when given the same argument values; that is, it does not do database lookups or otherwise use information not directly present in its argument list. If this option is given, any call of the function with all-constant arguments can be immediately replaced with the function value.

STABLE indicates that within a single table scan the function will consistently return the same result for the same argument values, but that its result could change across SQL statements. This is the appropriate selection for functions whose results depend on database lookups, parameter variables (such as the current time zone), etc. Also note that the current_timestamp family of functions qualify as stable, since their values do not change within a transaction.

VOLATILE indicates that the function value can change even within a single table scan, so no optimizations can be made. Relatively few database functions are volatile in this sense; some examples are random(), currval(), timeofday(). Note that any function that has side-effects must be classified volatile, even if its result is quite predictable, to prevent calls from being optimized away; an example is setval().

CALLED ON NULL INPUT

RETURNS NULL ON NULL INPUT

STRICT

CALLED ON NULL INPUT (the default) indicates that the function will be called normally when some of its arguments are null. It is then the function author's responsibility to check for null values if necessary and respond appropriately.

RETURNS NULL ON NULL INPUT or STRICT indicates that the function always returns null whenever any of its arguments are null. If this parameter is specified, the function is not executed when there are null arguments; instead a null result is assumed automatically.

[EXTERNAL] SECURITY INVOKER

[EXTERNAL] SECURITY DEFINER

SECURITY INVOKER indicates that the function is to be executed with the privileges of the user that calls it. That is the default. SECURITY DEFINER specifies that the function is to be executed with the privileges of the user that created it.

The key word EXTERNAL is present for SQL conformance but is optional since, unlike in SQL, this feature does not only apply to external functions.

definition

A string defining the function; the meaning depends on the language. It may be an internal function name, the path to an object file, an SQL command, or text in a procedural language.

obj_file, link_symbol

This form of the AS clause is used for dynamically loadable C language functions when the function name in the C language source code is not the same as the name of the SQL function. The string obj_file is the name of the file containing the dynamically loadable object, and link_symbol is the function's link symbol, that is, the name of the function in the C language source code. If the link symbol is omitted, it is assumed to be the same as the name of the SQL function being defined.

attribute

The historical way to specify optional pieces of information about the function. The following attributes may appear here:

isStrict

Equivalent to STRICT or RETURNS NULL ON NULL INPUT

isCachable

isCachable is an obsolete equivalent of IMMUTABLE; it's still accepted for backwards-compatibility reasons.

Attribute names are not case-sensitive.  

NOTES

Refer to the section called ``User-Defined Functions'' in the documentation for further information on writing functions.

The full SQL type syntax is allowed for input arguments and return value. However, some details of the type specification (e.g., the precision field for type numeric) are the responsibility of the underlying function implementation and are silently swallowed (i.e., not recognized or enforced) by the CREATE FUNCTION command.

PostgreSQL allows function overloading; that is, the same name can be used for several different functions so long as they have distinct argument types. However, the C names of all functions must be different, so you must give overloaded C functions different C names (for example, use the argument types as part of the C names).

When repeated CREATE FUNCTION calls refer to the same object file, the file is only loaded once. To unload and reload the file (perhaps during development), use the LOAD [load(7)] command.

Use DROP FUNCTION to remove user-defined functions.

Any single quotes or backslashes in the function definition must be escaped by doubling them.

To be able to define a function, the user must have the USAGE privilege on the language.  

EXAMPLES

Here is a trivial example to help you get started. For more information and examples, see the section called ``User-Defined Functions'' in the documentation.

CREATE FUNCTION add(integer, integer) RETURNS integer
    AS 'select $1 + $2;'
    LANGUAGE SQL
    IMMUTABLE
    RETURNS NULL ON NULL INPUT;

COMPATIBILITY

A CREATE FUNCTION command is defined in SQL99. The PostgreSQL version is similar but not fully compatible. The attributes are not portable, neither are the different available languages.  

SEE ALSO

ALTER FUNCTION [alter_function(7)], DROP FUNCTION [drop_function(7)], GRANT [grant(7)], LOAD [load(7)], REVOKE [revoke(7)], createlang(1)