17.00 - 17.05 - RuntimeContractメソッド - Advanced SQL Engine - Teradata Database

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

Product
Advanced SQL Engine
Teradata Database
Release Number
17.00
17.05
Published
2020年6月
Content Type
プログラミング リファレンス
Publication ID
B035-1147-170K-JPN
Language
日本語 (日本)

bytesTransferred

public void  bytesTransferred(long  in, long  out)
   throws SQLException
パラメータ名 定義
in 外部サーバーからTeradata Databaseに転送されるバイト数。
out Teradata Databaseから外部サーバーに転送されるバイト数。

テーブル演算子によってTeradata Databaseと外部サーバー間で転送されるバイト数を記録します。このルーチンは、テーブル演算子によってAMP vprocでのみ呼び出すことができます。

complete

public void  complete()

Teradataパーサーによる契約の成立。

disableCoGroup

public void  disableCoGroup()

複数の入力ストリームを処理するテーブル演算子のcogroup機能を無効にします。

使用例:

public int contract(RuntimeContract contract, ResultSet rsin[], ResultSet rsout[])
throws SQLException

{
   DbsInfo.traceWrite("MITblOpContract");
   contract.disableCoGroup();
      ...
}
cogroupが無効になっている場合、複数の入力ストリームを処理するテーブル演算子がAMP数が異なるさまざまな構成のシステムで一定の結果を返す可能性があります。さまざまな構成で一定の結果を得るには、cogroupを有効にする必要があります。

getAmpHash

public void  getAmpHash(int[][]  amphash)
パラメータ名 定義
amphash amphash[n][0]はAMP番号です。

amphash[n][1]は、AMPにハッシュする値とともに返されます。

nは、amphash配列のサイズです。

指定したAMPにハッシュされる値を返します。このルーチンはAMPまたはPE vprocで呼び出すことができます。

getBaseInfo

public UDTBaseInfo[]  getBaseInfo(ColumnDefinition[]  colDefs)
   throws SQLException
パラメータ名 定義
colDefs 列定義の一覧。

UDTまたはCDTの列に関するメタデータ情報を取得します。

メソッドは、渡されたColumnDefinitionオブジェクトに対しUDTBaseInfoオブジェクトの配列を返します。このメソッドは、コントラクト関数でのみ呼び出し可能です。

getContractCtx

public byte[]  getContractCtx()

AMPの契約バイトにアクセスできます。このメソッドはsetContracCtx(byte [])で使用されます。

byte[]は、TeradataパーサーのsetContracCtx(Object)からAMP中の演算子へオブジェクトを返します。

getContractObject

public java.lang.Object  getContractObject()
   throws java.io.IOException,
          java.lang.ClassNotFoundException

AMPのシリアライズされた契約オブジェクトにアクセスできます。このメソッドはsetContracCtx(Object)で使用されます。

オブジェクトは、TeradataパーサーのsetContracCtx(Object)からAMP中の演算子へオブジェクトを返します。

getContractPhase

public ContractPhase  getContractPhase();
コントラクト関数が呼び出されている構文解析プログラムのフェーズを示します。構文解析プログラムのフェーズは次のとおりです。
  • FNC_CTRCT_GET_ALLCOLS_PHASE = 0

    リモート テーブルのすべての列が返されることを示します。

  • FNC_CTRCT_VALIDATE_PHASE = 1

    指定した入力が正しいことを検証します。コントラクト関数は、このフェーズから複数回呼び出すことができます。

    このフェーズは現在使用されていません。
  • FNC_CTRCT_COMPLETE_PHASE = 2

    これがコントラクト関数の最後の呼び出しであり、実行が必要な外部サーバーのアクションを完了する必要があることを示します。

  • FNC_CTRCT_DDL_PHASE = 3

    CREATE SERVER文の実行が完了し、接続を検証する必要があることを示します。

  • FNC_CTRCT_DEFINE_SERVER_PHASE = 4

    CREATE VIEW文またはCREATE MACRO文が実行中で、カスタム句データが有効でない場合があることを示します。

このルーチンは、PE vprocでテーブル演算子によってのみ呼び出し可能です。

getDBSSessionAttrInfo

String getDBSSessionAttrInfo();
現在のセッションに関する情報をテーブル演算子に返します。getDBSSessionAttrInfoは、以下を含むシステム変数やセッション属性などの現在のセッション情報を含むJSON形式の文字列を返します。
  • 現在のユーザー名
  • 現在のロール名
  • トランザクション モード
  • 照合

現在のロール名に対して、最大127のロール名が返されます。ユーザーに127を超えるロールが付与されており、ユーザーがすべてのロールを有効にするためにSET ROLE ALL文を発行した場合、現在のロール名に対して"ALL"が返されます。例えば、次の出力例は127を超えるロールが有効になっているTESTUSERに返されるセッション情報を示しています。

{"CurUserName":"TESTUSER","CurRoleName":"ALL","TransactionMode":"BTET","Collation":"ASCII"}

SET ROLE ALLを指定したがロールが127以下のユーザーの場合は、"ALL"と共に各ロール名が返されます。例えば、TESTUSER2には、Role1、Role2、およびRole3という3つのロールがあります。

{"CurUserName":"TESTUSER2","CurRoleName":["ALL","Role1","Role2","Role3"],"TransactionMode":"BTET","Collation":"ASCII"}

getExternalQuery

public String  getExternalQuery(
   ColumnDefinition[]  colDefs,
   ServerType          serverType,
   ExtOpSetType[]      extOpSetTypes,
   int[]               interfaceVersions)
      throws SQLException
パラメータ名 定義
colDefs 外部サーバーによってWHERE句で発生する可能性がある列定義の一覧。
serverType ServerTypeは次のように定義されます:
public enum ServerType {
   ANSISQL(0),
   HADOOP(1);
}
extOpSetTypes 外部サーバーでサポートされている有効な演算子のセット。
ExOpSetTypeは次のように定義されます:
public enum ExtOpSetType {
   Eq_ET(0),
   Ne_ET(1),
   Gt_ET(2),
   Le_ET(3),
   Lt_ET(4),
   And_ET(5),
   Or_ET(6),
   Not_ET(7),
   Between_ET(8),
   In_ET(9),
   NotIn_ET(10),
   Ge_ET(11),
   Like_ET(12),
   LastOp_ET(13);
}
interfaceVersions
  • 呼び出し側は、引数として目的のインターフェース バージョンを渡します。
  • ルーチンは、現在サポートされている実際のインターフェースのバージョンを返します。

外部サーバーのテキスト問合わせ文字列を生成し、現在サポートされているインターフェース バージョンを返します。メソッドは外部問合わせを含む文字列を返します。

このルーチンは、PE vprocでテーブル演算子によってのみ呼び出し可能です。

例: getExternalQueryの呼び出し

ServerType sType = ServerType.ANSISQL;
ExtOpSetType extOpTypes[] = new ExtOpSetType[3];
extOpTypes[0] = ExtOpSetType.Eq_ET;
extOpTypes[1] = ExtOpSetType.And_ET;
extOpTypes[2] = ExtOpSetType.Or_ET;

int[] versions = new int[2];
versions[0] = 1;    // The caller passes in the desired interface version.

String extQuery = contract.getExternalQuery(colDefs, sType, extOpTypes, versions);

getExternalQueryを呼び出した後、versions[1]には現在システムでサポートされている実際のインターフェースのバージョンが含まれます。

getHashAmp

public int  getHashAmp(Object[]  data)
パラメータ名 定義
data テーブルの列を表わす配列。

データを受け取り、そのキーに必要なAMPを決定します。メソッドはそのキーに必要なAMPの数を表わす整数を返します。このルーチンは、PE vprocでテーブル演算子によってのみ呼び出し可能です。

getInnerContractCtx

public byte[]  getInnerContractCtx()
   throws SQLException

外部テーブル演算子が使用するための、ネストされた内部テーブル演算子のコントラクト定義を取得します。内部コントラクト関数が存在しない場合はNULLが返されます。このルーチンは、PE vprocでテーブル演算子によってのみ呼び出し可能です。

getInputInfo

public InputInfo  getInputInfo()

InputInfoコンテナへアクセスしてテーブル演算子の実行に関するメタデータを取得できます。

getUniqTblOpID

public int  getUniqTblOpID()

テーブル演算子に関連付けられた固有識別子を戻します。

複数のテーブル演算子が1つの問合わせにある場合、SELECT * FROM operator (on (select * from operator))などのマップ削減演算では、固有テーブル識別子を使用して各テーブル演算子を識別することができます。

setActivityCount

public void  setActivityCount(int  stream, long  rowsexported)
   throws SQLException
パラメータ名 定義
stream 書き込み先のストリームを指定します。
rowsexported ActivityCountに書き込まれる値。

エクスポートされる行の数を設定します。このルーチンは、テーブル演算子によってAMP vprocでのみ呼び出すことができます。

setContractCtx

public void  setContractCtx(byte[]ctx)
   throws java.sql.SQLException
パラメータ名 定義
ctx AMPに渡されるデータ。

TeradataパーサーからAMPに渡すべきbyte[]を定義します。

setContractCtx

public void  setContractCtx(java.lang.Object  Obj)
   throws java.io.IOException
パラメータ名 定義
Obj 契約オブジェクト。

契約オブジェクトをシリアライズおよび設定します。クラス オブジェクトはwriteObject()をサポートする必要があります。

setDisplayLength

public void  setDisplayLength(char  direction,
                             ColumnDefinition[]  colDefs)
   throws SQLException
パラメータ名 定義
char direction INパラメータ

入力値として、エクスポートの場合は'R'、インポートの場合は'W'を指定します。

ColumnDefinition[] colDefs IN/OUTパラメータ

表示長さがリセットされる列定義。

VARCHARデータ型の列定義の長さをリセットします。このルーチンはインポートおよびエクスポートの両方の操作に対して呼び出すことができます。

ルーチンは、テーブル演算子によってPE vprocでのみ呼び出すことができます。

setExplainText

public void  setExplainText(String[]  texts);
パラメータ名 定義
texts EXPLAINテキスト文字列を格納する配列。

テーブル演算子にhexplainカスタム句のセットがある場合、EXPLAINテキストを設定します。

Hexplainには、完了するEXPLAINの型の次の値があります。
  • 1 = 単純
  • 2 = 冗長
  • 3 = DBQL

このルーチンは、外部サーバーからの複数行EXPLAIN計画を処理するために入力として複数の自己格納型EXPLAINテキスト文字列を受け取ります。ルーチンはEXPLAIN計画の複数行を表示する構文解析プログラムにEXPLAIN計画を提供します。

このルーチンは、PE vprocでテーブル演算子によってのみ呼び出し可能です。

setFormat

public void  setFormat(
   int  stream,
   InputInfo.StreamDir  dir,
   java.util.Map<StreamFormat.FormatAttribute,java.lang.Object>  formatattributes)
パラメータ名 定義
stream INパラメータ

形式が適用されるストリームを示します。現在有効な値は0のみです。

dir INパラメータ

ストリーム(入力または出力)の方向。

formatattributes INパラメータ
適用される属性値のマップ。有効な属性は、以下のとおりです。
  • "RECFMT"
  • "TZTYPE"
  • "CHARSETFMT"
  • "REPUNSPTCHR"

"CHARSETFMT"と"REPUNSPTCHR"は、テーブル演算子のインポートにのみ適用されます。

入力および出力ストリームの形式属性を設定します。これにより、コントラクト関数は構文解析プログラムへのデータ型の書式を指定することができます。

使用上の注意
  • このルーチンは、テーブル演算子のコントラクト関数内で呼び出された場合にのみ有効です。
  • "RECFMT"のデフォルト値はINDICFMT1で、形式は行セパレータ センチネル付きIndicDataです。フィールドレベルの形式はすべて、レコード全体に影響を及ぼします。
  • 外部サーバーからインポートされるデータにTeradata Databaseでサポートされていない文字が含まれている場合、setFormat()を使用して、明示的に"CHARSETFMT"属性と"REPUNSPTCHR"属性を設定します。

形式属性の値

パラメータ名 定義
"RECFMT" レコード形式を定義します:
  • INDICFMT1 = 1

    行セパレータ センチネル付きIndicData。

  • INDICBUFFMT1 = 2

    行/パーティション セパレータ センチネルなしIndicData。

"TZTYPE" TIME/TIMESTAMPデータを異なる形式でテーブル演算子から受信する、またはテーブル演算子に送信するためのTeradata Databaseへの識別子として使用されます。
  • Teradata Databaseファイル システムに格納されるRAW = 0
  • UTC = 1 as UTC
"CHARSETFMT"
  • EVLDBC

    データ変換も検出も必要としないことを示します。

  • EVLUTF16CHARSET

    Teradata Databaseにインポートされる外部データがUTF16エンコードであることを示します。

  • EVLUTF8CHARSET

    Teradata Databaseにインポートされる外部データがUTF8エンコードであることを示します。

"REPUNSPTCHR" サポートされていないUnicode文字がTeradata Databaseにインポートされる外部データで検出されるときの動作を指定するブール値。
  • true

    サポートされていない文字をU+FFFDに置き換えます。

  • false

    サポートされていない文字が検出された場合はエラーを返します。これはデフォルトの動作です。

TIME/TIMESTAMPデータのインポートとエクスポート

データをこれらの外部サーバーにインポートまたはエクスポートしているときに、Teradata Database TIMEデータ型とTIMESTAMPデータ型をHadoop STRINGデータ型またはOracle TIMESTAMPデータ型にマッピングできます。

テーブル演算子はsetFormat()を使用して、tztype属性をTeradata Databaseへの識別子として設定し、TIMESTAMPデータをネイティブの調整した形式でテーブル演算子から受信したり、テーブル演算子に送信したりできます。

tztype属性は、インポート演算子およびエクスポート演算子に対し、次のように設定されます。
  • Hadoopの場合、属性はUTCに設定されます。
  • Oracleの場合、属性はUTCに設定されます。

変換がオフの場合、データはテーブルの演算子のデフォルトで、標準UDFと一貫したRAW形式で転送されます。

tztypeは、次のようにfnctypes.hで定義された構造FNC_FmtConfig_tのメンバーです:
typedef struct
{
   int Stream_Fmt_en recordfmt; //enum - indicdata, fastload binary, delimited
   bool inlinelob; //inline or deferred
   bool UDTTransformsOff; //true or false
   bool PDTTransformsOff; //true or false
   bool ArrayTransformsOff; //true or false
   char auxinfo[128]; //For delimited text can contain the record separator, delimiter
                         //specification and the field enclosure characters
   double inperc; //recommended percentage of buffer devoted to input rows
   bool inputnames; //send input column names to step
   bool outputnames; //send output column names to step
   TZType_en tztype; //enum - Raw or UTC
   int charsetfmt; // charset format of data to be imported into TD through QG
   bool replUnsprtedUniChar; /* true - replace unsupported unicode character
                                encountered with U+FFFD when data is imported
                                into TD through QG
                                false - error out when unsupported unicode
                                char encountered */
} FNC_FmtConfig_t;
TZType_enは次のように定義されます:
typedef enum
{
   Raw = 0, /* as stored on TD File system */
   UTC = 1, /* as UTC */
} TZType_en;

エクスポートの場合、setInputInfo()は意味解釈ルーチンのコントラクト フェーズで呼び出され、tztype属性を使用して必要なキャストを入力TIMEまたはTIMESTAMP列型に追加します。

Teradata DatabaseはTIMEおよびTIMESTAMPデータを文字型にキャストする前にセッション ローカル時間に変換します。そのため、TIME列またはTIMESTAMP列がHadoop STRING型へのマッピング時にcharfix/charvarにマッピングされるとき、データはセッション ローカル タイムゾーンで送信され、明示的キャストは不要になります。

インポートの場合、入力バッファをテーブル演算子から取得するときにTIMEデータまたはTIMESTAMPデータをRAW形式に変換する必要があります。Teradata Database TIMEデータ型またはTIMESTAMPデータ型へのHadoop Stringsのインポートに必要な変換はありません。文字からTeradata DatabaseのTIME/TIMESTAMPへの通常の変換パスの後に付くためです。

Teradataでは、timedatewzcontrolフラグ57 = 0でTeradata DatabaseシステムのTIME/TIMESTAMPデータをインポートまたはエクスポートすることは推奨しません。そのようなシステムの場合、TIME/TIMESTAMPデータはOSローカル時間で保存されます。システム/セッションのタイムゾーンは設定されず、Teradata DatabaseはTIME/TIMESTAMPデータのディスクからの読み取りまたは書き込み時に変換は適用しません。そのため、そのようなデータを外部サーバーによって指定される形式で安全にエクスポートすることには問題があり、TeradataではそのようなシステムにTeradata-to-Hadoopコネクタ機能を使用しないことを推奨しています。

setHashBy

public void  setHashBy(int  streamno,
                      String[]  colNames)
   throws SQLException
パラメータ名 定義
streamno 入力ストリーム番号。
colNames HASH BYメタデータを指すポインタ。

テーブル演算子作成時に、コントラクト関数作成者にHASH BY指定の設定を許可します。

このルーチンは、コントラクト関数内で呼び出された場合にのみ有効です。PE vprocで呼び出すことができます。

ストリーム番号が無効の場合、またはHASH BYメタデータが設定済みの場合、このルーチンはエラーを返します。

setInputInfo

public void  setInputInfo(int  streamNo,
                         ColumnDefinition[]  colDefs)
   throws SQLException
パラメータ名 定義
streamno 入力ストリーム番号。
colDefs 列定義の一覧。

入力列にキャスト文を設定し、データ型を呼び出し側によって示されるとおりにキャストします。

ルーチンは、テーブル演算子によってPE vprocでのみ呼び出すことができます。

setOrderBy

public void  setOrderBy(int  streamno,
                       String[]  colNames)
   throws SQLException
パラメータ名 定義
streamno 入力ストリーム番号。
colNames LOCAL ORDER BYメタデータを指すポインタ。

テーブル演算子作成時に、コントラクト関数作成者に整列指定の設定を許可します。

このルーチンは、コントラクト関数内で呼び出された場合にのみ有効です。PE vprocで呼び出すことができます。

ストリーム番号が無効の場合、またはLOCAL ORDER BYメタデータが設定済みの場合、このルーチンはエラーを返します。

setOutputInfo

public void  setOutputInfo(int  streamno,
   ColumnDefinition[]  info)
   throws java.sql.SQLException
パラメータ名 定義
streamno 列定義が適用されるストリームを示します。現在有効な値は0のみです。
info 定義済み列。

ストリームの出力情報を定義します。

継承メソッド

以下のメソッドをclass java.lang.Objectから継承できます。
  • equals
  • getClass
  • hashCode
  • notify
  • notifyAll
  • toString
  • wait, wait, wait