CREATE [OR REPLACE] AGGREGATE

CREATE AGGREGATE コマンドは、ユーザー定義集約を作成するために使用します。 CREATE OR REPLACE AGGREGATE は、集約を作成するか、既存の集約を新しいオブジェクト・ファイル、状態、戻り値、メモリー使用量、またはロギング・レベルで更新します。

概要

ユーザー定義集約を作成するための構文
CREATE [OR REPLACE] AGGREGATE aggregate_name(argument_types)
RETURNS return_type STATE (state_types)
LANGUAGE CPP PARAMETER STYLE NPSGENERIC [FENCED | NOT FENCED]
[MAXIMUM MEMORY mem ] [LOGMASK mask]
[NO DEPENDENCIES| DEPENDENCIES deplibs]
[ TYPE ANY | ANALYTIC | GROUPED] [API VERSION [1 | 2]]
[ENVIRONMENT 'name'='value', 'name'='value']
[EXTERNAL CLASS NAME 'class_name']
[EXTERNAL HOST OBJECT 'host_object_filename']
[EXTERNAL SPU OBJECT 'SPU_object_filename']

入力

CREATE [OR REPLACE] AGGREGATE コマンドの入力は以下のとおりです。
表 1. CREATE [OR REPLACE] AGGREGATE の入力
入力 説明
AGGREGATE_NAME 作成する集約の名前を指定します。 これが、この集約を SQL 式で呼び出すときに使用する SQL ID です。

集約が既存の場合に、CREATE OR REPLACE コマンドを使用して名前を変更することはできません。

複数のスキーマがサポートされるシステムの場合は、schema.aggregate の形式で名前を指定して、現行データベースの別のスキーマで集約を作成することができます。 別のデータベースに集約を作成することはできません。

引数タイプ 集約の完全指定の引数データ型のリストを指定します。 Netezza Performance Serverのデータ型はすべてサポートされています。 ストリングには、サイズまたは ANY (ジェネリック・サイズの場合) を含める必要があります。 NUMERIC 型には、精度と位取り、または ANY (ジェネリック・サイズの場合) を含める必要があります。

VARARGS 値を指定して、可変引数の集約を作成することもできます。その場合、ユーザーは、サポートされる任意のデータ型の値を 64 個まで入力できます。 VARARGS は、相互排他的な値です。つまり、VARARGS を指定する場合、リストに他の引数を指定することはできません。

集約が既存の場合に、CREATE OR REPLACE コマンドを使用して引数型リストを変更することはできません。 UDA の引数型の内容は変更できます。例えば、ストリングのサイズ、数値の精度と位取りなどを変更できます。 引数リストから VARARGS を削除したり、VARARGS 以外は含まれていない引数リストに VARARGS を追加したりすることもできます。

RETURNSreturn_type 集約の戻り値を、完全指定の 1 つの引数および型として指定します。 Netezza Performance Serverのデータ型はすべてサポートされています。 ストリングにはサイズを含め、NUMERIC 型には精度および位取りを含める必要があります。
ステート・タイプ 完全指定の状態のデータ型のリストを指定します。これを空にすることはできません。 Netezza Performance Serverのデータ型はすべてサポートされています。 ストリングにはサイズを含め、NUMERIC 型には精度および位取りを含める必要があります。

これらのデータ項目は、集約処理のために実行されるアキュムレーターの役割を果たします。 この集約状態は、さまざまな効率上の理由から、Netezza Performance Serverによって集約実装クラスの内部状態の外部で維持されます。

言語 集約に使用されるプログラミング言語を指定します。 デフォルトは CPP (C++) で、これ以外の値は現在サポートされていません。
PARAMETER STYLE 集約のパラメーター・スタイルを指定します。 デフォルトは NPSGENERIC で、これ以外の値は無効です。
隔離

NOT FENCED

保護されたアドレス・スペースで別のプロセスとして集約を実行する (fenced モード) かどうかを指定します。 unfenced 集約を作成するには、Unfence 管理権限が必要です。
MAXIMUM MEMORY 集約の想定メモリー使用量の指標を指定します。 サイズ値は、空の値にするか、数値と文字 b (バイト)、k (キロバイト)、m (メガバイト)、または g (ギガバイト) という形式の値にすることができます。 例えば、「0」、「1k」、「100k」、「1g」、「10m」は有効な値です。 デフォルトは 0 です。
LOGMASKマスク 集約のロギング制御レベルを指定します。 有効な値は、NONE、DEBUG、および TRACE、または DEBUG と TRACE をコンマで区切ってつなげたものです。
ディペンデンス・デプリブズ UDX に関するユーザー定義共有ライブラリーの依存関係のリスト (オプション) を指定します。 ライブラリー名を 1 つ指定することも、複数のライブラリー名のコンマ区切りリストを指定することもできます。
NO DEPENDENCIES UDX に関する依存関係が存在しないことを指定します。DEPENDENCIES deplibs を省略した場合、これがデフォルトです。 このオプションを使用して、UDX に関して以前宣言された依存関係をクリアすることができます。
タイプ UDA を呼び出すことができるコンテキスト。 ウィンドウ集約にのみ UDA を許可する場合は ANALYTIC を指定します。 グループ集約または総集約に UDA を許可する場合は GROUPED を指定します。 また、両方のコンテキストで UDA を許可する場合は ANY を指定します。 ウィンドウの詳細については、『IBM NetezzaDatabase User's Guide』を参照してください。
API VERSION [1 | 2] 集約によって使用される UDX インターフェースのバージョンを指定します。 API VERSION は、ホストおよび SPU 用のオブジェクト・ファイルのコンパイル・バージョンと一致する必要があります。 デフォルトは 1 です。 バージョン2のコンパイル済みオブジェクトを含める場合は、API VERSION 2を指定する必要があります。
ENVIRONMENT 実行時に集約で使用できる名前値ペアを指定します。 複数の名前値ペアをコンマで区切って指定することができます。

1 つ以上の環境ペアから成る既存のセットを置き換える場合は、すべての環境設定を指定する必要があります。 つまり、このコマンドは、CREATE OR REPLACE コマンドに指定されたリストで現行のリストを置き換えます。

EXTERNAL CLASS NAME'クラス名' 集約を実装している C++ クラスの名前を指定します。 このクラスは、Uda 基本クラスから派生したものでなければならず、クラスのインスタンスをインスタンス化する静的メソッドを実装している必要があります。
EXTERNAL HOST OBJECT'host_object_filename' ホスト実行用のコンパイル済みオブジェクトのパス名を指定します。
EXTERNAL SPU OBJECT'SPU_object_filename' Linux®SPUのコンパイル済みオブジェクトファイルのパス名を指定します。 IBM® Netezza® 100およびNetezza 100モデルのRev10SPUには、spu10コンパイル済みオブジェクトを指定してください。

出力

CREATE [OR REPLACE] AGGREGATE コマンドの出力は以下のとおりです。
表 2. CREATE [OR REPLACE] AGGREGATE 出力
出力 説明
CREATE AGGREGATE コマンドが成功した場合にシステムが返すメッセージです。
ERROR: User 'username' is not allowed to create/drop aggregates. ユーザー・アカウントに Create Aggregate 特権がない場合、このメッセージがシステムから返されます。
ERROR: Synonym 'name' already exists 集約に指定した名前のシノニムが存在する場合、このメッセージがシステムから返されます。
ERROR: AggregateCreate: aggregate name already exists with the same arguments CREATE AGGREGATE コマンドを発行した場合に、同じ名前と引数型リストを持つ集約がデータベースに存在すると、このエラーが返されます。 代わりに、CREATE OR REPLACE AGGREGATE を使用してください。
NOTICE: AggregateCreate: existing UDX name(argument_types) differs in size of string/numeric arguments このメッセージは、同じ名前の UDX が存在するが、そのサイズが、ストリングまたは数値の引数に対して指定されたサイズではないことを示します。 集約シグニチャーの変更が意図したものではない場合は、シグニチャーを調べて正しいか確認してください。
ERROR: lookupLibrary: library libname does not exist 依存関係として指定したユーザー定義共有ライブラリーが見つからなかった場合に、システムから返されるメッセージです。
ERROR: Version mismatch for function udx_name. Specified version 2, but provided version 1 object file コンパイル済みオブジェクト・ファイルでは API バージョン 1 のサポートが使用されていますが、SQL コマンドではバージョン 2 の機能が使用されています。 バージョン 2 のコンパイル済みオブジェクトを作成するか、バージョン 2 の機能を指定した CREATE コマンドのオプションを除去する必要があります。
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データ型ではありません。

説明

集約を作成する場合、単一のスキーマがサポートされるシステムでは、集約シグニチャー (つまり、集約の名前と引数型リスト) はデータベース内で固有でなければなりません。 複数のスキーマがデータベースでサポートされるシステムでは、シグニチャーはスキーマ内で固有でなければなりません。 同じデータベースまたはスキーマ内で他の UDX が同じ名前と引数型リストを持つことはできません。

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

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

必要な特権

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

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

共通タスク

CREATE AGGREGATE コマンドは、新規のユーザー定義集約を作成し、その所有者になるために使用します。 このコマンドを使用してNetezza Performance Serverシステムにアグリゲートを登録する前に、'nzudxcompile使用してアグリゲート C++ ファイルを作成し、コンパイルする必要があります。

Netezza Performance Serverには、アグリゲートで使用される文字列フィールドを処理するための特別な処理があります。 使用する集約が 512 バイトより長いストリング型を戻す場合は、状態に 255 バイトより大きいストリング型が 1 つ存在するか、合計すると 255 バイトより長くなる複数のストリング型が存在する必要があります。 存在しないと、このコマンドは次のメッセージのようなエラーを返します。
ERROR: Records trailing string space set to 512 is too small: Bump
it up using the environment variable NZ_SPRINGFIELD_SIZE

使用法

以下に使用例を示します。
  • サンプルのPenMaxアグリゲートを作成するには(ユーザー定義アグリゲートの作成で説明):
    MYDB.SCHEMA(MYUSER)=> CREATE AGGREGATE PENMAX(INT4) RETURNS INT4
    STATE (INT4, INT4) LANGUAGE CPP PARAMETER STYLE NPSGENERIC
    EXTERNAL CLASS NAME 'CPenMax'
    EXTERNAL HOST OBJECT '/home/nz/udx_files/penmax.o_x86'
    EXTERNAL SPU OBJECT '/home/nz/udx_files/penmax.o_spu10';