CREATE [OR REPLACE] FUNCTION
Mithilfe des Befehls CREATE FUNCTION können Sie eine benutzerdefinierte Funktion erstellen. Mit CREATE OR REPLACE FUNCTION können Sie eine Funktion erstellen oder eine vorhandene Funktion durch eine Funktion mit gleichem Namen mit neuen Objektdateien, einem neuen Rückgabewert, einem neuem Funktionsverhalten oder einer neuen Protokollierungsstufe ersetzen.
Übersicht
CREATE [OR REPLACE] FUNCTION function_name(argument_types)
RETURNS return_type LANGUAGE CPP PARAMETER STYLE NPSGENERIC
[FENCED | NOT FENCED] [DETERMINISTIC | NOT DETERMINISTIC]
[RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT]
[MAXIMUM MEMORY mem] [LOGMASK <MASK>]
[NO DEPENDENCIES| DEPENDENCIES deplibs]
[API VERSION [ 1 | 2 ]]
[ENVIRONMENT 'name' = 'value', 'name2' = 'value2']
[TABLE, TABLE FINAL ALLOWED | TABLE ALLOWED | TABLE FINAL ALLOWED]
[PARALLEL ALLOWED | PARALLEL NOT ALLOWED]
[EXTERNAL CLASS NAME 'class_name']
[EXTERNAL HOST OBJECT 'host_object_filename']
[EXTERNAL SPU OBJECT 'SPU_object_filename']
Eingaben
Eingabe | Beschreibung |
---|---|
FUNCTION_NAME | Gibt den Namen der Funktion an, die Sie erstellen wollen. Hierbei handelt es sich um die SQL-Kennung, die verwendet wird, um die Funktion in einem SQL-Ausdruck aufzurufen. Der Name muss den Benennungskriterien für Schlüsselwörter und Bezeichner entsprechen, die im IBM Netezza Database User's Guide beschrieben sind. Wenn die Funktion bereits vorhanden ist, können Sie den Namen mit dem Befehl CREATE OR REPLACE nicht ändern. Auf Systemen, die mehrere Schemas unterstützen, können Sie einen Namen im Format 'Schema.Funktion' angeben, um eine Funktion in einem anderen Schema der aktuellen Datenbank zu erstellen. Die Erstellung einer Funktion in einer anderen Datenbank ist nicht möglich. |
argument_types | Gibt eine Liste vollständig angegebener Funktionsargumentdatentypen an. Alle Netezza Performance Server werden unterstützt. Zeichenfolgen müssen entweder eine Größenangabe oder die Angabe ANY für generische Größen umfassen. Bei numerischen Typen (NUMERIC) müssen Sie die Genauigkeit und die Anzahl der Kommastellen oder ANY für generische Größen angeben. Sie können auch den VARARGS-Wert angeben, um ein Aggregat mit variablen Argumenten zu erstellen, bei dem Benutzer bis zu 64 Werte eines beliebigen unterstützten Datentyps eingeben können. VARARGS ist ein Wert, der sich mit anderen Werten gegenseitig ausschließt; Sie können in der Liste keine anderen Argumente angeben. Sie können die Argumentliste oder Größen nicht ändern. Sie können VARARGS aus der Argumentliste entfernen oder es einer ansonsten leeren Argumentliste hinzufügen. Die Argumentliste kann mit diesem Befehl nicht geändert werden. Wenn die Funktion bereits vorhanden ist, können Sie die Argumenttypliste mit dem Befehl CREATE OR REPLACE nicht ändern. Sie können CREATE OR REPLACE außerdem verwenden, um bestimmte Aspekte der UDF-Argumenttypen zu ändern. Hierzu gehören beispielsweise die Größe einer Zeichenfolge oder die Genauigkeit und die Anzahl der Kommastellen eines numerischen Werts. |
RETURNS Rückgabetyp | Der Wert von 'Rückgabetyp' ist ein vollständig angegebenes Argument und ein vollständig angegebener Typ. Er folgt denselben Regeln wie 'Argumenttypen'. Wenn die API VERSION 2 ist, kann der return_type auch TABLE(name type, name2 type2, ...) sein oder TABLE(ANY), um eine Tabellenfunktion anzugeben. |
SPRACHE | Gibt die Programmiersprache an, die für die Funktion verwendet wird. Zurzeit wird nur der Standardwert CPP (C++) unterstützt. |
PARAMETER STYLE | Der Standardwert und einzige unterstützte Wert ist zurzeit NPSGENERIC. |
FENCED NOT FENCED |
Gibt an, ob die Funktion in einem separaten Prozess im geschützten Adressraum ausgeführt wird (abgeschirmter Modus). Zum Erstellen einer nicht abgeschirmten Funktion müssen Sie über die Administratorberechtigung für die Abschirmungsaufhebung verfügen. |
[DETERMINISTIC | NOT DETERMINISTIC] | DETERMINISTIC gibt an, dass die UDF eine reine Funktion ist, also eine Funktion, die bei Angabe derselben Argumentwerte immer denselben Wert zurückgibt und keine Nebeneffekte hat. Das System kann mehrere Instanzen einer deterministischen UDF, die identische Argumentlisten aufweisen, als Kandidaten für CSE (Common Subexpression Elimination)
berücksichtigen. Der Standardwert ist DETERMINISTIC. Ist eine Funktion als DETERMINISTIC definiert, wird sie nicht einmal pro Zeile, sondern einmal bei der Anweisungsvorbereitung
aufgerufen, wenn eine der folgenden Bedingungen zutrifft:
Ein Argument wird als Konstantenargument bezeichnet, wenn es sich um ein SQL-Literal, das Ergebnis einer UDF oder integrierten Funktion handelt, die nicht einmal pro Zeile, sondern einmal bei der Anweisungsvorbereitung ausgewertet wird. |
[RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT] | RETURNS NULL ON NULL INPUT gibt an, dass die Funktion immer NULL zurückgibt, wenn eines ihrer Argumente NULL ist. Wenn Sie diesen Parameter angeben, wird die Funktion nicht ausgeführt, wenn NULL-Argumente vorhanden sind. Stattdessen wird automatisch ein NULL-Ergebnis angenommen. Mit der Standardeinstellung CALLED ON NULL INPUT wird angegeben, dass die Funktion normal aufgerufen wird, wenn Argumente der Funktion NULL sind. In diesem Fall liegt es im Verantwortungsbereich des Funktionserstellers, die Daten bei Bedarf auf NULL-Werte zu überprüfen und entsprechend zu reagieren. Weitere Informationen zu den Auswirkungen dieser Einstellung auf die Abfrageoptimierung finden Sie unter Netezza Performance Server und UDX-Aufrufe. |
MAXIMUM MEMORY | Gibt die potenziell mögliche Speicherbelegung durch die Funktion an. Der Größenwert kann ein leerer Wert oder ein numerischer Wert mit einem der Buchstaben 'b' (Byte), 'k' (Kilobyte), 'm' (Megabyte) oder 'g' (Gigabyte) sein. Beispiele für gültige Werte sind '0', '1k', '100k', '1g' oder '10m'. Der Standardwert ist 0. |
LOGMASK Maske | Gibt die Protokollierungssteuerungsebene für die Funktion an. Gültige Werte sind NONE, DEBUG und TRACE oder eine durch Kommas getrennte Kombination aus DEBUG und TRACE. |
DEPENDENCIES Abhängige_Bibliotheken | Gibt für die UDX eine optionale Liste von Abhängigkeiten zu benutzerdefinierten gemeinsam genutzten Bibliotheken an. Sie können einen einzelnen Bibliotheksnamen oder eine durch Kommas getrennte Liste mit Bibliotheksnamen angeben. |
API VERSION [1 | 2] | Gibt die Version der UDX-Schnittstelle an, die vom Aggregat verwendet wird. Die Angabe für API VERSION muss der kompilierten Version der Objektdateien für den Host und die SPU entsprechen. Der Standardwert beträgt 1. Wenn Sie kompilierte Objekte der Version 2 einbeziehen, müssen Sie API VERSION 2 angeben. |
ENVIRONMENT | Gibt ein Name/Wert-Paar an, das bei der Ausführung der Funktion verfügbar ist. Sie können mehrere, durch Kommas getrennte Name/Wert-Paare angeben. Zum Ändern eines vorhandenen Sets mit mindestens einem Umgebungspaar müssen Sie alle Umgebungseinstellungen angeben. Der Änderungsbefehl ersetzt die aktuelle Liste durch die im Befehl ALTER angegebene Liste. |
TABLE, TABLE FINAL ALLOWED TABLE ALLOWED TABLE FINAL ALLOWED |
Gibt die Optionen an, mit denen gesteuert wird, wie die benutzerdefinierte Tabellenfunktion aufgerufen werden kann.
FINAL bedeutet, dass die Tabellenfunktion nach Verarbeitung aller Eingabezeilen aufgerufen wird, sodass die Ausgabe eine größere Anzahl von Zeilen enthalten kann. |
PARALLEL ALLOWED | Gibt an, dass eine benutzerdefinierte Tabellenfunktion abhängig von der Entscheidung des Optimierungsprogramms entweder auf dem Host oder der SPU aufgerufen werden kann. |
PARALLEL NOT ALLOWED | Gibt an, dass die Tabellenfunktion abhängig von der Entscheidung des Optimierungsprogramms immer auf dem Host oder einer ausgewählten SPU aufgerufen wird. |
EXTERNAL CLASS NAME 'Klassenname' | Gibt den Namen der C++-Klasse an, die die Funktion implementiert. Die Klasse muss sich aus der Basisklasse 'Udf' ableiten lassen und eine statische Methode implementieren, die eine Instanz der Klasse instanziiert. |
EXTERNAL HOST OBJECT 'Hostobjektdateiname' | Gibt den Namen des Pfads zum kompilierten Objekt für die Hostausführung an. |
EXTERNAL SPU OBJECT 'SPU-Objektdateiname' | Gibt den Pfadnamen für die kompilierte Objektdatei der Linux® SPU an. Geben Sie das kompilierte Objekt spu10 für Rev10 SPUs auf IBM® Netezza® 100 und Netezza 100 Modellen an. |
Ausgaben
Ausgabe | Beschreibung |
---|---|
CREATE FUNCTION | Die Nachricht, die das System zurückgibt, wenn der Befehl erfolgreich ist. |
ERROR: User 'username' is not allowed to create/drop functions. | Das System gibt diese Nachricht zurück, wenn Ihr Benutzerkonto nicht über die Funktionserstellungsberechtigung verfügt. |
ERROR: Synonym 'name' already exists | Das System gibt diese Nachricht zurück, wenn ein Synonym mit dem Namen vorhanden ist, den Sie für die Funktion angegeben haben. |
ERROR: function name already exists with the same signature | Dieser Fehler wird zurückgegeben, wenn Sie einen Befehl CREATE FUNCTION absetzen und eine gleichnamige Funktion mit derselben Argumenttypliste in der Datenbank bereits vorhanden ist. Verwenden Sie stattdessen CREATE OR REPLACE FUNCTION. |
ERROR: function name already exists with the same signature | Das System gibt diese Nachricht zurück, wenn eine Funktion mit dem Namen vorhanden ist, den Sie für die Funktion angegeben haben. |
NOTICE: FunctionCreate: existing UDX name(argument_types) differs in size of string/numeric arguments | Diese Nachricht gibt an, dass eine UDX mit diesem Namen vorhanden ist, bei der jedoch für Zeichenfolgeargumente oder numerische Argumente andere Größen angegeben wurden. Wenn Sie die Funktionssignatur nicht ändern wollten, sollten Sie die Signatur prüfen und sicherstellen, dass sie korrekt ist. |
ERROR: lookupLibrary: library libname does not exist | Die Nachricht, die vom System zurückgegeben wird, wenn es die als Abhängigkeit angegebene, benutzerdefinierte gemeinsam genutzte Bibliothek nicht finden kann. |
ERROR: ProcedureCreate: Can't use version 2 features without specifying API VERSION 2 for udx_name | Die Nachricht gibt an, dass Sie für den SQL-Befehl zwar Optionen der Version 2 angegeben haben, die API-Version 2 im SQL-Befehl jedoch nicht angegeben haben. |
ERROR: Version mismatch for function udx_name. Specified version 2, but provided version 1 object file | Für die kompilierten Objektdateien wird die Unterstützung von API-Version 1 verwendet, der SQL-Befehl verwendet jedoch die Funktionalität von Version 2. Sie müssen entweder kompilierte Objekte der Version 2 erstellen oder im Befehl die Optionen entfernen, die Funktionen der Version 2 angeben. |
ERROR: Version mismatch for function udx_name. Specified version 1, but provided version 2 object file | Für die kompilierten Objektdateien wird die Unterstützung von API-Version 2 verwendet, der SQL-Befehl verwendet jedoch die Funktionalität von Version 1. Sie müssen entweder kompilierte Objekte der Version 1 angeben oder den Befehl ALTER so ändern, dass er die Syntax von Version 2 verwendet. |
ERROR: Environment names can't be empty | Der Wert für Name einer Umgebungseinstellung darf keine leere Zeichenfolge sein. |
ERROR: type 'type' is not yet defined | Der angegebene Rückgabetyp ist kein bekannter Datentyp von Netezza Performance Server. |
Beschreibung
Wenn Sie eine Funktion erstellen, sollten Sie beachten, dass die Signatur (d. h. der Name und die Argumenttypliste) der Funktion in der zugehörigen Datenbank eindeutig sein muss. Keine andere benutzerdefinierte Funktion bzw. kein anderes benutzerdefiniertes Aggregat darf innerhalb derselben Datenbank denselben Namen und dieselbe Argumenttypliste aufweisen.
Die Änderung des Funktionsnamens oder der Argumenttypliste ist mit dem Befehl CREATE OR REPLACE nicht möglich. Sie können einige Aspekte der Argumenttypen ändern; Sie können beispielsweise die Größe einer Zeichenfolge oder die Genauigkeit und die Anzahl der Kommastellen eines numerischen Werts ändern. Zur Änderung eines Funktionsnamens und/oder einer Argumenttypliste müssen Sie die vorhandene Funktion löschen und anschließend eine Funktion mit dem gewünschten neuen Namen und/oder der gewünschten Argumenttypliste erstellen.
Eine benutzerdefinierte Funktion, die momentan in einer aktiven Abfrage verwendet wird, kann nicht ersetzt werden. Nachdem die aktive Abfragetransaktion abgeschlossen ist, verarbeitet das Netezza Performance Server den Befehl CREATE OR REPLACE FUNCTION, um die Funktion zu aktualisieren.
Zugriffsrechte erforderlich
Bei Systemen, die mehrere Schemas unterstützen, müssen Sie der Datenbankadministrator oder der Eigner der aktuellen Datenbank bzw. des aktuellen Schemas sein. Andere Benutzer müssen über die Funktionserstellungsberechtigung verfügen, um den Befehl CREATE FUNCTION verwenden zu können. Wenn Sie mit CREATE OR REPLACE FUNCTION eine UDF ändern, müssen Sie über die Funktionserstellungsberechtigung und die Änderungsberechtigung für die UDF verfügen, um sie ändern zu können. Zum Erstellen einer nicht abgeschirmten Funktion müssen Sie über die Administratorberechtigung für die Abschirmungsaufhebung verfügen.
Allgemeine Aufgaben
Mithilfe des Befehls CREATE FUNCTION können Sie eine neue benutzerdefinierte Funktion erstellen und ihr Eigner werden. Sie müssen die C++-Dateien der Funktion erstellen und sie mit ' nzudxcompile ' kompilieren, bevor Sie diesen Befehl verwenden können, um die Funktion im Netezza Performance Server zu registrieren. Die Funktion wird in der aktuellen Datenbank als Objekt definiert.
Verwendung
- So erstellen Sie die Beispielfunktion ' CustomerName (beschrieben in Benutzerdefinierte Funktionen erstellen):
MYDB.SCHEMA(MYUSER)=> CREATE FUNCTION CustomerName(varchar(64000)) RETURNS int4 LANGUAGE CPP PARAMETER STYLE npsgeneric EXTERNAL CLASS NAME 'CCustomerName' EXTERNAL HOST OBJECT '/home/nz/udx_files/customername.o_x86' EXTERNAL SPU OBJECT '/home/nz/udx_files/customername.o_spu10'