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聲明該函數將以創建它的用戶的權限執行。
關鍵字 EXTERNAL 的目的是和 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 的過時的等效物;不過出於向下兼容,我們仍然接受它。
屬性名是大小寫無關的。
這裏是一些簡單的例子,用於幫助你開始掌握這個命令。
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 $$ SELECT $1, CAST($1 AS text) || ' is text' $$
LANGUAGE SQL;
SELECT * FROM dup(42);
你可以通過命名明確的複合類型的方法冗長地幹同樣的事情:
CREATE TYPE dup_result AS (f1 int, f2 text);
CREATE FUNCTION dup(int) RETURNS dup_result
AS $$ SELECT $1, CAST($1 AS text) || ' is text' $$
LANGUAGE SQL;
SELECT * FROM dup(42);
兼容性在 SQL:1999 裏定義了一個CREATE FUNCTIONPostgreSQL的和它類似但是不兼容。這個屬性是不可移植的,可以使用的不同語言也是如此。
爲了和一些其他的數據庫系統兼容,argmode 可以在argname之前或者之後寫,但是隻有第一種訪法是標準兼容的。
http://www.postgresql.org/docs/9.1/static/sql-createfunction.html