Sintaxe compatível Descrição Parâmetros Observações Considerações Exemplos Compatibilidade

`CREATE FUNCTION`

CREATE FUNCTION define uma nova função.

Importante

No Amazon Aurora DSQL, CREATE FUNCTION só comporta funções da linguagem SQL (LANGUAGE sql).

Sintaxe compatível


CREATE [ OR REPLACE ] FUNCTION
    name ( [ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [, ...] ] )
    [ RETURNS rettype
      | RETURNS TABLE ( column_name column_type [, ...] ) ]
  { LANGUAGE sql
    | { IMMUTABLE | STABLE | VOLATILE }
    | { CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT }
    | { [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER }
    | PARALLEL { UNSAFE | RESTRICTED | SAFE }
    | COST execution_cost
    | ROWS result_rows
    | SET configuration_parameter { TO value | = value | FROM CURRENT }
    | AS 'definition'
    | RETURN expression
    | BEGIN ATOMIC statement; [ statement; ... ] END
  } ...

where LANGUAGE must be sql

Descrição

CREATE FUNCTION define uma nova função. CREATE OR REPLACE FUNCTION criará uma função ou substituirá uma definição existente. Para poder definir uma função, é necessário ter o privilégio USAGE na linguagem.

Se um nome de esquema for incluído, a função será criada no esquema especificado. Caso contrário, a função será criada no esquema atual. O nome da nova função não deve corresponder a nenhuma função existente com os mesmos tipos de argumentos de entrada no mesmo esquema. No entanto, funções de diferentes tipos de argumentos podem compartilhar um nome (isso é chamado de sobrecarga).

Para substituir a definição atual de uma função existente, use CREATE OR REPLACE FUNCTION. Você não pode alterar o nome nem os tipos de argumento de uma função dessa forma (isso, na verdade, criaria uma função nova e distinta). Além disso, você não pode usar CREATE OR REPLACE FUNCTION para alterar o tipo de retorno de uma função existente. Para isso, é necessário descartar e recriar a função.

Quando CREATE OR REPLACE FUNCTION é usado para substituir uma função existente, a propriedade e as permissões da função não mudam. Todas as outras propriedades da função recebem os valores especificados ou implícitos no comando. Para substituir uma função, ela deve pertencer a você (isso inclui ser membro do perfil de propriedade).

Se você descartar e depois recriar uma função, a nova função não será a mesma entidade da antiga; você terá que descartar as regras, visualizações etc. existentes, que se referem à função antiga. Use CREATE OR REPLACE FUNCTION para alterar a definição de uma função sem romper objetos que se refiram à função.

Você se torna o proprietário de uma função que você criou.

Para poder criar uma função, você deve ter o privilégio USAGE sobre os tipos de argumentos e o tipo de retorno.

Uma função SQL agrupa uma ou mais instruções SQL em uma unidade reutilizável e chamável. Use funções para centralizar expressões ou cálculos comuns, aplicar lógica consistente em várias consultas e simplificar o código da aplicação chamando uma única função em vez de repetir o mesmo código SQL.

Parâmetros

name

O nome (opcionalmente qualificado para o esquema) da função a ser criada.

argmode

O modo de um argumento: IN, OUT, INOUT ou VARIADIC. Se for omitido, o padrão será IN. VARIADIC deve ser o último parâmetro de entrada; somente argumentos OUT podem segui-lo. Os argumentos OUT e INOUT não podem ser combinados com a notação RETURNS TABLE.

argname

O nome de um argumento. Em uma função SQL, você pode se referir a um argumento pelo nome no corpo da função. O nome de um argumento OUT ou INOUT também é significativo, pois define o nome da coluna correspondente no tipo de linha de resultado.

argtype

Tipo de dados de um argumento. Isso pode ser qualquer tipo básico, tipo de matriz ou domínio compatível com o Aurora DSQL. Para obter mais informações, consulte Tipos de dados compatíveis no Aurora DSQL. Você também pode fazer referência ao tipo de uma coluna de tabela existente usando a notação %TYPE.

default_expr

Uma expressão a ser usada como valor padrão se o argumento não for especificado. A expressão deve ser convertida no tipo de argumento do parâmetro. Somente os argumentos IN e INOUT podem ter um valor padrão. Todos os argumentos após um argumento com valor padrão também devem ter um valor padrão.

rettype

O tipo de dados de retorno. Isso pode ser qualquer tipo básico, tipo de matriz ou domínio compatível com o Aurora DSQL. Para obter mais informações, consulte Tipos de dados compatíveis no Aurora DSQL. Para exibir um conjunto de linhas, use SETOF rettype ou RETURNS TABLE. Se a função não deve retornar um valor, especifique void como o tipo de retorno. Quando há parâmetros OUT ou INOUT, a cláusula RETURNS pode ser omitida e a função exibe um record ou o tipo de linha correspondente.

RETURNS TABLE ( column_name column_type [, ...] )

Especifica que a função exiba um conjunto de linhas com as colunas nomeadas e seus tipos. Isso equivale a declarar um ou mais parâmetros OUT e especificar SETOF como o tipo de retorno.

LANGUAGE sql

A linguagem usada para implementar a função. No Aurora DSQL, deve ser sql. Se você omitir a cláusula LANGUAGE e fornecer um corpo BEGIN ATOMIC ou RETURN, sql será considerado o padrão. Um corpo constante de string (AS 'definition') requer uma cláusula LANGUAGE sql explícita; omiti-la resulta no erro no language specified.

IMMUTABLE / STABLE / VOLATILE

Esses atributos informam o otimizador de consulta sobre o comportamento da função. Você pode especificar no máximo um. Se você omitir todos os três, o padrão da função será VOLATILE.

IMMUTABLE indica que a função não pode modificar o banco de dados e sempre exibe o mesmo resultado quando recebe os mesmos valores de argumento.
STABLE indica que a função não pode modificar o banco de dados. Em uma única verificação de tabela, ela exibe consistentemente o mesmo resultado para os mesmos valores de argumento, mas o resultado pode mudar nas instruções SQL.
VOLATILE indica que o valor da função pode mudar mesmo em uma única verificação de tabela, portanto, nenhuma otimização pode ser feita.

CALLED ON NULL INPUT / RETURNS NULL ON NULL INPUT / STRICT

CALLED ON NULL INPUT (o padrão) indica que a função é chamada normalmente quando alguns de seus argumentos são nulos. RETURNS NULL ON NULL INPUT ou STRICT indica que a função sempre exibe nulo quando qualquer um de seus argumentos é nulo. Se especificado, o Aurora DSQL não executa a função quando qualquer argumento é nulo; em vez disso, a função exibe nulo automaticamente.

[ EXTERNAL ] SECURITY INVOKER / [ EXTERNAL ] SECURITY DEFINER

SECURITY INVOKER (o padrão) indica que a função deve ser executada com os privilégios do usuário que a chama. SECURITY DEFINER especifica que a função deve ser executada com os privilégios do usuário que a possui. A palavra-chave EXTERNAL é permitida para conformidade com SQL, mas é opcional.

PARALLEL { UNSAFE | RESTRICTED | SAFE }

O Aurora DSQL aceita e armazena a marcação PARALLEL. No entanto, essa marcação não afeta a execução da consulta.

COST execution_cost

Um número positivo dando o custo de execução estimado para a função. Se a função exibir um conjunto, esse valor será o custo estimado por linha exibida. O planejador de consultas usa essa estimativa quando não incorpora a função.

ROWS result_rows

Um número positivo que fornece o número estimado de linhas que o planejador de consultas deve esperar que a função exiba. Isso só é permitido quando a função é declarada para exibir um conjunto. A suposição padrão é mil linhas.

SET configuration_parameter { TO value | = value | FROM CURRENT }

A cláusula SET faz com que o parâmetro de configuração especificado seja definido como o valor especificado quando a função é inserida e, depois, restaurado ao valor anterior quando a função é encerrada. SET FROM CURRENT salva o valor do parâmetro que é atual quando CREATE FUNCTION é executado como o valor a ser aplicado quando a função é inserida.

AS 'definition'

Uma constante de string definindo a função; o significado depende da linguagem. Para uma função em linguagem SQL, são as instruções SQL que compõem o corpo da função.

RETURN expression

Define o corpo da função usando a sintaxe padrão SQL para uma função que exibe uma única expressão. Essa é uma alternativa à forma constante de string.

BEGIN ATOMIC statement; [ ... ] END

Define o corpo da função usando a sintaxe padrão SQL. O corpo consiste em uma ou mais instruções SQL. Este formulário só é válido para LANGUAGE sql. As declarações em um corpo atômico são rastreadas como dependências da função. Por exemplo, uma tabela referida no corpo não pode ser descartada sem também eliminar a função ou que se use DROP ... CASCADE.

Observações

Use a instrução DROP FUNCTION para remover uma função. Você também pode conceder e revogar privilégios em uma função com GRANT e REVOKE (por exemplo, REVOKE ALL ON FUNCTION).

Qualquer função que lê ou modifica dados em tabelas está sujeita ao mesmo comportamento de transação e simultaneidade que as instruções SQL equivalentes executadas diretamente. Funções declaradas IMMUTABLE ou STABLE não devem modificar o banco de dados.

Para atualizar a definição atual de uma função existente, use CREATE OR REPLACE FUNCTION. Você não pode alterar os tipos de argumentos nem o tipo de retorno de uma função dessa forma; em vez disso, descarte e recrie a função.

Para renomear uma função, alterar seu proprietário ou mova-a para outro esquema, use ALTER FUNCTION. Para alterar qualquer outro atributo, use CREATE OR REPLACE FUNCTION com as alterações desejadas. Para obter mais informações, consulte ALTER FUNCTION.

A sobrecarga de funções é aceita: você pode definir várias funções com o mesmo nome, desde que seus tipos de argumentos de entrada sejam diferentes. Uma função definida pelo usuário também pode chamar outras funções e pode sombrear uma função interna com o mesmo nome e tipos de argumento.

Para uma função que exibe um conjunto (SETOF ou RETURNS TABLE) cujo corpo contém mais de uma instrução, somente o resultado da declaração final é exibido. A função ainda executa as instruções anteriores, mas descarta seus resultados. Esse é o comportamento padrão das funções da linguagem SQL. Estruture a função para que sua declaração final produza o conjunto completo de resultados.

Uma função que exibe um conjunto não garante nenhuma ordem de linhas específica. Para controlar a ordem das linhas, inclua uma cláusula ORDER BY na consulta.

Considerações

Os recursos CREATE FUNCTION a seguir exibem o erro mostrado.

LEAKPROOF: Exibe o erro only superuser can define a leakproof function. NOT LEAKPROOF (o padrão) é aceito.
TRANSFORM FOR TYPE: Exibe o erro transform for type type language "sql" does not exist.
SUPPORT (função de suporte do planejador): Exibe o erro function name(internal) does not exist.
Tipos compostos definidos pelo usuário (CREATE TYPE ... AS), incluindo funções que exibem um tipo composto: Exibe o erro unsupported statement: CompositeType.

O Aurora DSQL não comporta CREATE PROCEDURE, o que resulta no erro PROCEDURE is not supported.

O atributo WINDOW é aceito sintaticamente, mas não é útil para funções da linguagem SQL. Evite usar esse atributo.

Exemplos

Crie uma função SQL simples que adicione dois números inteiros, usando um corpo constante de string:


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

Crie a mesma função usando o corpo RETURN padrão SQL e os argumentos nomeados:


CREATE FUNCTION add(a integer, b integer) RETURNS integer
    LANGUAGE sql
    IMMUTABLE
    RETURN a + b;

Crie uma função que exiba um conjunto de linhas usando RETURNS TABLE e um corpo BEGIN ATOMIC:


CREATE FUNCTION employees_in_dept(dept_id integer)
    RETURNS TABLE (id integer, name text)
    LANGUAGE sql
    STABLE
    BEGIN ATOMIC
        SELECT id, name FROM employees WHERE department_id = dept_id;
    END;

Crie uma função que seja executada com os privilégios de seu proprietário e defina um parâmetro de configuração para a duração da chamada:


CREATE FUNCTION current_department() RETURNS text
    LANGUAGE sql
    STABLE
    SECURITY DEFINER
    SET search_path = app
    AS 'SELECT current_setting(''app.department'');';

Compatibilidade

Um comando CREATE FUNCTION é definido no padrão SQL. A implementação do PostgreSQL pode ser usada de forma compatível, mas tem muitas extensões. Por outro lado, o padrão SQL especifica vários recursos opcionais que não são implementados no PostgreSQL.

Veja a seguir problemas importantes de compatibilidade:

OR REPLACE é uma extensão da linguagem PostgreSQL.
Para compatibilidade com alguns outros sistemas de banco de dados, argmode pode ser escrito antes ou depois de argname. Mas somente a primeira forma é compatível com os padrões.
Para padrões de parâmetros, o padrão SQL especifica somente a sintaxe com a palavra-chave DEFAULT. A sintaxe com = é usada no T-SQL e no Firebird.
O modificador SETOF é uma extensão do PostgreSQL.
Somente o SQL é padronizado como linguagem.
Todos os outros atributos, exceto CALLED ON NULL INPUT e RETURNS NULL ON NULL INPUT, não são padronizados.
Para o corpo das funções LANGUAGE sql, o padrão SQL especifica apenas o formato sql_body.

Funções LANGUAGE sql simples podem ser escritas de uma forma que esteja em conformidade com os padrões e portátil para outras implementações. Funções mais complexas usando recursos avançados, atributos de otimização ou outras linguagens serão necessariamente específicas do PostgreSQL de forma significativa.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

SET CONSTRAINTS

ALTER FUNCTION