tmudr::UDRInvocationInfo Class Reference

Describes an invocation of a UDR. More...

#include <sqludr.h>

Inherits tmudr::TMUDRSerializableObject.

Public Types
enum	FuncType { GENERIC, MAPPER, REDUCER }
	Type of a TMUDF: Generic, mapper or reducer. More...
enum	SQLAccessType
enum	SQLTransactionType
enum	SQLRightsType
enum	IsolationType
enum	CallPhase
	call phase for the UDR interface More...
enum	DebugFlags { DEBUG_INITIAL_RUN_TIME_LOOP_ONE = 0x00000001, DEBUG_INITIAL_RUN_TIME_LOOP_ALL = 0x00000002, DEBUG_INITIAL_COMPILE_TIME_LOOP = 0x00000004, DEBUG_LOAD_MSG_LOOP = 0x00000008, TRACE_ROWS = 0x00000010, PRINT_INVOCATION_INFO_INITIAL = 0x00000020, PRINT_INVOCATION_INFO_END_COMPILE = 0x00000040, PRINT_INVOCATION_INFO_AT_RUN_TIME = 0x00000080, VALIDATE_WALLS = 0x00000100 }
	values used for the UDR_DEBUG_FLAGS CQD More...
Public Member Functions
const std::string &	getUDRName () const
int	getNumTableInputs () const
const TableInfo &	in (int childNum=0) const
const TableInfo &	out () const
CallPhase	getCallPhase () const
const std::string &	getCurrentUser () const
const std::string &	getSessionUser () const
const std::string &	getCurrentRole () const
bool	isCompileTime () const
bool	isRunTime () const
int	getDebugFlags () const
FuncType	getFuncType () const
const ParameterListInfo &	getFormalParameters () const
const ParameterListInfo &	par () const
int	getNumPredicates () const
const PredicateInfo &	getPredicate (int i) const
bool	isAComparisonPredicate (int i) const
const ComparisonPredicateInfo &	getComparisonPredicate (int i) const
TableInfo &	out ()
void	addFormalParameter (const ColumnInfo &param)
void	setFuncType (FuncType type)
void	addPassThruColumns (int inputTableNum=0, int startInputColNum=0, int endInputColNum=-1)
void	setChildPartitioning (int inputTableNum, const PartitionInfo &partInfo)
void	setChildOrdering (int inputTableNum, const OrderInfo &orderInfo)
void	setChildColumnUsage (int inputTableNum, int inputColumnNum, ColumnInfo::ColumnUseCode usage)
void	setUnusedPassthruColumns ()
void	setPredicateEvaluationCode (int predicateNum, PredicateInfo::EvaluationCode c)
void	pushPredicatesOnPassthruColumns (int startPredNum=0, int lastPredNum=-1)
void	propagateConstraintsFor1To1UDFs (bool exactlyOneRowPerInput)
UDRWriterCompileTimeData *	getUDRWriterCompileTimeData ()
void	setUDRWriterCompileTimeData (UDRWriterCompileTimeData *compileTimeData)
void	copyPassThruData (int inputTableNum=0, int startInputColNum=0, int endInputColNum=-1)
const std::string &	getQueryId () const
int	getNumParallelInstances () const
int	getMyInstanceNum () const
void	print ()

Detailed Description

Describes an invocation of a UDR.

This combines the description of the UDR, its names and properties with the parameters, input and output table layouts and other information. An object of this class is passed to most methods defined by the UDR writer. It can be used to get input and parameter data and to set values of table-valued output columns.

Member Enumeration Documentation

enum tmudr::UDRInvocationInfo::CallPhase

call phase for the UDR interface

This is of limited interest for UDR writers and mostly used internally to ensure method calls are not done at the wrong time.

enum tmudr::UDRInvocationInfo::DebugFlags

values used for the UDR_DEBUG_FLAGS CQD

use cqd UDR_DEBUG_FLAGS 'num' in SQL to set these, add up the flags (in decimal) that you want to set. See https://cwiki.apache.org/confluence/display/TRAFODION/Tutorial%3A+The+object-oriented+UDF+interface#Tutorial:Theobject-orientedUDFinterface-DebuggingUDFcode for details.

Enumerator:

DEBUG_INITIAL_RUN_TIME_LOOP_ONE	1
DEBUG_INITIAL_RUN_TIME_LOOP_ALL	2
DEBUG_INITIAL_COMPILE_TIME_LOOP	4
DEBUG_LOAD_MSG_LOOP	8
TRACE_ROWS	16
PRINT_INVOCATION_INFO_INITIAL	32
PRINT_INVOCATION_INFO_END_COMPILE	64
PRINT_INVOCATION_INFO_AT_RUN_TIME	128
VALIDATE_WALLS	256

enum tmudr::UDRInvocationInfo::FuncType

Type of a TMUDF: Generic, mapper or reducer.

Enumerator:

GENERIC	The Trafodion compiler will make only the most conservative assumptions about this type of UDF.
MAPPER	A UDF that behaves like a mapper. A mapper does not carry any state between rows it reads from its table-valued inputs. It produces zero or more output rows per input row. Because no state is kept between rows, the Trafodion compiler can automatically parallelize execution and push predicates down to the table-valued inputs.
REDUCER	A reducer requires the data to be partitioned on a set of columns. The UDF does not carry any state between groups of rows with the same partition column values, but it may carry state within such groups. This allows the compiler to parallelize execution and to push predicates on the partitioning column(s) down to table-valued inputs.

enum tmudr::UDRInvocationInfo::IsolationType

Indicates whether this UDR is trusted or not

enum tmudr::UDRInvocationInfo::SQLAccessType

Type of SQL access allowed in this routine

enum tmudr::UDRInvocationInfo::SQLRightsType

Effective user ids for determining privileges

This is meaningful only for UDRs that perform SQL operations, using the default connection.

enum tmudr::UDRInvocationInfo::SQLTransactionType

Type of transaction that is required, if any

Member Function Documentation

void UDRInvocationInfo::addFormalParameter ( const ColumnInfo & param )

Add a formal parameter to match an actual parameter.

Only use this method from within the UDR::describeParamsAndColumns() method.

See also:: describeParamsAndColumns()

Parameters:

param

Info with name and type of the formal parameter.

Exceptions:

UDRException

void UDRInvocationInfo::addPassThruColumns	(	int	inputTableNum = `0`,
		int	startInputColNum = `0`,
		int	endInputColNum = `-1`
	)

Add columns of table-valued inputs as output columns.

Many TMUDFs make the column values of their table-valued inputs available as output columns. Such columns are called "pass-thru" columns. This method is an easy interface to create such pass-thru columns. Note that if a column is marked as pass-thru column, the UDF must copy the input value to the output (e.g. with the copyPassThruData() method). If it fails to do that, incorrect results may occur, because the compiler makes the assumptions that these values are the same.

Only use this method from within the UDR::describeParamsAndColumns() method.

See also:: UDR::describeParamsAndColumns(); ProvenanceInfo; ColumnInfo::getProvenance()

Parameters:

	inputTableNum	Index of table-valued input to add.
	startInputColNum	First column of the table-valued input to add as an output column.
	endInputColNum	Last column of the table-valued input to add as an output column (note this is inclusive) or -1 to add all remaining column.

Exceptions:

UDRException

void UDRInvocationInfo::copyPassThruData	(	int	inputTableNum = `0`,
		int	startInputColNum = `0`,
		int	endInputColNum = `-1`
	)

Copy values of pass-thru columns from the input to the output table.

This method is an easy way to set the values of the table-valued result row from their corresponding values in the table-valued inputs. Note that the UDR must set all the values of the pass-thru columns to the corresponsing values of the input tables. If it fails to do that, some optimizations done by Trafodion could lead to wrong results (e.g. some predicates could be applied incorrectly). Every TMUDF with table-valued inputs and pass-thru columns should call this method for every row it emits.

This method can only be called from within UDR::processData().

See also:: addPassThruColumns(); UDR::processData()

Parameters:

	inputTableNum	Number of table-valued input to copy from.
	startInputColNum	First column number in the input table to copy
	endInputColNum	Last column number in the input table to copy (inclusive) or -1 to copy all remaining columns

Exceptions:

UDRException

UDRInvocationInfo::CallPhase UDRInvocationInfo::getCallPhase ( ) const

Get call phase.

This call is not normally needed, since we know which method of UDR we are in. However, in some cases where the UDR writer wants to use code in multiple call phases this might be useful.

Returns:: Enum for the call phase we are in.

const ComparisonPredicateInfo & UDRInvocationInfo::getComparisonPredicate ( int i ) const

Get a comparison predicate

Note: This will throw an exception if predicate i is not a comparison predicate. Use method isAComparisonPredicate() to make sure this is the case. Note also that the numbering scheme is the same as that for getPredicate, so if there is a mix of different predicate types, the numbers of comparison predicates are not contiguous.

See also:: getPredicate(); isAComparisonPredicate()

Parameters:

i

Number/ordinal of the predicate to retrieve.

Returns:: Comparison predicate.

Exceptions:

UDRException

const std::string & UDRInvocationInfo::getCurrentRole ( ) const

Get current role.

Returns:: Current role.

const std::string & UDRInvocationInfo::getCurrentUser ( ) const

Get current user.

Get the id of the current user, which is the effective user id at the time. This is usually the same as the session user, except when a view or UDR uses "definer privileges", substituting the current user with the definer of the view or UDR. In SQL, this value is called CURRENT_USER.

See also:: getSessionUser()

Returns:: Current user.

int UDRInvocationInfo::getDebugFlags ( ) const

Get debugging flags, set via CONTROL QUERY DEFAULT.

Debug flags are set via the UDR_DEBUG_FLAGS CONTROL QUERY DEFAULT at compile time. This returns the value of this CQD. Usually not needed.

Returns:: Value the UDR_DEBUG_FLAGS CQD has or had at compile time.

const ParameterListInfo & UDRInvocationInfo::getFormalParameters ( ) const

Get the formal parameters of the UDR invocation.

Formal parameters are available only at compile time. They are either defined in the CREATE FUNCTION DDL or through the compile time interface. Note that number and types of formal and actual parameters must match, once we return from the describeParamsAndColumns() call, otherwise an error will be generated.

Returns:: Formal parameter description.

UDRInvocationInfo::FuncType UDRInvocationInfo::getFuncType ( ) const

Get the function type of this UDR invocation.

Returns the function type that can be set by the UDR writer with the setFuncType() method.

See also:: setFuncType()

Returns:: Enum of the function type.

int UDRInvocationInfo::getMyInstanceNum ( ) const

Get the instance number of this runtime process.

Use this method to find out which of the parallel instances executing a UDR this process is.

This method can only be called from within UDR::processData().

See also:: getNumParallelInstances()

Returns:: A number between 0 and getNumParallelInstances() - 1.

Exceptions:

UDRException

int UDRInvocationInfo::getNumParallelInstances ( ) const

Get the number of parallel instances working on this UDR invocation.

Use this method to find out how many parallel instances are executing this UDR.

This method can only be called from within UDR::processData().

See also:: getMyInstanceNum()

Returns:: Number of parallel instances for this UDR invocation.

Exceptions:

UDRException

int UDRInvocationInfo::getNumPredicates ( ) const

Return number of predicates to be applied in the context of this UDF.

Don't use this method from within UDR::describeParamsAndColumns(), since the predicates are not yet set up in that phase.

Returns:: Number of predicates.

int UDRInvocationInfo::getNumTableInputs ( ) const

Get number of table-valued inputs provided.

Returns:: Number of table-valued inputs provided.

const PredicateInfo & UDRInvocationInfo::getPredicate ( int i ) const

Get the description of a predicate to be applied.

Returns:: Description of the predicate.

See also:: setPredicateEvaluationCode()

Exceptions:

UDRException

const std::string & UDRInvocationInfo::getQueryId ( ) const

Get query id.

The query id is only available at runtime. It is an empty string at compile time.

Returns:: Query id.

const std::string & UDRInvocationInfo::getSessionUser ( ) const

Get session user.

Get the id of the session user, which is the user who connected to the database. This is usually the same as the current user, except when a view or UDR uses "definer privileges", substituting the current user with the definer of the view or UDR. In SQL, this value is called SESSION_USER.

See also:: getCurrentUser()

Returns:: Session user.

const std::string & UDRInvocationInfo::getUDRName ( ) const

Get the UDR name.

Returns:: Fully qualified name (catalog.schema.name) of the UDR.

UDRWriterCompileTimeData * UDRInvocationInfo::getUDRWriterCompileTimeData ( )

Get data to persist between calls of the compile-time interface

The UDR writer must use a static or dynamic cast to get a pointer to the derived class.

Only use this method at compile time.

See also:: setUDRWriterCompileTimeData()

Returns:: UDR writer-specific data that was previously attached or NULL.

Exceptions:

UDRException

const TableInfo & UDRInvocationInfo::in ( int childNum = 0 ) const

Get description of a table-valued input.

Returns:: TableInfo reference for the table-valued input.

Exceptions:

UDRException

bool UDRInvocationInfo::isAComparisonPredicate ( int i ) const

Check whether a given predicate is a comparison predicate.

This returns whether it is safe to use method getComparisonPredicate().

See also:: getComparisonPredicate()

Parameters:

i

Number/ordinal index of the predicate.

Returns:: true if predcate i is a comparison predicate, false otherwise.

Exceptions:

UDRException

bool UDRInvocationInfo::isCompileTime ( ) const

Check whether we are in the compile time interface.

Returns:: true at compile time, false at run-time.

bool UDRInvocationInfo::isRunTime ( ) const

Check whether we are in the run-time interface.

Returns:: false at compile time, true at run-time.

TableInfo & UDRInvocationInfo::out ( )

Non-const method to get description of the table-valued result.

Returns:: Non-const TableInfo reference for the table-valued output.

const TableInfo & UDRInvocationInfo::out ( ) const

Get description of the table-valued result.

Returns:: TableInfo reference for the table-valued output.

const ParameterListInfo & UDRInvocationInfo::par ( ) const

Get parameters of the UDR invocation.

These are the actual parameters. At compile time, if a constant has been used, the value of this constant is available, using getString(), getInt() etc. methods. The isAvailable() method indicates whether the parameter is indeed available at compile time. Parameters are always available at run-time.

Returns:: Parameter description.

void UDRInvocationInfo::print ( )

Print the object, for use in debugging.

See also:: UDR::debugLoop(); UDRInvocationInfo::PRINT_INVOCATION_INFO_AT_RUN_TIME

void UDRInvocationInfo::propagateConstraintsFor1To1UDFs ( bool exactlyOneRowPerInput )

Propagate constraints for UDFs that return one result row for every input row.

Use this method only if the UDF returns no more than one result row for every input row it reads from its single table-valued input. Note that it is ok for the UDF to return no result rows for some input rows. Wrong results may be returned by SQL statements involving this UDF if the UDF does at runtime not conform to the 1x1 relationship of rows.

Only use this method from within the UDR::describeConstraints() method.

Parameters:

exactlyOneRowPerInput

Indicates whether the UDF returns exactly one output row (true) or at most one output row (false) for every input row.

void UDRInvocationInfo::pushPredicatesOnPassthruColumns	(	int	startPredNum = `0`,
		int	lastPredNum = `-1`
	)

Push predicates on pass-thru columns to the table-valued input.

Push one or more predicates to their corresponding table-valued input, if they reference only columns from that input, otherwise leave the predicate(s) unchanged.

Only use this method from within the UDR::describeDataflowAndPredicates() method.

See also:: PredicateInfo::setEvaluationCode(); UDR::describeDataflowAndPredicates()

Parameters:

	startPredNum	Number/index of first predicate to be pushed.
	lastPredNum	Number/index of last predicate to be pushed (inclusive) or -1 to push all remaining predicates.

Exceptions:

UDRException

void UDRInvocationInfo::setChildColumnUsage	(	int	inputTableNum,
		int	inputColumnNum,
		ColumnInfo::ColumnUseCode	usage
	)

Set the usage information for a column of a table-valued input

This method allows the UDR writer to specify whether a given child column is needed or not.

Only use this method from within the UDR::describeDataflowAndPredicates() method.

See also:: setUnusedPassthruColumns(); UDR::describeDataflowAndPredicates()

Parameters:

	inputTableNum	Number of table-valued input to set.
	inputColumnNum	Column number for the column to set.
	usage	New usage for this column.

Exceptions:

UDRException

void UDRInvocationInfo::setChildOrdering	(	int	inputTableNum,
		const OrderInfo &	orderInfo
	)

Set the ORDER BY info for a table-valued input.

This method allows the UDR writer to override the ORDER BY syntax specified for a table-valued input in the query. Use it to change the required order.

Only use this method from within the UDR::describeParamsAndColumns() method.

See also:: getChildOrdering(); UDR::describeParamsAndColumns()

Parameters:

	inputTableNum	Number of table-valued input to set.
	orderInfo	New information on required order for this input table.

Exceptions:

UDRException

void UDRInvocationInfo::setChildPartitioning	(	int	inputTableNum,
		const PartitionInfo &	partInfo
	)

Set the PARTITION BY info for a table-valued input.

This method allows the UDR writer to override the PARTITION BY syntax specified for a table-valued input in the query. Use it to change the required partitioning.

Only use this method from within the UDR::describeParamsAndColumns() method.

See also:: getChildPartitioning(); UDR::describeParamsAndColumns()

Parameters:

	inputTableNum	Number of table-valued input to set.
	partInfo	New information on required partitioning for this input table.

Exceptions:

UDRException

void UDRInvocationInfo::setFuncType ( FuncType type )

Set the function type of this UDR invocation.

Use this simple method with some caution, since it has an effect on how predicates are pushed down through TMUDFs with table-valued inputs. See describeDataflowAndPredicates() for details. The function type also influences the default degree of parallelism for a TMUDF.

Only use this method from within the UDR::describeParamsAndColumns() method.

See also:: getFunctType(); describeParamsAndColumns(); describeDataflowAndPredicates(); setDesiredDegreeOfParallelism()

Parameters:

type

Function type of this UDR invocation.

Exceptions:

UDRException

void UDRInvocationInfo::setPredicateEvaluationCode	(	int	predicateNum,
		PredicateInfo::EvaluationCode	c
	)

Decide where to evaluate a predicate.

Only use this method from within the UDR::describeDataflowAndPredicates() method.

See also:: getPredicate(); UDR::describeDataflowAndPredicates()

Parameters:

	predicateNum	Number/index of predicate returned by getPredicate() method.
	c	Evaluation code for this predicate.

Exceptions:

UDRException

void UDRInvocationInfo::setUDRWriterCompileTimeData ( UDRWriterCompileTimeData * compileTimeData )

Set data to persist between calls of the compile-time interface

This call can be used to attach an object derived from class UDRWriterCompileTimeData to the UDRInvocationInfo object. Once attached, the data will be carried between the stages of the compiler interface and can be used to keep state. Note that this data will be deleted at the end of the compiler phase and will not persist until runtime.

Only use this method at compile time.

To keep state for specific plan alternatives, use the UDRPlanInfo::setUDRWriterCompileTimeData() method.

See also:: UDRInvocationInfo::getUDRWriterCompileTimeData(); UDRPlanInfo::setUDRWriterCompileTimeData(); getUDRWriterCompileTimeData()

Parameters:

compileTimeData

UDR writer-defined compile-time data to attach.

Exceptions:

UDRException

void UDRInvocationInfo::setUnusedPassthruColumns ( )

Mark any passthru columns that are not needed as unused.

For any passthru columns that are marked as NOT_USED or NOT_PRODUCED in the table-valued result, set the corresponding input columns to NOT_USED as well. Note that this assumes that the UDF does not need these columns, either! The usage for the passthru column itself is also set to NOT_PRODUCED, since the UDF could not produce the column without having access to the corresponding input column.

Only use this method from within the UDR::describeDataflowAndPredicates() method.

See also:: addPassThruColumns(); setChildColumnUsage(); UDR::describeDataflowAndPredicates()

Exceptions:

UDRException

The documentation for this class was generated from the following files:

sqludr.h
sqludr.cpp

tmudr::UDRInvocationInfo Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation