Simple and Vector Function metadata

[aditi-pandit]

Co-author : @pramodsatya

A goal of Prestissimo SPIV2 is to make the Presto co-ordinator aware of the functions supported in the Prestissimo worker. Presto co-ordinator needs json conforming to JsonBasedUdfFunctionMetadata (https://github.com/prestodb/presto/blob/master/presto-function-namespace-managers/src/main/java/com/facebook/presto/functionNamespace/json/JsonBasedUdfFunctionMetadata.java) to register all Presto worker functions in its catalogs. So we are trying (in presto_cpp logic) to build this metadata from each function in the Velox function registries to expose to the Presto co-ordinator.

To achieve this we have run into multiple road-blocks :

• Metadata in JsonBasedUdfFunctionMetadata viz determinism, nullCallClause are not available in a uniform manner from Velox. Some of the information is available (if at all) from VectorFunctionMetadata, SimpleFunctionMetadata or UDFHolder (see relevant background below). We feel these fields should be exposed as part of the FunctionSignature (and AggregateFunctionSignature or WindowFunctionSignature respectively).

• Prestissimo shouldn’t have to resolve functions to the actual function object and retrieve metadata from them. (like for VectorFunctionMetadata).

• Prestissimo shouldn’t have to access UDFHolder/UDFRegistration logic to get these fields. Those are part of the Velox SimpleFunctionAdapter framework used to construct functions.

• This metadata should be part of the Velox runtime.

• Ideally, there should be a single source of truth for this metadata for both SimpleFunctions and VectorFunctions. VectorFunctionMetadata seems like a good place for this. SimpleFunctionAdapterFactory should populate this structure for Simple functions as well.

• Aggregate functions do not have metadata for nullCallClause. Can this be inferred somehow ?

The rest of this document provides more details about each of the above items.

Background

Scalar functions in Velox

Scalar functions in Velox can be written using either the simple function API or as a vector function. Simple functions abstract the engine details and are easier to write.

The simple function framework allows developers to write the function logic by taking a single row of values as the input. e.g the logic of the simple function year which takes a single argument of type timestamp and returns an int64_t value is defined by the following call method in the class YearFunction:

  FOLLY_ALWAYS_INLINE void call(
      int64_t& result,
      const arg_type<Timestamp>& timestamp) {
    result = getYear(getDateTime(timestamp, this->timeZone_));
  }

Functions are registered using registerFunction. e.g.

registerFunction<YearFunction, int64_t, Timestamp>({prefix + "year"});

The registration makes these functions and their signatures queryable from a FunctionRegistry structure.

Vector functions
Vector functions on the other hand are written to run on whole vectors.

Vector functions derive from the base class, VectorFunction, which consists of a pure virtual function, apply, that defines the function logic:

void apply(
      const velox::SelectivityVector& /* rows */,
      std::vector<velox::VectorPtr>& /* args */,
      const TypePtr& /* outputType */,
      velox::exec::EvalCtx& /* context */,
      velox::VectorPtr& /* result */) const override {}

Vector functions are registered against a set of supported signatures, which are constructed using the FunctionSignatureBuilder and bound to the function as follows:

exec::FunctionSignatureBuilder()
                .typeVariable("K")
                .typeVariable("V")
                .returnType("map(K,V)")
                .argumentType("map(K,V)")
                .argumentType("function(K,V,boolean)")
                .build()
...
exec::registerVectorFunction(name, signatures, function);    

Simple function metadata

Internally, all simple functions are converted to an instance of VectorFunction for vectorized execution. This is accomplished by the utility class SimpleFunctionAdapter, which derives from VectorFunction and constructs the apply function from the simple function definition.

Mechanics of Simple function

Simple functions are registered using the following helper function in Velox, which takes the function’s class, return type, and argument types as template variables:

template <typename Func, typename TReturn, typename... TArgs>
void registerFunction(const std::vector<std::string>& aliases = {}) {
  using funcClass = typename Func::template udf<exec::VectorExec>;
  using holderClass = core::UDFHolder<
      funcClass,
      exec::VectorExec,
      TReturn,
      ConstantChecker<TArgs...>,
      typename UnwrapConstantType<TArgs>::type...>;
  exec::registerSimpleFunction<holderClass>(aliases);
}

The function registerSimpleFunction is templated on the class UDFHolder and is defined as:

// This function should be called once and alone.
template <typename UDFHolder>
void registerSimpleFunction(const std::vector<std::string>& names) {
  mutableSimpleFunctions()
      .registerFunction<SimpleFunctionAdapterFactoryImpl<UDFHolder>>(names);
}

mutableSimpleFunctions returns an instance of class SimpleFunctionRegistry, which keeps track of all the registered simple functions. The helper function registerFunction in SimpleFunctionRegistry registers the function name in the function registry, mapping it to the function metadata and function entry:

class SimpleFunctionRegistry {
  template <typename UDF>
  void registerFunction(const std::vector<std::string>& aliases = {}) {
    const auto& metadata = singletonUdfMetadata<typename UDF::Metadata>();
    const auto factory = [metadata]() { return CreateUdf<UDF>(); };

    if (aliases.empty()) {
      registerFunctionInternal(metadata->getName(), metadata, factory);
    } else {
      for (const auto& name : aliases) {
        registerFunctionInternal(name, metadata, factory);
      }
    }
  }
...
}

The template variable UDF here corresponds to the class SimpleFunctionAdapterFactoryImpl, which exposes the metadata from the class UDFHolder, and provides a helper function to construct an instance of VectorFunction using utility class SimpleFunctionAdapter:

template <typename UDFHolder>
class SimpleFunctionAdapterFactoryImpl : public SimpleFunctionAdapterFactory {
 public:
  // Exposed for use in FunctionRegistry
  using Metadata = typename UDFHolder::Metadata;
  ...

  std::unique_ptr<VectorFunction> createVectorFunction(
      const std::vector<VectorPtr>& constantInputs,
      const core::QueryConfig& config) const override {
    return std::make_unique<SimpleFunctionAdapter<UDFHolder>>(
        config, constantInputs);
  }
}

The simple function metadata is obtained from the class UDFHolder and is represented by the class SimpleFunctionMetadata:

// wraps a UDF object to provide the inheritance
// this is basically just boilerplate-avoidance
template <
    typename Fun,
    typename Exec,
    typename TReturn,
    typename ConstantChecker,
    typename... TArgs>
class UDFHolder final
    : public core::
          SimpleFunctionMetadata<Fun, TReturn, ConstantChecker, TArgs...> {
  ...
public:
  ...
  using Metadata =
      core::SimpleFunctionMetadata<Fun, TReturn, ConstantChecker, TArgs...>;
  ...
}

Current logic to obtain ‘is_deterministic’ and ‘default_null_behavior‘:

The function signature for simple functions is constructed in SimpleFunctionMetadata::buildSignature. The fields is_deterministic and default_null_behavior, once added to the function signature, can be updated in buildSignature.

SimpleFunctionMetadata is currently missing information about the default null behavior. This information is present in the class UDFHolder in the variable default_null_behavior, which uses a method resolver to check if a callNullable method is defined in the function’s class. The default_null_behavior variable can be passed from UDFHolder to SimpleFunctionMetadata when the singleton instance of function metadata is created in SimpleFunctionRegistry::registerFunction. It would also require adding a variable in SimpleFunctionAdapterFactoryImpl to represent default_null_behavior so it’s value can be obtained in SimpleFunctionRegistry.

Open questions:

We rely on using the simple function framework to obtain the metadata values. Is this an ideal way to add new fields to simple function metadata? e.g. ‘default_null_behavior’ is inferred from the UDFHolder with
static constexpr bool is_default_null_behavior = !udf_has_callNullable;

Should this field be defined by the UDF author in the registration instead ?

Vector function metadata

Velox provides the following macro and helper function to register vector functions with metadata (represented by an instance of class VectorFunctionMetadata):

#define VELOX_DECLARE_VECTOR_FUNCTION_WITH_METADATA(             \
    tag, signatures, metadata, function)                         \
  void _VELOX_REGISTER_FUNC_NAME(tag)(const std::string& name) { \
    facebook::velox::exec::registerVectorFunction(               \
        (name), (signatures), (function), (metadata));           \
  }

...

bool registerVectorFunction(
    const std::string& name,
    std::vector<FunctionSignaturePtr> signatures,
    std::unique_ptr<VectorFunction> func,
    VectorFunctionMetadata metadata = {},
    bool overwrite = true);

Currently, the metadata about default null behavior and determinism is obtained from the following functions in the class VectorFunction:

virtual bool isDeterministic() const {
  return true;
}

// Returns true if null in any argument always produces null result.
// In this case, "rows" in "apply" will point only to positions for
// which all arguments are not null.
virtual bool isDefaultNullBehavior() const {
  return true;
}

Proposed change and open questions

• In the current design, the vector function would need to be resolved in order to obtain the metadata is_deterministic and default_null_behavior. It would be ideal to obtain this metadata from the function signature without resolving the function.
• Considering is_deterministic, this can be accomplished by adding a field in both VectorFunctionMetadata and the function signature to represent this metadata. In registerVectorFunction, the value of this metadata can be obtained from VectorFunctionMetadata, and then set in all the function signatures.
• Can a field be added to VectorFunctionMetadata to represent the default null behavior metadata? We need this to be consistent across Simple and VectorFunctions.
• Can the functions isDeterministic and isDefaultNullBehavior be removed from VectorFunction if they are moved to VectorFunctionMetadata?

Aggregate function metadata

For aggregate functions written using the recently added simple aggregate framework, which uses SimpleAggregateAdapter (eg: GeometricMeanAggregate), the metadata default_null_behavior can be obtained from the field SimpleAggregateAdapter::aggregate_default_null_behavior. However, the metadata is_deterministic is still missing. Furthermore, most of the aggregates are not written using the simple aggregate framework so the metadata aggregate_default_null_behavior is not present. This metadata can be obtained from AggregateFunctionSignature by adding fields for them but it is not clear how they will be populated since this information is not present.

• An open question here is whether all the aggregate functions will eventually be rewritten to use the simple aggregate framework?

[aditi-pandit]

@tdcmeehan @czentgr

[aditi-pandit]

@mbasmanova : Would be great to hear your thoughts on this.

[mbasmanova]

@aditi-pandit Aditi, thank you for a clear detailed writeup.

For scalar functions, it would be great to extend VectorFunctionMetadata to include is-deterministic and is-default-null-behavior flags and remove corresponding methods from the VectorFunction interface. I don't think we want to copy this data into signatures though. I suggest to keep it separate and update registry APIs to allow querying both signatures and metadata.

For aggregate functions, we need to introduce something similar, AggregateFunctionMetadata. There are no plans to re-write existing aggregate functions using simple API.