CREATE [ OR REPLACE ] FUNCTION nome ( [ tipo_do_argumento [, ...] ] )
RETURNS tipo_retornado
{ LANGUAGE nome_da_linguagem
| IMMUTABLE | STABLE | VOLATILE
| CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
| [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER
| AS 'definição'
| AS 'arquivo_objeto', 'símbolo_de_vínculação'
} ...
[ WITH ( atributo [, ...] ) ]
O comando CREATE FUNCTION cria uma função. O comando CREATE OR REPLACE FUNCTION cria uma função, ou substitui uma função existente.
Se o nome do esquema for incluído então a função é criada no esquema especificado, senão é criada no esquema corrente. O nome da nova função não deve ser igual ao de outra função existente com argumentos do mesmo tipo, no mesmo esquema. Entretanto, funções com argumentos de tipos diferentes podem ter o mesmo nome, o que é chamado de sobrecarga (overload).
Para atualizar a definição de uma função existente deve ser usado o comando CREATE OR REPLACE FUNCTION. Não é possível mudar o nome ou os tipos dos argumentos da função desta maneira; se for tentado, será criada uma nova função distinta. O comando CREATE OR REPLACE FUNCTION também não permite mudar o tipo de dado retornado por uma função existente; para fazer isto a função deve ser removida e recriada.
Se a função for removida e recriada, a nova função não é mais a mesma entidade que era antes; será necessário remover as regras, visões, gatilhos, etc. que fazem referência à função antiga. Use o comando CREATE OR REPLACE FUNCTION para mudar a definição de uma função sem invalidar os objetos que fazem referência à função.
O usuário que cria a função se torna o seu dono.
current_timestamp se qualifica como estável, uma vez que seus valores não mudam dentro de uma transação.
O atributo VOLATILE indica que o valor da função pode mudar mesmo dentro de uma única varredura da tabela e, portanto, nenhuma otimização pode ser feita. Poucas funções de banco de dados são voláteis neste sentido; alguns exemplos são random(), currval() e timeofday(). Deve ser observado que toda função que produz efeito colateral deve ser classificada como volátil, mesmo que seu resultado seja totalmente previsível, para evitar que as chamadas sejam otimizadas; um exemplo é setval().
Não há diferença entre letras minúsculas de maiúsculas nos nomes de atributos.
Consulte a Seção 33.3 para obter mais informações sobre como escrever funções.
A sintaxe tipo SQL completa é permitida para os argumentos de entrada e o valor retornado. Entretanto, alguns detalhes da especificação do tipo (por exemplo, o campo precisão para o tipo numeric) são de responsabilidade da implementação da função subjacente, sendo engolidos em silêncio (ou seja, não são reconhecidos nem exigidos) pelo comando CREATE FUNCTION.
O PostgreSQL permite a sobrecarga de função, ou seja, o mesmo nome pode ser utilizado por várias funções diferentes, desde que possuam argumentos com tipos distintos. Entretanto, na linguagem C os nomes de todas as funções devem ser diferentes e, portanto, as funções na linguagem C sobrecarregadas devem possuir nomes diferentes (por exemplo, utilizando os tipos dos argumentos como parte do nome na linguagem C).
Quando chamadas repetidas ao comando CREATE FUNCTION fazem referência ao mesmo arquivo objeto, o arquivo só é carregado uma vez. Para descarregar e recarregar o arquivo (talvez durante o desenvolvimento), deve ser usado o comando LOAD .
Use o comando DROP FUNCTION para remover funções definidas pelo usuário.
Todo apóstrofo (') ou contrabarra (\) presente na definição da função deve ser escrito duas vezes.
Para poder criar uma função o usuário deve possuir o privilégio USAGE na linguagem.
Abaixo estão mostrados exemplos simples para ajudar a começar. Para obter mais informações e exemplos deve ser vista a Seção 33.3 .
Somar dois números inteiros. Esta função recebe como argumentos dois números inteiros, e retorna como resultado a soma dos dois números recebidos.
CREATE FUNCTION soma(integer, integer) RETURNS integer
AS 'select $1 + $2;'
LANGUAGE SQL
IMMUTABLE
RETURNS NULL ON NULL INPUT;
Somar dias a uma data. A seguir está mostrada uma função sobrecarregada para somar dias a data. Pode ser utilizada com os tipos de dado date, timestamp e timestamp with time zone. [1]
CREATE OR REPLACE FUNCTION soma_dias(data date,dias integer)
RETURNS date AS '
DECLARE
nova_data date;
BEGIN
nova_data := data + dias;
RETURN nova_data;
END;
' LANGUAGE plpgsql;
CREATE OR REPLACE FUNCTION soma_dias(data timestamp,dias integer)
RETURNS timestamp AS '
DECLARE
nova_data timestamp;
hora interval;
BEGIN
hora := data - CAST(data AS DATE);
nova_data := CAST(data AS DATE)+ dias;
RETURN nova_data + hora;
END;
' LANGUAGE plpgsql;
CREATE OR REPLACE FUNCTION soma_dias(data timestamp with time zone, dias integer)
RETURNS timestamp with time zone AS '
DECLARE
nova_data timestamp with time zone;
hora interval;
BEGIN
hora := data - CAST(data AS DATE);
nova_data := CAST(data AS DATE)+ dias;
RETURN nova_data + hora;
END;
' LANGUAGE plpgsql;
SELECT soma_dias(date '2004-07-16', 30);
soma_dias
------------
2004-08-15
(1 linha)
SELECT soma_dias(timestamp '2004-07-16 15:00:00', 30);
soma_dias
---------------------
2004-08-15 15:00:00
(1 linha)
SELECT current_timestamp, soma_dias(current_timestamp, 30);
timestamptz | soma_dias
-------------------------------+-------------------------------
2005-02-15 21:29:05.403436-02 | 2005-03-17 21:29:05.403436-03
(1 linha)
O comando CREATE FUNCTION está definido no SQL:1999 e posterior. A versão do PostgreSQL é semelhante mas não é totalmente compatível. Os atributos não são portáveis, nem as diferentes linguagens disponíveis o são.
| [1] |
Exemplo escrito pelo tradutor, não fazendo parte do manual original. |