Trait datafusion_expr::WindowUDFImpl

source · 
pub trait WindowUDFImpl:
    Debug
    + Send
    + Sync {
    // Required methods
    fn as_any(&self) -> &dyn Any;
    fn name(&self) -> &str;
    fn signature(&self) -> &Signature;
    fn return_type(&self, arg_types: &[DataType]) -> Result<DataType>;
    fn partition_evaluator(&self) -> Result<Box<dyn PartitionEvaluator>>;

    // Provided methods
    fn aliases(&self) -> &[String] { ... }
    fn simplify(&self) -> Option<WindowFunctionSimplification> { ... }
    fn equals(&self, other: &dyn WindowUDFImpl) -> bool { ... }
    fn hash_value(&self) -> u64 { ... }
}
Expand description

Trait for implementing WindowUDF.

This trait exposes the full API for implementing user defined window functions and can be used to implement any function.

See advanced_udwf.rs for a full example with complete implementation and WindowUDF for other available options.

§Basic Example

#[derive(Debug, Clone)]
struct SmoothIt {
  signature: Signature
}

impl SmoothIt {
  fn new() -> Self {
    Self {
      signature: Signature::uniform(1, vec![DataType::Int32], Volatility::Immutable)
     }
  }
}

/// Implement the WindowUDFImpl trait for AddOne
impl WindowUDFImpl for SmoothIt {
   fn as_any(&self) -> &dyn Any { self }
   fn name(&self) -> &str { "smooth_it" }
   fn signature(&self) -> &Signature { &self.signature }
   fn return_type(&self, args: &[DataType]) -> Result<DataType> {
     if !matches!(args.get(0), Some(&DataType::Int32)) {
       return plan_err!("smooth_it only accepts Int32 arguments");
     }
     Ok(DataType::Int32)
   }
   // The actual implementation would add one to the argument
   fn partition_evaluator(&self) -> Result<Box<dyn PartitionEvaluator>> { unimplemented!() }
}

// Create a new WindowUDF from the implementation
let smooth_it = WindowUDF::from(SmoothIt::new());

// Call the function `add_one(col)`
// smooth_it(speed) OVER (PARTITION BY car ORDER BY time ASC)
let expr = smooth_it.call(vec![col("speed")])
    .partition_by(vec![col("car")])
    .order_by(vec![col("time").sort(true, true)])
    .window_frame(WindowFrame::new(None))
    .build()
    .unwrap();

Required Methods§

source

fn as_any(&self) -> &dyn Any

Returns this object as an Any trait object

source

fn name(&self) -> &str

Returns this function’s name

source

fn signature(&self) -> &Signature

Returns the function’s Signature for information about what input types are accepted and the function’s Volatility.

source

fn return_type(&self, arg_types: &[DataType]) -> Result<DataType>

What DataType will be returned by this function, given the types of the arguments

source

fn partition_evaluator(&self) -> Result<Box<dyn PartitionEvaluator>>

Invoke the function, returning the PartitionEvaluator instance

Provided Methods§

source

fn aliases(&self) -> &[String]

Returns any aliases (alternate names) for this function.

Note: aliases should only include names other than Self::name. Defaults to [] (no aliases)

source

fn simplify(&self) -> Option<WindowFunctionSimplification>

Optionally apply per-UDWF simplification / rewrite rules.

This can be used to apply function specific simplification rules during optimization. The default implementation does nothing.

Note that DataFusion handles simplifying arguments and “constant folding” (replacing a function call with constant arguments such as my_add(1,2) --> 3 ). Thus, there is no need to implement such optimizations manually for specific UDFs.

Example: [simplify_udwf_expression.rs]: https://github.com/apache/arrow-datafusion/blob/main/datafusion-examples/examples/simplify_udwf_expression.rs

§Returns

None if simplify is not defined or,

Or, a closure with two arguments:

source

fn equals(&self, other: &dyn WindowUDFImpl) -> bool

Return true if this window UDF is equal to the other.

Allows customizing the equality of window UDFs. Must be consistent with Self::hash_value and follow the same rules as Eq:

  • reflexive: a.equals(a);
  • symmetric: a.equals(b) implies b.equals(a);
  • transitive: a.equals(b) and b.equals(c) implies a.equals(c).

By default, compares Self::name and Self::signature.

source

fn hash_value(&self) -> u64

Returns a hash value for this window UDF.

Allows customizing the hash code of window UDFs. Similarly to Hash and Eq, if Self::equals returns true for two UDFs, their hash_values must be the same.

By default, hashes Self::name and Self::signature.

Implementors§