Query Optimization State

During the Optimization state, the server is in the initial process of constructing a query plan. The server collects schema information and some preliminary statistical information.

The [_enter_state], _describe_extfn, and [_leave_state] methods are called. The _enter_state and _leave_state methods are optional, and called if provided by the UDF.

The query optimization state is represented in the v4 API by EXTFNAPIV4_STATE_OPTIMIZATION from the a_v4_extfn_state enumeration:

typedef enum a_v4_extfn_state {
    … EXTFNAPIV4_STATE_OPTIMIZATION, …
} a_v4_extfn_state;

Negotiations during the query optimization state include:

The server and UDF determine the partitioning/ordering/clustering already specified for input tables.
The server and UDF determine the partitioning/ordering required for input tables.
The UDF declares physical properties (such as an ordering property) for the result table.
The UDF describes any properties and statistics (for example, cost estimates) which can be used during the query optimization process.
- Table scope estimates include:
  - Number of rows – the total number of rows present in the UDF during the execution state. This value is available for both the input TABLE parameter and the returned table.
  - Row size – an estimate of the average number of bytes in each row.
- Column scope estimates include:
  - Distinct count – the number of distinct values in a column over the total number of rows in a table. This value is available for both the input TABLE parameter and the returned table.

In the Optimization state, UDFs have access to describe attributes:

EXTFNAPIV4_DESCRIBE_PARM_NAME
EXTFNAPIV4_DESCRIBE_PARM_TYPE
EXTFNAPIV4_DESCRIBE_PARM_WIDTH
EXTFNAPIV4_DESCRIBE_PARM_SCALE
EXTFNAPIV4_DESCRIBE_PARM_IS_CONSTANT
EXTFNAPIV4_DESCRIBE_PARM_CONSTANT_VALUE
EXTFNAPIV4_DESCRIBE_PARM_TABLE_NUM_COLUMNS
EXTFNAPIV4_DESCRIBE_PARM_TABLE_NUM_ROWS
EXTFNAPIV4_DESCRIBE_PARM_TABLE_ORDERBY
EXTFNAPIV4_DESCRIBE_PARM_TABLE_PARTITIONBY
EXTFNAPIV4_DESCRIBE_PARM_TABLE_REQUEST_REWIND
EXTFNAPIV4_DESCRIBE_PARM_TABLE_HAS_REWIND
EXTFNAPIV4_DESCRIBE_COL_NAME
EXTFNAPIV4_DESCRIBE_COL_TYPE
EXTFNAPIV4_DESCRIBE_COL_WIDTH
EXTFNAPIV4_DESCRIBE_COL_SCALE
EXTFNAPIV4_DESCRIBE_COL_CAN_BE_NULL
EXTFNAPIV4_DESCRIBE_COL_IS_CONSTANT
EXTFNAPIV4_DESCRIBE_COL_CONSTANT_VALUE
EXTFNAPIV4_DESCRIBE_COL_IS_USED_BY_CONSUMER
EXTFNAPIV4_DESCRIBE_COL_VALUES_SUBSET_OF_INPUT