RuntimeContract Methods - Advanced SQL Engine - Teradata Database

bytesTransferred

public void  bytesTransferred(long  in, long  out)
   throws SQLException

Records the number of bytes transferred between Teradata Database and the foreign server by the table operator. This routine is callable on an AMP vproc only by a table operator.

complete

public void  complete()

Finalize the contract with the Teradata parser.

disableCoGroup

public void  disableCoGroup()

Disables the cogroup functionality for table operators that handle multiple input streams.

Example usage:

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

{
   DbsInfo.traceWrite("MITblOpContract");
   contract.disableCoGroup();
      ...
}

getAmpHash

public void  getAmpHash(int[][]  amphash)

Returns values that hash to the specified AMPs. This routine is callable on an AMP or PE vproc.

getBaseInfo

public UDTBaseInfo[]  getBaseInfo(ColumnDefinition[]  colDefs)
   throws SQLException

Retrieves metadata information about a UDT or CDT column.

The method returns an array of UDTBaseInfo objects for the ColumnDefinition objects passed in. This method can only be invoked in the contract function.

getContractCtx

public byte[]  getContractCtx()

Provides access to the contract bytes in the AMP. This method is used with setContracCtx(byte []).

byte[] returns the object from setContracCtx(Object) from the Teradata parser to the operator in the AMP.

getContractObject

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

Provides access to the serialized contract object in the AMP. This method is used with setContracCtx(Object).

Object returns the object from setContracCtx(Object) from the Teradata parser to the operator in the AMP.

getContractPhase

public ContractPhase  getContractPhase();

This routine is callable on a PE vproc only by a table operator.

getDBSSessionAttrInfo

String getDBSSessionAttrInfo();

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

{"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

public enum ServerType {
   ANSISQL(0),
   HADOOP(1);
}

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);
}

Generates the text query string for the foreign server and returns the interface version that is currently supported. The method returns a string which contains the external query.

This routine is callable on a PE vproc only by a table operator.

Example: Calling 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);

After calling getExternalQuery, versions[1] will contain the actual interface version that is currently supported on the system.

getHashAmp

public int  getHashAmp(Object[]  data)

Accepts data and determines the AMP which would be responsible for that key. The method returns an integer representing the number of the AMP that would be responsible for the key. This routine is callable on a PE vproc only by a table operator.

getInnerContractCtx

public byte[]  getInnerContractCtx()
   throws SQLException

Gets the contract definition of a nested inner table operator for the outer table operator to use. NULL is returned if the inner contract function does not exist. This routine is callable on a PE vproc only by a table operator.

getInputInfo

public InputInfo  getInputInfo()

Provides access to the InputInfo container to get metadata about the execution of the table operator.

getUniqTblOpID

public int  getUniqTblOpID()

Returns the unique identifier associated with a table operator.

When multiple table operators are present in a single query, as in a map reduce operation such as SELECT * FROM operator (on (select * from operator), you can use the unique table identifier to distinguish between each of the table operators.

setActivityCount

public void  setActivityCount(int  stream, long  rowsexported)
   throws SQLException

Sets the number of rows exported. This routine is callable on an AMP vproc only by a table operator

setContractCtx

public void  setContractCtx(byte[]ctx)
   throws java.sql.SQLException

Defines a byte [] to be passed from the Teradata parser to the AMPs.

setContractCtx

public void  setContractCtx(java.lang.Object  Obj)
   throws java.io.IOException

Serializes and sets the contract object. Class object must support writeObject().

setDisplayLength

public void  setDisplayLength(char  direction,
                             ColumnDefinition[]  colDefs)
   throws SQLException

Resets the lengths in column definitions for VARCHAR data types. This routine can be invoked for both import and export operations.

The routine is callable on a PE vproc only by a table operator.

setExplainText

public void  setExplainText(String[]  texts);

Sets the EXPLAIN text when the table operator has the hexplain custom clause set.

This routine accepts multiple self-contained EXPLAIN text strings as input in order to handle a multi-row EXPLAIN plan from a foreign server. The routine provides the EXPLAIN plan to the parser which will display the multiple lines of the EXPLAIN plan.

This routine is callable on a PE vproc only by a table operator.

setFormat

public void  setFormat(
   int  stream,
   InputInfo.StreamDir  dir,
   java.util.Map<StreamFormat.FormatAttribute,java.lang.Object>  formatattributes)

Sets attributes of the format of the input and output streams. This allows the contract function to specify the format of the data types to the parser.

Format Attribute Values

Importing and Exporting TIME/TIMESTAMP Data

You can map the Teradata Database TIME and TIMESTAMP data types to the Hadoop STRING or the Oracle TIMESTAMP data type when importing or exporting data to these foreign servers.

The table operator can use setFormat() to set the tztype attribute as an indicator to Teradata Database to receive from or send TIMESTAMP data to the table operator in a native but adjusted format.

If the transform is off, the data will be transferred in Raw form which is the default for table operators and is consistent with standard UDFs.

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;

typedef enum
{
   Raw = 0, /* as stored on TD File system */
   UTC = 1, /* as UTC */
} TZType_en;

For export, setInputInfo() is called during the contract phase in the resolver and will use the tztype attribute to add the desired cast to the input TIME or TIMESTAMP column types.

Teradata Database converts the TIME and TIMESTAMP data to the session local time before casting to the character type, so when a TIME or TIMESTAMP column is being mapped to charfix/charvar as when mapping to the Hadoop STRING type, the data will transmit in session local time zone and no explicit casts are needed.

For import, when getting the input buffer from the table operator, TIME or TIMESTAMP data have to be converted to Raw form. There is no conversion needed for the import of Hadoop Strings to Teradata Database TIME or TIMESTAMP data types since it follows the normal conversion path from character to TIME/TIMESTAMP in Teradata Database.

setHashBy

public void  setHashBy(int  streamno,
                      String[]  colNames)
   throws SQLException

Allows the contract function writer to set the HASH BY specification when developing table operators.

This routine can only run if called from the contract function. It is callable on a PE vproc.

The routine will produce an error if the stream number is invalid or the HASH BY metadata was already set.

setInputInfo

public void  setInputInfo(int  streamNo,
                         ColumnDefinition[]  colDefs)
   throws SQLException

Sets casting statements on the input columns so that the data types are cast as indicated by the caller.

The routine is callable on a PE vproc only by a table operator.

setOrderBy

public void  setOrderBy(int  streamno,
                       String[]  colNames)
   throws SQLException

Allows the contract function writer to set the ordering specification when developing table operators.

This routine can only run if called from the contract function. It is callable on a PE vproc.

The routine will produce an error if the stream number is invalid or the LOCAL ORDER BY metadata was already set.

setOutputInfo

public void  setOutputInfo(int  streamno,
   ColumnDefinition[]  info)
   throws java.sql.SQLException

Defines the output information for the stream.

Inherited Methods