Trait TableFunction

pub trait TableFunction:
    Debug
    + Sync
    + Send {
    // Required methods
    fn return_type(&self) -> DataType;
    fn eval<'a, 'async_trait>(
        &'a self,
        input: &'a DataChunk,
    ) -> Pin<Box<dyn Future<Output = BoxStream<'a, Result<DataChunk>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'a: 'async_trait;

    // Provided method
    fn boxed(self) -> BoxedTableFunction
       where Self: Sized + Send + 'static { ... }
}

A table function takes a row as input and returns multiple rows as output.

It is also known as Set-Returning Function.

Required Methods

fn return_type(&self) -> DataType

The data type of the output.

fn eval<'a, 'async_trait>( &'a self, input: &'a DataChunk, ) -> Pin<Box<dyn Future<Output = BoxStream<'a, Result<DataChunk>>> + Send + 'async_trait>>

where Self: 'async_trait, 'a: 'async_trait,

Contract of the output

The returned DataChunk contains two or three columns:

• The first column is an I32Array containing row indices of input chunk. It should be monotonically increasing.
• The second column is the output values. The data type of the column is return_type.
• (Optional) If any error occurs, the error message is stored in the third column.

i.e., for the i-th input row, the output rows are (i, output_1), (i, output_2), …

How the output is split into the Stream is arbitrary. It’s usually done by a DataChunkBuilder.

Example

select generate_series(1, x) from t(x);

# input chunk     output chunks
1 --------------> 0 1
2 --------------> 1 1
3 ----┐           ---
      │           1 2
      └---------> 2 1
                  ---
                  2 2
                  2 3
         row idx--^ ^--values

Relationship with ProjectSet executor

(You don’t need to understand this section to implement a TableFunction)

The output of the TableFunction is different from the output of the ProjectSet executor. ProjectSet executor uses the row indices to stitch multiple table functions and produces projected_row_id.

Example

select generate_series(1, x) from t(x);

# input chunk     output chunks (TableFunction)  output chunks (ProjectSet)
1 --------------> 0 1 -------------------------> 0 1
2 --------------> 1 1 -------------------------> 0 1
3 ----┐           ---                            ---
      │           1 2                            1 2
      └---------> 2 1 -------------------------> 0 1
                  ---                            ---
                  2 2                            1 2
                  2 3                            2 3
         row idx--^ ^--values  projected_row_id--^ ^--values

Provided Methods

fn boxed(self) -> BoxedTableFunction

where Self: Sized + Send + 'static,

Implementors

impl TableFunction for Empty

impl TableFunction for RepeatN

impl TableFunction for UserDefinedTableFunction