CREATE [OR REPLACE] FUNCTION

CREATE FUNCTION コマンドは、ユーザー定義関数を作成するために使用します。 CREATE OR REPLACE FUNCTION は、関数を作成するか、同じ名前の既存の関数を新しいオブジェクト・ファイル、戻り値、関数動作、またはロギング・レベルで置き換えます。

概要

新しいユーザー定義関数を作成するための構文

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']

入力

CREATE [OR REPLACE] FUNCTION コマンドの入力は以下のとおりです。

表 1. CREATE [OR REPLACE] FUNCTION の入力
入力	説明
`FUNCTION_NAME`	作成する関数の名前を指定します。これが、この関数を SQL 式で呼び出すときに使用する SQL ID です。この名前はIBM NetezzaDatabase User's Guideに記載されているキーワードと識別子の命名基準を満たしている必要があります。関数が既存の場合に、CREATE OR REPLACE コマンドを使用して関数の名前を変更することはできません。複数のスキーマがサポートされるシステムの場合は、schema.function の形式で名前を指定して、現行データベースの別のスキーマで関数を作成することができます。別のデータベースに関数を作成することはできません。
`引数タイプ`	関数の完全指定の引数データ型のリストを指定します。 Netezza Performance Serverのデータ型はすべてサポートされています。ストリングには、サイズまたは ANY (ジェネリック・サイズの場合) を含める必要があります。 NUMERIC 型には、精度と位取り、または ANY (ジェネリック・サイズの場合) を含める必要があります。 VARARGS 値を指定して、可変引数の集約を作成することもできます。その場合、ユーザーは、サポートされる任意のデータ型の値を 64 個まで入力できます。 VARARGS は、相互排他的な値です。つまり、VARARGS を指定する場合、リストに他の引数を指定することはできません。引数のリストおよびサイズは変更できません。引数リストから VARARGS を削除したり、VARARGS 以外は含まれていない引数リストに VARARGS を追加したりすることもできます。このコマンドを使用して引数リストを変更することはできません。関数が既存の場合に、CREATE OR REPLACE コマンドを使用して引数型リストを変更することはできません。 CREATE OR REPLACE を使用して UDF の引数の型の内容を一部変更することはできます。例えば、ストリングのサイズ、数値の精度と位取りなどを変更できます。
RETURNS`return_type`	return_type 値は、完全指定の 1 つの引数および型です。これは、argument_types と同じ規則に従います。 API VERSIONが2の場合、return_typeはTABLE(name type,name2 type2, ...)にもなるまたはTABLE(ANY)でテーブル関数を指定する。
言語	関数に使用されるプログラミング言語を指定します。デフォルトは CPP (C++) で、これ以外の値は現在サポートされていません。
PARAMETER STYLE	デフォルトは NPSGENERIC で、これ以外の値は現在サポートされていません。
隔離 NOT FENCED	保護されたアドレス・スペースで別のプロセスとして関数を実行する (fenced モード) かどうかを指定します。 unfenced 関数を作成するには、Unfence 管理権限が必要です。
[DETERMINISTIC \| NOT DETERMINISTIC]	DETERMINISTIC は、この UDF が、同じ引数値を与えられたときに必ず同じ値を返す、副次作用がない純粋な関数であることを示します。システムは、引数リストが同じ決定論的 UDF の複数のインスタンスを、共通部分式除去 (CSE) の候補と見なす場合があります。デフォルトは DETERMINISTIC です。 DETERMINISTIC の関数は、以下のいずれかが当てはまる場合、1 行ごとに 1 回呼び出されるのではなく、ステートメントの準備時に 1 回呼び出されます。 RETURNS NULL ON NULL INPUT 関数であり、1 つ以上の引数が NULL (リテラル NULL) である。引数がすべて定数である。引数が SQL リテラルである場合、または、1 行ごとに 1 回評価されるのではなくステートメントの準備時に 1 回評価される UDF または組み込み関数の結果である場合、その引数は定数です。
[RETURNS NULL ON NULL INPUT \| CALLED ON NULL INPUT]	RETURNS NULL ON NULL INPUT は、いずれかの引数が NULL の場合に必ず関数が NULL を返すことを示します。このパラメーターを指定すると、NULL の引数が存在する場合に関数は実行されません。代わりに、NULL の結果が自動的に想定されます。 CALLED ON NULL INPUT (デフォルト) は、一部の引数が NULL でも通常どおり関数が呼び出されることを示します。この場合、必要に応じて NULL 値かどうかを検査して適宜対処するのは、関数作成者の責任となります。この設定によるクエリ最適化の効果の詳細については、Netezza Performance Serverクエリ最適化と UDX 呼び出しを参照してください。
MAXIMUM MEMORY	関数の想定メモリー使用量の指標を指定します。サイズ値は、空の値にするか、数値と文字 b (バイト)、k (キロバイト)、m (メガバイト)、または g (ギガバイト) という形式の値にすることができます。例えば、「0」、「1k」、「100k」、「1g」、「10m」は有効な値です。デフォルトは 0 です。
LOGMASK`マスク`	関数のロギング制御レベルを指定します。有効な値は、NONE、DEBUG、および TRACE、または DEBUG と TRACE をコンマで区切ってつなげたものです。
`ディペンデンス・デプリブズ`	UDX に関するユーザー定義共有ライブラリーの依存関係のリスト (オプション) を指定します。ライブラリー名を 1 つ指定することも、複数のライブラリー名のコンマ区切りリストを指定することもできます。
API VERSION [1 \| 2]	集約によって使用される UDX インターフェースのバージョンを指定します。 API VERSION は、ホストおよび SPU 用のオブジェクト・ファイルのコンパイル・バージョンと一致する必要があります。デフォルトは 1 です。バージョン2のコンパイル済みオブジェクトを含める場合は、API VERSION 2を指定する必要があります。
ENVIRONMENT	実行時に関数で使用できる名前値ペアを指定します。複数の名前値ペアをコンマで区切って指定することができます。 1 つ以上の環境ペアから成る既存のセットを変更する場合は、すべての環境設定を指定する必要があります。つまり、ALTER コマンドは、ALTER コマンドに指定されたリストで現行のリストを置き換えます。
TABLE, TABLE FINAL ALLOWED TABLE ALLOWED TABLE FINAL ALLOWED	ユーザー定義表関数の呼び出し方法を制御するオプションを指定します。 TABLE, TABLE FINAL ALLOWED オプションは、TABLE(func())、TABLE WITH FINAL(func()) のどちらを使用しても表関数を呼び出せることを指定します。 TABLE ALLOWED または TABLE FINAL ALLOWED のどちらかを指定して、それらの形式の一方を使用したユーザー定義表関数の呼び出しを許可することもできます。 FINAL は、入力行がすべて処理された後に表関数が呼び出されること、したがって、追加行の出力が可能であることを意味します。
PARALLEL ALLOWED	ユーザー定義表関数が、オプティマイザーの判断に従ってホストでも SPU でも呼び出し可能であることを指定します。
PARALLEL NOT ALLOWED	表関数が、必ず、ホストか、あるいはオプティマイザーの判断により選択された 1 つの SPU で呼び出されることを指定します。
EXTERNAL CLASS NAME`'クラス名`'	関数を実装している C++ クラスの名前を指定します。このクラスは、Udf 基本クラスから派生したものでなければならず、クラスのインスタンスをインスタンス化する静的メソッドを実装している必要があります。
EXTERNAL HOST OBJECT`'host_object_filename`'	ホスト実行用のコンパイル済みオブジェクトのパス名を指定します。
EXTERNAL SPU OBJECT`'SPU_object_filename`'	Linux®SPUのコンパイル済みオブジェクトファイルのパス名を指定します。 IBM® Netezza® 100およびNetezza 100モデルのRev10SPUには、spu10コンパイル済みオブジェクトを指定してください。

出力

CREATE [OR REPLACE] FUNCTION コマンドの出力は以下のとおりです。

表 2. CREATE [OR REPLACE] FUNCTION の出力
出力	説明
`CREATE FUNCTION`	コマンドが成功した場合にシステムが返すメッセージです。
`ERROR: User 'username' is not allowed to create/drop functions.`	ユーザー・アカウントに Create Function 特権がない場合、このメッセージがシステムから返されます。
`ERROR: Synonym 'name' already exists`	関数に指定した名前のシノニムが存在する場合、このメッセージがシステムから返されます。
`ERROR: function name already exists with the same signature`	CREATE FUNCTION コマンドを発行した場合に、同じ名前と引数型リストを持つ関数がデータベースに存在すると、このエラーが返されます。代わりに、CREATE OR REPLACE FUNCTION を使用してください。
`ERROR: function name already exists with the same signature`	関数に指定した名前の関数が存在する場合、このメッセージがシステムから返されます。
`NOTICE: FunctionCreate: existing UDX name(argument_types) differs in size of string/numeric arguments`	このメッセージは、同じ名前の UDX が存在するが、そのサイズが、ストリングまたは数値の引数に対して指定されたサイズではないことを示します。関数シグニチャーの変更が意図したものではない場合は、シグニチャーを調べて正しいか確認してください。
`ERROR: lookupLibrary: library libname does not exist`	依存関係として指定したユーザー定義共有ライブラリーが見つからなかった場合に、システムから返されるメッセージです。
`ERROR: ProcedureCreate: Can't use version 2 features without specifying API VERSION 2 for udx_name`	このメッセージは、ユーザーが SQL コマンドにバージョン 2 のオプションを指定しながら API VERSION 2 と SQL コマンドに指定しなかったことを示します。
`ERROR: Version mismatch for function udx_name. Specified version 2, but provided version 1 object file`	コンパイル済みオブジェクト・ファイルでは API バージョン 1 のサポートが使用されていますが、SQL コマンドではバージョン 2 の機能が使用されています。バージョン 2 のコンパイル済みオブジェクトを作成するか、バージョン 2 の機能を指定したコマンドのオプションを除去する必要があります。
`ERROR: Version mismatch for function udx_name. Specified version 1, but provided version 2 object file`	コンパイル済みオブジェクト・ファイルでは API バージョン 2 のサポートが使用されていますが、SQL コマンドではバージョン 1 の機能が使用されています。バージョン 1 のコンパイル済みオブジェクトを指定するか、バージョン 2 の構文を指定するように ALTER コマンドを変更する必要があります。
`ERROR: Environment names can't be empty`	環境設定の `name` 値を空のストリングにすることはできません。
`ERROR: type 'type' is not yet defined`	指定された戻り値の型が既知のNetezza Performance Serverデータ型ではありません。

説明

関数を作成する場合、関数シグニチャー (つまり、関数の名前と引数型リスト) はデータベース内で固有でなければなりません。同じデータベース内で他のユーザー定義の関数または集約が同じ名前と引数型リストを持つことはできません。

CREATE OR REPLACE コマンドで関数の名前や引数型リストを変更することはできません。引数型の内容は変更できます。例えば、ストリングのサイズ、数値の精度と位取りなどを変更できます。関数の名前、引数型リスト、またはその両方を変更するには、関数をドロップしてから、新しい名前、引数型リスト、またはその両方を指定して関数を作成する必要があります。

アクティブな照会で使用中のユーザー定義関数を置き換えることはできません。アクティブなクエリ・トランザクションが完了すると、Netezza Performance Serverシステムは CREATE OR REPLACE FUNCTION コマンドを処理して関数を更新します。

必要な特権

データベース管理ユーザーであるか、現行のデータベースを所有しているか、複数のスキーマがサポートされるシステムの場合は現行のスキーマを所有している必要があります。その他のユーザーが CREATE FUNCTION コマンドを使用するには、Create Function 特権が必要です。また、CREATE OR REPLACE FUNCTION を使用して UDF を変更するには、その UDF に対する Create Function 特権および Alter 特権が必要です。 unfenced 関数を作成するには、Unfence 管理権限が必要です。

注意:CREATE FUNCTIONコマンドを発行すると、データベースはHOST OBJECTファイルとSPU OBJECTファイルをユーザnzとして処理します。ユーザー nz にはオブジェクト・ファイルに対する読み取り権限と、ルートからオブジェクト・ファイルまでのパスにあるすべてのディレクトリーに対する読み取り権限および実行権限が必要です。

共通タスク

CREATE FUNCTION コマンドは、新規のユーザー定義関数を作成し、その所有者になるために使用します。このコマンドを使用してNetezza Performance Serverシステムに関数を登録する前に、関数 C++ ファイルを作成し、'nzudxcompile使用してコンパイルする必要があります。関数は、現行のデータベースのオブジェクトとして定義されます。

使用法

以下に使用例を示します。

サンプル関数「CustomerName」を作成する（ユーザー定義関数の作成で説明）：

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'