Skip to main content

AggregateFunction

fsqlite_func::aggregate

Trait AggregateFunction 

Source 
pub trait AggregateFunction: Send + Sync {
    type State: Send;

    // Required methods
    fn initial_state(&self) -> Self::State;
    fn step(&self, state: &mut Self::State, args: &[SqliteValue]) -> Result<()>;
    fn finalize(&self, state: Self::State) -> Result<SqliteValue>;
    fn num_args(&self) -> i32;
    fn name(&self) -> &str;

    // Provided methods
    fn step_with_arg_subtypes(
        &self,
        state: &mut Self::State,
        args: &[SqliteValue],
        _arg_subtypes: &[u32],
    ) -> Result<()> { ... }
    fn min_args(&self) -> i32 { ... }
    fn max_args(&self) -> Option<i32> { ... }
    fn arity(&self) -> FunctionArity { ... }
}
Expand description

An aggregate SQL function (e.g. SUM, COUNT, AVG).

This trait is open (user-implementable). Extension authors implement this trait to register custom aggregate functions.

§State Lifecycle

  1. initial_state creates a fresh accumulator.
  2. step is called once per row.
  3. finalize consumes the state and returns the result.

§Send + Sync

The function object itself is shared across threads via Arc. The State type must be Send so it can be moved between threads.

Required Associated Types§

Source

type State: Send

The per-group accumulator type.

Required Methods§

Source

fn initial_state(&self) -> Self::State

Create a fresh accumulator (zero/identity state).

Source

fn step(&self, state: &mut Self::State, args: &[SqliteValue]) -> Result<()>

Process one row, updating the accumulator.

Source

fn finalize(&self, state: Self::State) -> Result<SqliteValue>

Consume the accumulator and produce the final result.

Source

fn num_args(&self) -> i32

The number of arguments this function accepts (-1 = variadic).

Source

fn name(&self) -> &str

The function name, used in error messages and EXPLAIN output.

Provided Methods§

Source

fn step_with_arg_subtypes( &self, state: &mut Self::State, args: &[SqliteValue], _arg_subtypes: &[u32], ) -> Result<()>

Process one row with per-argument subtype tags available.

arg_subtypes[i] is the subtype of args[i] (0 when untagged), the same channel the scalar path exposes via ScalarFunction::invoke_with_arg_subtypes. The default ignores the tags and forwards to Self::step; aggregates that must preserve them (e.g. json_group_array embedding a nested json_object(...) rather than quoting it) override this.

Source

fn min_args(&self) -> i32

Minimum accepted SQL argument count for a variadic function.

The default is zero. Fixed-arity functions are matched directly from Self::num_args and do not consult this method.

Source

fn max_args(&self) -> Option<i32>

Maximum accepted SQL argument count for a variadic function.

The default is unbounded. Fixed-arity functions are matched directly from Self::num_args and do not consult this method.

Source

fn arity(&self) -> FunctionArity

Return the complete SQL-visible arity contract in one metadata call.

Registries use this method exactly once before publication, preventing a reentrant or stateful Self::num_args implementation from producing a key and bounds from different observations.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§