CREATE FUNCTION

CREATE FUNCTIONdefinisce una nuova funzione.

Importante

In Amazon Aurora DSQL, supporta CREATE FUNCTION solo SQL-language le funzioni (). LANGUAGE sql

Sintassi supportata

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

Description

CREATE FUNCTIONdefinisce una nuova funzione. CREATE OR REPLACE FUNCTIONcreerà una nuova funzione o sostituirà una definizione esistente. Per poter definire una funzione, è necessario disporre del USAGE privilegio sulla lingua.

Se è incluso un nome di schema, la funzione viene creata nello schema specificato. Altrimenti, la funzione viene creata nello schema corrente. Il nome della nuova funzione non deve corrispondere a nessuna funzione esistente con gli stessi tipi di argomenti di input nello stesso schema. Tuttavia, le funzioni con diversi tipi di argomento possono condividere un nome (questo è chiamato sovraccarico).

Per sostituire la definizione corrente di una funzione esistente, usaCREATE OR REPLACE FUNCTION. Non è possibile modificare il nome o i tipi di argomento di una funzione in questo modo (ciò creerebbe effettivamente una nuova funzione distinta). Inoltre, non è possibile utilizzare CREATE OR REPLACE FUNCTION per modificare il tipo di ritorno di una funzione esistente. Per fare ciò, è necessario eliminare e ricreare la funzione.

Quando CREATE OR REPLACE FUNCTION viene utilizzato per sostituire una funzione esistente, la proprietà e le autorizzazioni della funzione non cambiano. A tutte le altre proprietà della funzione vengono assegnati i valori specificati o impliciti nel comando. È necessario possedere la funzione per sostituirla (ciò include essere un membro del ruolo proprietario).

Se si elimina e poi si ricrea una funzione, la nuova funzione non è la stessa entità della precedente; sarà necessario eliminare le regole, le visualizzazioni e così via esistenti che si riferiscono alla vecchia funzione. Si usa CREATE OR REPLACE FUNCTION per modificare la definizione di una funzione senza rompere gli oggetti che si riferiscono alla funzione.

Diventi il proprietario di una funzione che hai creato.

Per poter creare una funzione, è necessario disporre dei USAGE privilegi sui tipi di argomento e sul tipo restituito.

Una SQL funzione racchiude una o più SQL istruzioni in un'unità riutilizzabile e richiamabile. Utilizza le funzioni per centralizzare espressioni o calcoli comuni, applicare una logica coerente su più query e semplificare il codice dell'applicazione richiamando una singola funzione anziché ripetere la stessa. SQL

Parameters

name

Il nome (facoltativamente qualificato dallo schema) della funzione da creare.

argmode

La modalità di un argomento:IN,OUT, INOUT o. VARIADIC Se omesso, il valore predefinito èIN. VARIADICdeve essere l'ultimo parametro di input; solo OUT gli argomenti possono seguirlo. OUTe INOUT gli argomenti non possono essere combinati con la RETURNS TABLE notazione.

argname

Il nome di un argomento. In una funzione SQL, è possibile fare riferimento a un argomento per nome nel corpo della funzione. Anche il nome di un INOUT argomento OUT or è significativo, poiché definisce il nome della colonna corrispondente nel tipo di riga dei risultati.

argtype

Il tipo di dati di un argomento. Può trattarsi di qualsiasi tipo di DSQL-supported base, tipo di array o dominio Aurora. Per ulteriori informazioni, consulta Tipi di dati supportati in Aurora DSQL. È inoltre possibile fare riferimento al tipo di una colonna di tabella esistente utilizzando la %TYPE notazione.

default_expr

Un'espressione da utilizzare come valore predefinito se l'argomento non è specificato. L'espressione deve essere coercibile al tipo di argomento del parametro. Solo IN gli INOUT argomenti possono avere un valore predefinito. Ogni argomento dopo uno con un valore predefinito deve avere anche un valore predefinito.

rettype

Il tipo di dati restituito. Può trattarsi di qualsiasi tipo di DSQL-supported base, tipo di array o dominio Aurora. Per ulteriori informazioni, consulta Tipi di dati supportati in Aurora DSQL. Per restituire un set di righe, usa SETOF rettype oRETURNS TABLE. Se non si prevede che la funzione restituisca un valore, void specificalo come tipo restituito. Se sono presenti INOUT parametri OUT o, la RETURNS clausola può essere omessa e la funzione restituisce uno record o il tipo di riga corrispondente.

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

Speciifica che la funzione restituisce un set di righe con le colonne denominate e i relativi tipi. Ciò equivale a dichiarare uno o più OUT parametri e specificarlo SETOF come tipo restituito.

LANGUAGE sql

Il linguaggio usato per implementare la funzione. In Aurora DSQL, deve essere così. sql Se si omette la LANGUAGE clausola e si fornisce un RETURN corpo BEGIN ATOMIC o, si presume. sql Una stringa costante body (AS 'definition') richiede una LANGUAGE sql clausola esplicita; la sua omissione fallisce con l'errore. no language specified

IMMUTABLE / STABLE / VOLATILE

Questi attributi informano l'ottimizzatore di query sul comportamento della funzione. È possibile specificarne al massimo uno. Se li ometti tutti e tre, la funzione viene impostata per impostazione predefinita su. VOLATILE

• IMMUTABLEindica che la funzione non può modificare il database e restituisce sempre lo stesso risultato quando vengono assegnati gli stessi valori di argomento.

• STABLEindica che la funzione non può modificare il database. All'interno di una singola scansione della tabella, restituisce costantemente lo stesso risultato per gli stessi valori degli argomenti, ma il risultato potrebbe cambiare tra le istruzioni SQL.

• VOLATILEindica che il valore della funzione può cambiare anche all'interno di una singola scansione della tabella, quindi non è possibile effettuare ottimizzazioni.

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

CALLED ON NULL INPUT(impostazione predefinita) indica che la funzione viene chiamata normalmente quando alcuni dei suoi argomenti sono nulli. RETURNS NULL ON NULL INPUTo STRICT indica che la funzione restituisce sempre null quando uno qualsiasi dei suoi argomenti è nullo. Se specificato, Aurora DSQL non esegue la funzione quando un argomento è nullo; invece, la funzione restituisce automaticamente null.

[ EXTERNAL ] SECURITY INVOKER / [ EXTERNAL ] SECURITY DEFINER

SECURITY INVOKER(impostazione predefinita) indica che la funzione deve essere eseguita con i privilegi dell'utente che la chiama. SECURITY DEFINERspecifica che la funzione deve essere eseguita con i privilegi dell'utente che la possiede. La parola chiave EXTERNAL è consentita per la conformità a SQL, ma è facoltativa.

PARALLEL { UNSAFE | RESTRICTED | SAFE }

Aurora DSQL accetta e archivia la marcatura. PARALLEL Tuttavia, questa marcatura non influisce sull'esecuzione delle query.

COST execution_cost

Un numero positivo che indica il costo di esecuzione stimato per la funzione. Se la funzione restituisce un set, questo valore è il costo stimato per riga restituita. Il pianificatore di query utilizza questa stima quando non include la funzione.

ROWS result_rows

Un numero positivo che indica il numero stimato di righe che il pianificatore di query dovrebbe aspettarsi che la funzione restituisca. Ciò è consentito solo quando si dichiara che la funzione restituisce un set. Il presupposto predefinito è 1000 righe.

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

La SET clausola fa sì che il parametro di configurazione specificato venga impostato sul valore specificato quando viene immessa la funzione e quindi ripristinato al valore precedente quando la funzione viene chiusa. SET FROM CURRENTsalva il valore del parametro che è corrente quando CREATE FUNCTION viene eseguito come valore da applicare quando viene immessa la funzione.

AS 'definition'

Una costante di stringa che definisce la funzione; il significato dipende dalla lingua. Per una SQL-language funzione, sono le istruzioni SQL che costituiscono il corpo della funzione.

RETURN expression

Definisce il corpo della funzione utilizzando la SQL-standard sintassi di una funzione che restituisce una singola espressione. Si tratta di un'alternativa alla forma a stringa costante.

BEGIN ATOMIC statement; [ ... ] END

Definisce il corpo della funzione utilizzando la SQL-standard sintassi. Il corpo è costituito da una o più istruzioni SQL. Questo modulo è valido solo perLANGUAGE sql. Le istruzioni in un corpo atomico vengono tracciate come dipendenze della funzione. Ad esempio, una tabella a cui si fa riferimento nel corpo non può essere eliminata senza eliminare anche la funzione o utilizzarla. DROP ... CASCADE

Note

Utilizzate l'DROP FUNCTIONistruzione per rimuovere una funzione. È inoltre possibile concedere e revocare i privilegi su una funzione con GRANT and REVOKE (ad esempio,). REVOKE ALL ON FUNCTION

Qualsiasi funzione che legge o modifica i dati nelle tabelle è soggetta allo stesso comportamento di transazione e concorrenza delle istruzioni SQL equivalenti eseguite direttamente. Le funzioni dichiarate IMMUTABLE o non STABLE devono modificare il database.

Per aggiornare la definizione di una funzione esistente, utilizzareCREATE OR REPLACE FUNCTION. Non è possibile modificare i tipi di argomento o restituire il tipo di funzione in questo modo; è invece possibile eliminare e ricreare la funzione.

Per rinominare una funzione, cambiarne il proprietario o spostarla in un altro schema, usa. ALTER FUNCTION Per modificare qualsiasi altro attributo, utilizzatelo CREATE OR REPLACE FUNCTION con le modifiche desiderate. Per ulteriori informazioni, consulta ALTER FUNCTION.

È supportato il sovraccarico delle funzioni: è possibile definire diverse funzioni con lo stesso nome purché i tipi di argomenti di input siano diversi. Una funzione definita dall'utente può anche richiamare altre funzioni e oscurare una funzione incorporata con lo stesso nome e lo stesso tipo di argomento.

Per una funzione che restituisce un set (SETOFoRETURNS TABLE) il cui corpo contiene più di un'istruzione, viene restituito solo il risultato dell'istruzione finale. La funzione esegue ancora le istruzioni precedenti, ma ne scarta i risultati. Questo è il comportamento standard per SQL-language le funzioni. Strutturate la funzione in modo che la sua dichiarazione finale produca il set completo di risultati.

Una funzione di restituzione dei set non garantisce alcun ordine di riga particolare. Per controllare l'ordine delle righe, includete una ORDER BY clausola nella query.

Considerazioni

Le seguenti CREATE FUNCTION funzionalità restituiscono l'errore mostrato.

LEAKPROOF

Restituisce l'erroreonly superuser can define a leakproof function. NOT LEAKPROOF(impostazione predefinita) è accettata.

TRANSFORM FOR TYPE

Restituisce l'erroretransform for type type language "sql" does not exist.

SUPPORT(funzione di supporto del pianificatore)

Restituisce l'errorefunction name(internal) does not exist.

User-defined tipi compositi (CREATE TYPE ... AS), incluse le funzioni che restituiscono un tipo composito

Restituisce l'erroreunsupported statement: CompositeType.

Aurora DSQL non supportaCREATE PROCEDURE, il che fallisce con l'errore. PROCEDURE is not supported

L'WINDOWattributo è accettato sintatticamente ma non è utile per le funzioni. SQL-language Evita di usare questo attributo.

Esempi

Crea una semplice funzione SQL che aggiunge due numeri interi, utilizzando un corpo di stringa costante:

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

Crea la stessa funzione usando il SQL-standard RETURN corpo e gli argomenti denominati:

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

Crea una funzione che restituisca un insieme di righe utilizzando RETURNS TABLE e un BEGIN ATOMIC corpo:

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;

Crea una funzione che funzioni con i privilegi del proprietario e imposta un parametro di configurazione per la durata della chiamata:

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

Compatibilità

Un CREATE FUNCTION comando è definito nello standard SQL. L'implementazione di PostgreSQL può essere utilizzata in modo compatibile ma ha molte estensioni. Al contrario, lo standard SQL specifica una serie di funzionalità opzionali che non sono implementate in PostgreSQL.

Di seguito sono riportati importanti problemi di compatibilità:

• OR REPLACEè un'estensione PostgreSQL.

• Per compatibilità con altri sistemi di database, argmode può essere scritto prima o dopo. argname Ma solo il primo metodo è conforme agli standard.

• Per i parametri predefiniti, lo standard SQL specifica solo la sintassi con la parola chiave. DEFAULT La sintassi with = è usata in and Firebird. T-SQL

• Il SETOF modificatore è un'estensione PostgreSQL.

• Solo SQL è standardizzato come linguaggio.

• Tutti gli altri attributi tranne CALLED ON NULL INPUT e non RETURNS NULL ON NULL INPUT sono standardizzati.

• Per il corpo delle LANGUAGE sql funzioni, lo standard SQL specifica solo il sql_body modulo.

LANGUAGE sqlLe funzioni semplici possono essere scritte in modo conforme agli standard e portabile ad altre implementazioni. Le funzioni più complesse che utilizzano funzionalità avanzate, attributi di ottimizzazione o altri linguaggi saranno necessariamente specifiche di PostgreSQL in modo significativo.