tmudr::UDRPlanInfo Class Reference

Describes the query plan used for a UDR invocation. More...

#include <sqludr.h>

Inherits tmudr::TMUDRSerializableObject.

Public Types
enum	SpecialDegreeOfParallelism { ANY_DEGREE_OF_PARALLELISM = 0, DEFAULT_DEGREE_OF_PARALLELISM = -1, MAX_DEGREE_OF_PARALLELISM = -2, ONE_INSTANCE_PER_NODE = -3 }
	Special degrees of parallelism. More...
Public Member Functions
int	getPlanNum () const
long	getCostPerRow () const
int	getDesiredDegreeOfParallelism () const
void	setCostPerRow (long nanoseconds)
void	setDesiredDegreeOfParallelism (int dop)
UDRWriterCompileTimeData *	getUDRWriterCompileTimeData ()
void	setUDRWriterCompileTimeData (UDRWriterCompileTimeData *compileTimeData)
void	addPlanData (const char *planData, int planDataLength)
const char *	getPlanData (int &planDataLength)
void	print ()

---

Detailed Description

Describes the query plan used for a UDR invocation.

Objects of this type are used together with UDRInvocationInfo objects and they contain additional info on plan-related such as the chosen partitioning and ordering.

---

Member Enumeration Documentation

enum tmudr::UDRPlanInfo::SpecialDegreeOfParallelism

Special degrees of parallelism.

Values that can be used in the setDesiredDegreeOfParallelism() method, in addition to positive numbers for the degree of parallelism (DoP).

Enumerator:

ANY_DEGREE_OF_PARALLELISM	Optimizer decides DoP.
DEFAULT_DEGREE_OF_PARALLELISM	Optimizer decides DoP based on dataflow heuristics.
MAX_DEGREE_OF_PARALLELISM	Execute the UDF with the largest degree of parallelism allowed.
ONE_INSTANCE_PER_NODE	Execute one instance of the on every Trafodion node. Used internally for maintenance UDFs.

---

Member Function Documentation

void UDRPlanInfo::addPlanData	(	const char *	planData,
		int	planDataLength
	)

Attach a byte array to the plan to be sent to the runtime instances.

Compile time and runtime interfaces of the UDR can be called from different processes, since UDRs can be executed in parallel and on different nodes. If the UDR writer would like to carry state from the compiler interface calls to runtime calls, the best way to achieve this to attach it using this call and to retrieve the state at runtime using the getPlanData() call.

The best place to use this method is from within UDR::completeDescription() method, since this method is called on the optimal plan that will be used at runtime. It can also be called from other methods, and the plan data will be discarded if the plan is not chosen.

See also:

getPlanData()

Parameters:

	planData	A byte array, content defined by the UDR writer, to be sent to all runtime instances executing the UDR. The buffer can and should be deleted by the caller after calling this method.
	planDataLength	Length, in bytes, of the planData.

Exceptions:

UDRException

long UDRPlanInfo::getCostPerRow

(

)

const

Get the cost of the UDR per row, approximately in nanoseconds.

See also:

setCostPerRow()

Returns:

Cost of the UDR per row, in nanoseconds, for optimization purposes.

int UDRPlanInfo::getDesiredDegreeOfParallelism

(

)

const

Return the desired degree of parallelism for this plan.

See also:

setDesiredDegreeOfParallelism()

Returns:

Degree of parallelism to be used for this plan alternative (positive) or one of the enum values in UDRPlanInfo::SpecialDegreeOfParallelism (zero or negative).

const char * UDRPlanInfo::getPlanData

(

int &

planDataLength

)

Retrieve plan data attached to the UDR invocation and plan.

This method can be called at runtime to get state generated at compile time.

See also:

setPlanData()

Parameters:

planDataLength

(out) Length of returned plan data.

Returns:

Pointer to a byte array with plan data generated by the UDR writer at compile time.

int UDRPlanInfo::getPlanNum

(

)

const

Get a unique id for a given plan within a UDR invocation.

Returns:

Plan number for this object, relative to the invocation.

UDRWriterCompileTimeData * UDRPlanInfo::getUDRWriterCompileTimeData

(

)

Get data to persist between calls of the optimizer interface

See also:

setUDRWriterCompileTimeData()

Returns:

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

Exceptions:

UDRException

void UDRPlanInfo::print

(

)

Print the object, for use in debugging.

See also:

UDRInvocationInfo::PRINT_INVOCATION_INFO_AT_RUN_TIME

void UDRPlanInfo::setCostPerRow

(

long

nanoseconds

)

Set the cost of the UDR per row, approximately in nanoseconds.

Specifying a cost can help with query plan issues. Note that the operator cost ("EST_OPER_COST") in EXPLAIN is not directly related to the nanosecond value specified here:

• For parallel plans (those under an ESP_EXCHANGE), the cost is calculated for one parallel instance only.
• The cost in nanoseconds is converted to internal units (see CQD NCM_UDR_NANOSEC_FACTOR).
• The EXPLAIN cost contains additional factors, accounting for the cost to send input data to the process that executes the UDR and for sending back the result.

The default implementation estimates the cost to be approximately 100 * sqrt(out().getRecordLength()). Therefore, a value of 1000 might be a good starting point for a cost per row estimate, assuming an output row length of about 1 KB. Increase this for more complex UDFs or for wider result rows, decrease it for simpler UDFs or shorter result rows.

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

See also:

UDR::describeDesiredDegreeOfParallelism()

getCostPerRow()

UDR::TupleInfo::getRecordLength()

Parameters:

nanoseconds

Cost of the UDR per row, in nanoseconds, for optimization purposes.

void UDRPlanInfo::setDesiredDegreeOfParallelism

(

int

dop

)

Set the desired degree of parallelism.

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

Here are some special values that can be set, in addition to positive numbers. These are defined in class UDRPlanInfo.

• ANY_DEGREE_OF_PARALLELISM: This will allow the optimizer to choose any degree of parallelism, including 1 (serial execution)
• DEFAULT_DEGREE_OF_PARALLELISM: Currently the same as ANY_DEGREE_OF_PARALLELISM. The optimizer will use a heuristic based on the estimated cardinality.
• MAX_DEGREE_OF_PARALLELISM: Choose the highest possible degree of parallelism.
• ONE_INSTANCE_PER_NODE: Start one parallel instance on every Trafodion node. This is mostly meant for internal TMUDFs, e.g. a TMUDF to read the log files on every node.

See also:

getDesiredDegreeOfParallelism()

Parameters:

dop

desired degree of parallelism (a positive number or one of the enum values in UDRPlanInfo::SpecialDegreeOfParallelism).

Exceptions:

UDRException

void UDRPlanInfo::setUDRWriterCompileTimeData

(

UDRWriterCompileTimeData *

compileTimeData

)

Set data to persist between calls of the optimizer interface

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

Use this method to keep data that is specific to a query plan alternative, represented by the UDRPlanInfo object. Use UDRInvocationInfo::setUDRWriterCompileTimeData() to keep data that is common for the entire UDR invocation.

See also:

UDRInvocationInfo::setUDRWriterCompileTimeData()

getUDRWriterCompileTimeData()

Parameters:

compileTimeData

UDR writer-defined compile-time data to attach.

Exceptions:

UDRException

---

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

• sqludr.h
• sqludr.cpp