CREATE FUNCTION

CREATE FUNCTIONdefiniert eine neue Funktion.

Wichtig

Unterstützt in Amazon Aurora DSQL CREATE FUNCTION nur SQL-language functions (LANGUAGE sql).

Unterstützte Syntax

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 FUNCTIONdefiniert eine neue Funktion. CREATE OR REPLACE FUNCTIONerstellt entweder eine neue Funktion oder ersetzt eine bestehende Definition. Um eine Funktion definieren zu können, müssen Sie über die USAGE entsprechenden Sprachrechte verfügen.

Wenn ein Schemaname enthalten ist, wird die Funktion im angegebenen Schema erstellt. Andernfalls wird die Funktion im aktuellen Schema erstellt. Der Name der neuen Funktion darf mit keiner vorhandenen Funktion mit denselben Eingabeargumenttypen im selben Schema übereinstimmen. Funktionen verschiedener Argumenttypen können jedoch einen gemeinsamen Namen haben (dies wird als Überladen bezeichnet).

Um die aktuelle Definition einer vorhandenen Funktion zu ersetzen, verwenden SieCREATE OR REPLACE FUNCTION. Sie können den Namen oder die Argumenttypen einer Funktion auf diese Weise nicht ändern (dadurch würde tatsächlich eine neue, eigenständige Funktion entstehen). Sie können es auch nicht verwenden, CREATE OR REPLACE FUNCTION um den Rückgabetyp einer vorhandenen Funktion zu ändern. Dazu müssen Sie die Funktion löschen und neu erstellen.

Wenn verwendet CREATE OR REPLACE FUNCTION wird, um eine bestehende Funktion zu ersetzen, ändern sich der Besitz und die Berechtigungen der Funktion nicht. Allen anderen Funktionseigenschaften werden die im Befehl angegebenen oder implizierten Werte zugewiesen. Sie müssen Eigentümer der Funktion sein, um sie zu ersetzen (dazu gehört auch, dass Sie Mitglied der Eigentümerrolle sind).

Wenn Sie eine Funktion löschen und dann neu erstellen, ist die neue Funktion nicht dieselbe Entität wie die alte. Sie müssen bestehende Regeln, Ansichten usw. löschen, die sich auf die alte Funktion beziehen. Wird verwendetCREATE OR REPLACE FUNCTION, um eine Funktionsdefinition zu ändern, ohne Objekte zu beschädigen, die auf die Funktion verweisen.

Sie werden Eigentümer einer von Ihnen erstellten Funktion.

Um eine Funktion erstellen zu können, müssen Sie über USAGE Berechtigungen für die Argumenttypen und den Rückgabetyp verfügen.

Eine SQL Funktion fasst eine oder mehrere SQL Anweisungen in eine wiederverwendbare, aufrufbare Einheit zusammen. Verwenden Sie Funktionen, um allgemeine Ausdrücke oder Berechnungen zu zentralisieren, konsistente Logik auf mehrere Abfragen anzuwenden und den Anwendungscode zu vereinfachen, indem Sie eine einzelne Funktion aufrufen, anstatt dieselbe zu wiederholen. SQL

Parameters

name

Der Name (optional schemaqualifiziert) der zu erstellenden Funktion.

argmode

Der Modus eines Arguments:IN, OUTINOUT, oder. VARIADIC Wenn es weggelassen wird, ist die StandardeinstellungIN. VARIADICmuss der letzte Eingabeparameter sein; ihm können nur OUT Argumente folgen. OUTund INOUT Argumente können nicht mit der RETURNS TABLE Notation kombiniert werden.

argname

Der Name eines Arguments. In einer SQL-Funktion können Sie im Hauptteil der Funktion anhand des Namens auf ein Argument verweisen. Der Name eines OUT INOUT OR-Arguments ist ebenfalls von Bedeutung, da er den entsprechenden Spaltennamen im Ergebniszeilentyp definiert.

argtype

Der Datentyp eines Arguments. Dies kann ein beliebiger DSQL-supported Aurora-Basistyp, Array-Typ oder Domain sein. Weitere Informationen finden Sie unter Unterstützte Datentypen in Aurora DSQL. Sie können auch mithilfe der %TYPE Notation auf den Typ einer vorhandenen Tabellenspalte verweisen.

default_expr

Ein Ausdruck, der als Standardwert verwendet werden soll, wenn das Argument nicht angegeben ist. Der Ausdruck muss vom Argumenttyp des Parameters abhängig gemacht werden können. Nur IN INOUT AND-Argumente können einen Standardwert haben. Jedes Argument nach dem anderen mit einem Standardwert muss auch einen Standardwert haben.

rettype

Der Rückgabedatentyp. Dies kann ein beliebiger DSQL-supported Aurora-Basistyp, Array-Typ oder Domain sein. Weitere Informationen finden Sie unter Unterstützte Datentypen in Aurora DSQL. Um eine Reihe von Zeilen zurückzugeben, verwenden Sie SETOF rettype oderRETURNS TABLE. Wenn die Funktion keinen Wert zurückgeben soll, geben Sie void als Rückgabetyp an. Wenn es OUT oder INOUT Parameter gibt, kann die RETURNS Klausel weggelassen werden und die Funktion gibt einen record oder den entsprechenden Zeilentyp zurück.

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

Gibt an, dass die Funktion eine Reihe von Zeilen mit den benannten Spalten und ihren Typen zurückgibt. Dies entspricht der Deklaration eines oder mehrerer OUT Parameter und der Angabe SETOF als Rückgabetyp.

LANGUAGE sql

Die Sprache, die zur Implementierung der Funktion verwendet wurde. In Aurora DSQL muss das so sein. sql Wenn Sie die LANGUAGE Klausel weglassen und einen BEGIN ATOMIC RETURN Oder-Hauptteil angeben, sql wird davon ausgegangen. Eine Zeichenkettenkonstante body (AS 'definition') erfordert eine explizite LANGUAGE sql Klausel; das Auslassen schlägt mit dem Fehler fehl. no language specified

IMMUTABLE / STABLE / VOLATILE

Diese Attribute informieren den Abfrageoptimierer über das Verhalten der Funktion. Sie können höchstens eine angeben. Wenn Sie alle drei weglassen, ist die Funktion standardmäßig auf eingestellt. VOLATILE

• IMMUTABLEgibt an, dass die Funktion die Datenbank nicht ändern kann und immer dasselbe Ergebnis zurückgibt, wenn dieselben Argumentwerte angegeben werden.

• STABLEgibt an, dass die Funktion die Datenbank nicht ändern kann. Innerhalb eines einzelnen Tabellenscans gibt sie konsistent dasselbe Ergebnis für dieselben Argumentwerte zurück, aber das Ergebnis kann sich zwischen den einzelnen SQL-Anweisungen ändern.

• VOLATILEgibt an, dass sich der Funktionswert auch innerhalb eines einzelnen Tabellenscans ändern kann, sodass keine Optimierungen vorgenommen werden können.

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

CALLED ON NULL INPUT(Standard) gibt an, dass die Funktion normal aufgerufen wird, wenn einige ihrer Argumente Null sind. RETURNS NULL ON NULL INPUToder STRICT gibt an, dass die Funktion immer Null zurückgibt, wenn eines ihrer Argumente Null ist. Falls angegeben, führt Aurora DSQL die Funktion nicht aus, wenn ein Argument Null ist. Stattdessen gibt die Funktion automatisch Null zurück.

[ EXTERNAL ] SECURITY INVOKER / [ EXTERNAL ] SECURITY DEFINER

SECURITY INVOKER(Standard) gibt an, dass die Funktion mit den Rechten des Benutzers ausgeführt werden soll, der sie aufruft. SECURITY DEFINERgibt an, dass die Funktion mit den Rechten des Benutzers ausgeführt werden soll, dem sie gehört. Das Schlüsselwort EXTERNAL ist aus Gründen der SQL-Konformität zulässig, aber optional.

PARALLEL { UNSAFE | RESTRICTED | SAFE }

Aurora DSQL akzeptiert und speichert die PARALLEL Markierung. Diese Markierung hat jedoch keinen Einfluss auf die Abfrageausführung.

COST execution_cost

Eine positive Zahl, die die geschätzten Ausführungskosten für die Funktion angibt. Wenn die Funktion eine Menge zurückgibt, entspricht dieser Wert den geschätzten Kosten pro zurückgegebener Zeile. Der Abfrageplaner verwendet diese Schätzung, wenn er die Funktion nicht integriert.

ROWS result_rows

Eine positive Zahl, die die geschätzte Anzahl von Zeilen angibt, die der Abfrageplaner von der Funktion erwarten sollte. Dies ist nur zulässig, wenn die Funktion so deklariert ist, dass sie eine Menge zurückgibt. Die Standardannahme ist 1000 Zeilen.

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

Die SET Klausel bewirkt, dass der angegebene Konfigurationsparameter auf den angegebenen Wert gesetzt wird, wenn die Funktion aufgerufen wird, und dann auf seinen vorherigen Wert zurückgesetzt wird, wenn die Funktion beendet wird. SET FROM CURRENTspeichert den Wert des Parameters, der bei der Ausführung aktuell CREATE FUNCTION ist, als den Wert, der bei Eingabe der Funktion angewendet werden soll.

AS 'definition'

Eine Zeichenkettenkonstante, die die Funktion definiert. Die Bedeutung hängt von der Sprache ab. Bei einer SQL-language Funktion bilden die SQL-Anweisungen den Funktionskörper.

RETURN expression

Definiert den Funktionskörper anhand der SQL-standard Syntax für eine Funktion, die einen einzelnen Ausdruck zurückgibt. Dies ist eine Alternative zur Form einer Zeichenkettenkonstante.

BEGIN ATOMIC statement; [ ... ] END

Definiert den Funktionskörper mithilfe der SQL-standard Syntax. Der Hauptteil besteht aus einer oder mehreren SQL-Anweisungen. Dieses Formular ist nur gültig fürLANGUAGE sql. Die Anweisungen in einem Atomkörper werden als Abhängigkeiten der Funktion verfolgt. Beispielsweise kann eine Tabelle, auf die im Hauptteil verwiesen wird, nicht gelöscht werden, ohne dass auch die Funktion gelöscht oder verwendet wirdDROP ... CASCADE.

Hinweise

Verwenden Sie die DROP FUNCTION Anweisung, um eine Funktion zu entfernen. Sie können einer Funktion auch mit und Rechte gewähren GRANT und entziehen REVOKE (z. B.REVOKE ALL ON FUNCTION).

Jede Funktion, die Daten in Tabellen liest oder ändert, unterliegt demselben Transaktions- und Parallelitätsverhalten wie die entsprechenden SQL-Anweisungen, die direkt ausgeführt werden. Funktionen, die deklariert sind IMMUTABLE oder STABLE dürfen die Datenbank nicht ändern.

Um die Definition einer vorhandenen Funktion zu aktualisieren, verwenden SieCREATE OR REPLACE FUNCTION. Sie können die Argumenttypen oder den Rückgabetyp einer Funktion auf diese Weise nicht ändern. Stattdessen müssen Sie die Funktion löschen und neu erstellen.

Um eine Funktion umzubenennen, ihren Besitzer zu ändern oder sie in ein anderes Schema zu verschieben, verwenden SieALTER FUNCTION. Um andere Attribute zu ändern, verwenden Sie sie CREATE OR REPLACE FUNCTION mit den gewünschten Änderungen. Weitere Informationen finden Sie unter ALTER FUNCTION.

Das Überladen von Funktionen wird unterstützt: Sie können mehrere Funktionen mit demselben Namen definieren, solange sich ihre Eingabeargumenttypen unterscheiden. Eine benutzerdefinierte Funktion kann auch andere Funktionen aufrufen und eine integrierte Funktion mit demselben Namen und denselben Argumenttypen abbilden.

Bei einer Funktion, die eine Menge (SETOFoderRETURNS TABLE) zurückgibt, deren Hauptteil mehr als eine Anweisung enthält, wird nur das Ergebnis der letzten Anweisung zurückgegeben. Die Funktion führt weiterhin die früheren Anweisungen aus, verwirft jedoch ihre Ergebnisse. Dies ist das Standardverhalten für SQL-language Funktionen. Strukturieren Sie die Funktion so, dass ihre endgültige Anweisung die vollständige Ergebnismenge ergibt.

Eine Funktion, die Mengen zurückgibt, garantiert keine bestimmte Zeilenreihenfolge. Um die Zeilenreihenfolge zu steuern, fügen Sie der Abfrage eine ORDER BY Klausel hinzu.

Überlegungen

Die folgenden CREATE FUNCTION Funktionen geben den angezeigten Fehler zurück.

LEAKPROOF

Gibt den Fehler zurückonly superuser can define a leakproof function. NOT LEAKPROOF(Standard) wird akzeptiert.

TRANSFORM FOR TYPE

Gibt den Fehler zurücktransform for type type language "sql" does not exist.

SUPPORT(Funktion zur Unterstützung von Planern)

Gibt den Fehler zurückfunction name(internal) does not exist.

User-defined zusammengesetzte Typen (CREATE TYPE ... AS), einschließlich Funktionen, die einen zusammengesetzten Typ zurückgeben

Gibt den Fehler zurückunsupported statement: CompositeType.

Aurora DSQL unterstützt nichtCREATE PROCEDURE, was mit dem Fehler PROCEDURE is not supported fehlschlägt.

Das WINDOW Attribut wird syntaktisch akzeptiert, ist aber für Funktionen nicht nützlich. SQL-language Vermeiden Sie die Verwendung dieses Attributs.

Beispiele

Erstellen Sie eine einfache SQL-Funktion, die zwei ganze Zahlen addiert und dabei einen konstanten Zeichenkettenkörper verwendet:

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

Erstellen Sie dieselbe Funktion mit dem SQL-standard RETURN Hauptteil und den benannten Argumenten:

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

Erstellen Sie eine Funktion, die eine Reihe von Zeilen zurückgibt, indem Sie RETURNS TABLE einen BEGIN ATOMIC Hauptteil verwenden:

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;

Erstellen Sie eine Funktion, die mit den Rechten ihres Besitzers ausgeführt wird, und legt einen Konfigurationsparameter für die Dauer des Aufrufs fest:

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

Kompatibilität

Ein CREATE FUNCTION Befehl ist im SQL-Standard definiert. Die PostgreSQL-Implementierung kann auf kompatible Weise verwendet werden, hat jedoch viele Erweiterungen. Umgekehrt spezifiziert der SQL-Standard eine Reihe optionaler Funktionen, die in PostgreSQL nicht implementiert sind.

Im Folgenden sind wichtige Kompatibilitätsprobleme aufgeführt:

• OR REPLACEist eine PostgreSQL-Erweiterung.

• argmodeKann aus Kompatibilitätsgründen mit einigen anderen Datenbanksystemen entweder vorher oder nachher geschrieben werden. argname Aber nur der erste Weg ist standardkonform.

• Für Parameter-Standardwerte spezifiziert der SQL-Standard nur die Syntax mit dem DEFAULT Schlüsselwort. Die Syntax mit = wird in T-SQL und Firebird verwendet.

• Der SETOF Modifikator ist eine PostgreSQL-Erweiterung.

• Nur SQL ist als Sprache standardisiert.

• Alle anderen Attribute außer CALLED ON NULL INPUT und RETURNS NULL ON NULL INPUT sind nicht standardisiert.

• Für den LANGUAGE sql Funktionsumfang spezifiziert der SQL-Standard nur das sql_body Formular.

Einfache LANGUAGE sql Funktionen können so geschrieben werden, dass sie sowohl standardkonform als auch auf andere Implementierungen übertragbar sind. Komplexere Funktionen, die erweiterte Funktionen, Optimierungsattribute oder andere Sprachen verwenden, werden zwangsläufig in erheblichem Maße spezifisch für PostgreSQL sein.