Implement Parameter Validation for PPL functions on Calcite

[yuancu]

Description

Implement parameter validations. It supports validations for

• Calcite built-in functions. E.g. registerOperator(ABS, SqlStdOperatorTable.ABS)
• Self-implemented UDFs. E.g. registerOperator(SHA2, PPLBuiltinOperators.SHA2);
• Directly registered implementations (with out registerOperator). E.g.

   register(
         TRIM,
         (FuncImpl1)
             (builder, arg) ->
                 builder.makeCall(
                     SqlStdOperatorTable.TRIM,
                     builder.makeFlag(Flag.BOTH),
                     builder.makeLiteral(" "),
                     arg));

Besides, it support functions with signature overriddings. E.g. timestamp has multiple signatures:

(STRING/DATE/TIME/TIMESTAMP) -> TIMESTAMP
(STRING/DATE/TIME/TIMESTAMP, STRING/DATE/TIME/TIMESTAMP) -> TIMESTAMP

This implementation is based on the PoC in #3562, where it explains why we can not directly adopt Calcite's built-in type checking mechanism for SQL and how our type checking works.

Issues Resolved

Resolves #3608

Implementation Notes

Classes related to type checking & their roles

• UDFOperandMetadata: Created for compatibility with SqlUserDefinedFunction, which serves as the basis for implementing our UDFs. Since SqlUserDefinedFunction only accepts SqlOperandMetadata as its type checker, and SqlOperandMetadata is incompatible with Calcite's built-in operators, UDFOperandMetadata was introduced. It acts as a wrapper around Calcite's operand type checkers, allowing us to reuse them. This ensures that type checkers can be utilized in the same way as Calcite's built-in operators for type checking.
• PPLTypeChecker: The type checker that does the real work. It retrieved acceptable types from Calcite's type checkers, and compare them with the actual ones.
• SqlOperandTypeChecker, ImplicitCastOperandTypeChecker, FamilyOperandTypeChecker, ...: Calcite's builtin type checkers. Cannot be directly used since it requires a SqlCallBinding: boolean checkOperandTypes(SqlCallBinding callBinding, boolean throwOnFailure).

classDiagram
    class SqlOperandTypeChecker {
        <<interface>>
        +checkOperandTypes(SqlCallBinding, boolean)
    }

    class CompositeOperandTypeChecker {
    }

    class FamilyOperandTypeChecker {
    }

    class PPLTypeChecker {
		    <<interface>>
        +checkOperandTypes(actualTypes) : boolean
    }
    
    class PPLFamilyTypeChecker {
	    - families: List[SqlTypeFamily]
    }
    
    class PPLCompositeTypeChecker {
	    - rules: List[FamilyOperandTypeChecker]
    }

    class UDFOperandMetadata {
       <<interface>>
       <<extends>> SqlOperandMetadata
       <<extends>> ImplicitCastOperandTypeChecker
        +getInnerTypeChecker() : SqlOperandTypeChecker
    }
    
    class SqlOperator {
		    <<abstract>>
		    - operandTypeChecker: SqlOperandTypeChecker
		    + getOperandTypeChecker() : SqlOperandTypeChecker
    }
    
    class SqlUserDefinedFunction {
				+SqlUserDefinedFunction(SqlOperandMetadata, ...)
    }
    
    

    %% Relationships
    SqlOperandTypeChecker <|.. FamilyOperandTypeChecker
    SqlOperandTypeChecker <|.. CompositeOperandTypeChecker
    SqlOperator <|-- SqlUserDefinedFunction
    PPLTypeChecker  <|.. PPLFamilyTypeChecker
    PPLTypeChecker  <|.. PPLCompositeTypeChecker
    UDFOperandMetadata --> SqlUserDefinedFunction : feeds to constructor
    SqlOperator *-- SqlOperandTypeChecker: contains
    %% UDFOperandMetadata *-- SqlOperandTypeChecker
    PPLFamilyTypeChecker ..> FamilyOperandTypeChecker: wraps
    PPLCompositeTypeChecker ..> CompositeOperandTypeChecker: wraps

Loading

Type checking for Calcite's built-in operators & for self-implemented UDFs

• For Calcite's built-in operators: the operator's type checker is first retrieved as a SqlOperandTypeChecker, then wrapped with PPLTypeChecker which does the actual type checking with the expected param types in the SqlOperandTypeChecker.
• For UDFs: We first wrap Calcite's type checker with UDFOperandMetadata to create a SqlUderDefinedFunction, which implements SqlOperator. Afterwards, the actual Calcite type checker can be retrieved and used in the same way as Calcite's built-in operators.
• For UDFs registered with register(funcName, FuncImp) interface, since there is no SqlOperator involved, we directly pass a PPLTypeChecker when creating a FuncImp instance.

Check List

• New functionality includes testing.
  • All tests pass, including unit test, integration test and doctest
• New functionality has been documented.
  • New functionality has javadoc added
  • New functionality has user manual doc added
• Commits are signed per the DCO using --signoff

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[penghuo]

Using @log4j2?

[yuancu]

As it was in an interface, I was hesitated in adding a static member logger to it. Therefore, I used LogManageer.getLogger().error(). It's also part of log4j.

Now this line is removed.

[penghuo]

I also see VARCHAR in other test cases. for instance, testTimestampWithWrongArg, does this issue all solved?

[LantaoJin]

We could investigate how to leverage SqlNode validation later 3.1.0. Approved.