During the annotation state the server updates the parse tree with the metadata necessary for efficient and correct query optimization.
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 annotation state is represented in the v4 API by EXTFNAPIV4_STATE_ANNOTATION from the a_v4_extfn_state enumeration:
typedef enum a_v4_extfn_state {
… EXTFNAPIV4_STATE_ANNOTATION, …
} a_v4_extfn_state;
As a UDF developer, you can perform some initial schema negotiation in this phase. Schema negotiation can occur either through the UDF describing to the server what it supports, or the UDF asking the server how it was declared.
When the UDF describes itself to the server, the server detects mismatches and returns SQL errors back to the client. For example, if a UDF describes that it requires four parameters and the SQL writer only declared the UDF with two, the server detects this and returns a SQL error back to the client.
When the UDF itself performs the validation by asking the server how it was declared, it adjusts its runtime execution accordingly: it either matches the declaratio, or it returns an error via the set_error v4 API. For example, assume you build a UDF that returns the maximum value of up to five input scalar integers. At runtime, the UDF determines how many input parameters were provided and adjusts its internal logic accordingly. SQL analysts could then create the procedure as:
CREATE PROCEDURE my_sum_2( IN a INT, IN b INT ) EXTERNAL "my_sum@my_lib" CREATE PROCEDURE my_sum_3( IN a INT, IN b INT, IN c INT ) EXTERNAL "my_sum@my_lib"
Both functions use the same underling implementation of my_sum. The UDF recognizes that there are only two parameters for my_sum_2, and attempts to sum parameters 1 and 2. For my_sum_3, the UDF sums parameters 1, 2 and 3.
As a UDF developer, you can obtain values for constant literal parameters only in the Annotation state. No other values are available until the Execution state. To get parameter values during the annotation state use the describe_parameter_get method with the PARM_CONSTANT_VALUE and PARM_IS_CONSTANT attributes.
During the Annotation phase the UDF can set the above values to define its schema to the server. If the server detects a mismatch between what the UDF describes and the SQL procedure declaration, it returns an error. This technique is referred to as self-describing.
An alternative technique, schema validation, can be employed by the UDF. This involves the UDF getting the values for the schema describe types, and then setting an error if a mismatch is detected. With this approach, validation is left to the UDF, but the UDF can choose to support multiple schemas with a single implementation (for example, the ability to support multiple datatypes for a given parameter or being able to support varying number of parameters).