実装のガイドライン - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL外部ルーチン プログラミング

Product
Advanced SQL Engine
Teradata Database
Release Number
17.05
17.00
Published
2020年6月
Language
日本語
Last Update
2021-03-30
dita:mapPath
ja-JP/qwr1571437338192.ditamap
dita:ditavalPath
ja-JP/qwr1571437338192.ditaval
dita:id
B035-1147
Product Category
Software
Teradata Vantage

以下に示すのは、入力引数として派生テーブルからの列を使用して呼び出すテーブルUDFを実装するJavaメソッドを書くための基本ステップです。

  1. CREATE FUNCTION文でパラメータを指定している順序で、パラメータ リストを定義します。

    詳細については、テーブルUDFのメソッド シグネチャを参照してください。

  2. テーブルUDFが動的な結果行指定で定義される場合は、Tbl.getColDef()を呼び出し、メソッドが戻さなければならない結果の行の引数の実数とデータ型を取得します。
  3. Tbl.getPhase()またはTbl.getPhaseEx()_を呼び出して、戻り値がTbl.TBL_MODE_VARYであることを検証します。この戻り値になっていれば、テーブルUDFは入力引数として派生テーブルからの列を使用して呼び出されたことになります。
  4. Tbl.getPhase()またはTbl.getPhaseEx()からphase引数の中に戻される値を使って、Teradata Databaseがメソッドを呼び出すフェーズと、取るべきアクションを判別します。
    メソッドの動作
    Tbl.TBL_PRE_INIT 対象になるすべての行の初めに呼び出されます。メソッドの入力引数には、最初のセットのデータが含まれます。

    このフェーズでは、メソッドが総合的なグローバル コンテキストを設定する機会を持つことになりますが、結果行は作成しません。

    メソッドはTBL_INITフェーズに進みます。

    Tbl.TBL_INIT Tbl.allocCtx()を呼び出して、関数コンテキストを初期化し、必要に応じてメソッドのローカルな反復実行間のデータ用のスクラッチパッドとして使用できます。

    メソッドの入力引数には、最初のセットのデータが含まれます。

    このフェーズでは、メソッドは結果行を作成しません。

    メソッドはTBL_BUILDフェーズに進みます。

    Tbl.TBL_BUILD 以下のいずれかのアクションを実行します。
    • メソッドに作成する行があれば、非NULLの入力値を含む各出力引数を完成させることで、出力行を作成します。

      メソッドはTBL_BUILDフェーズのままです。

    • メソッドに作成する行がなければ、SQLExceptionをスローし、SQLStateフィールドを"02000"に設定してデータがないことを示します。

      メソッドはTBL_FINIフェーズに進みます。

    Tbl.getPhaseEx()を使用すると、指定したオプションに応じて、以下のアクションが実行されます。

    • TBL_NEWROWオプションを設定すると、TBL_BUILDフェーズの新しい行を指定して関数を呼び出します。
    • TBL_NEWROWEOFオプションとEOFを設定すると、TBL_BUILDフェーズの新しい行を指定してテーブル関数を呼び出します。
    • TBL_LASTROWオプションを設定すると、TBL_BUILD_EOFフェーズに進む最後のデータのセットに渡されるまで、この関数はTBL_BUILDフェーズに維持されます。
    Tbl.TBL_BUILD_EOF

    (この値を返すのはgetPhaseEx()のみ)

    AMP上の最新の入力行が渡された後で呼び出されます。このUDFは、フェーズがTBL_BUILDの時に、前回の呼び出しの間にメモリに集積されたもののサマリー行を出力することがあります。このメソッドは、以下のいずれかのアクションを実行します。
    • メソッドに作成する行があれば、非NULLの入力値を含む各出力引数を完成させることで、出力行を作成します。

      メソッドはTbl.TBL_BUILD_EOFフェーズのままです。

    • メソッドに作成する行がなければ、SQLExceptionをスローし、SQLStateフィールドを"02000"に設定してデータがないことを示します。

      メソッドはTbl.TBL_ENDフェーズに進みます。

    Tbl.TBL_FINI 次に現れ得るデータのセットの準備として、スクラッチパッドのクリアなどのあらゆる初期化処理を実行できます。

    変数入力データがさらにある場合、メソッドはTbl.TBL_INITフェーズに戻ります。そうでない場合、メソッドはTBL_ENDフェーズに進みます。

    Tbl.TBL_END 処理の完了に関して、外部へのあらゆる必要な通知を行えます。

    メソッドは、このフェーズから戻った後にTeradata Databaseから再度呼び出されることはありません。

    Tbl.TBL_ABORT アボートされます。メソッドはこのフェーズでいつでも呼び出されることがありますが、このフェーズに入るのは、テーブル関数の1つのコピーがTbl.abort()を呼び出した場合に限られます。ユーザーによるアボートなど、外的な理由によるメソッドのアボートでは、このフェーズに入りません。
  5. メソッドがエラーを検出した場合は、SQLExceptionをスローします。詳細は、例外処理を参照してください。

一般に、次に示す段階のローの状態を把握する必要があります。

  • TBL_PRE_INITフェーズで、最初の行が渡されるとき。
  • TBL_BUILD フェーズでSQLState フィールドの値を示して、行を返すとき。
  • 新しい行が必要なとき。Tbl.getPhaseEx()のTBL_NEWROWまたはTBL_NEWROWEOFオプションを使用すると、これを定義できます。
  • ファイルの終端を検出したとき。Tbl.getPhaseEx()のTBL_LASTROWを使用すると、これを判断できます。