Enum datafusion::logical_plan::Expr

pub enum Expr {
    Alias(Box<Expr>, String),
    Column(String),
    ScalarVariable(Vec<String>),
    Literal(ScalarValue),
    BinaryExpr {
        left: Box<Expr>,
        op: Operator,
        right: Box<Expr>,
    },
    Not(Box<Expr>),
    IsNotNull(Box<Expr>),
    IsNull(Box<Expr>),
    Negative(Box<Expr>),
    Between {
        expr: Box<Expr>,
        negated: bool,
        low: Box<Expr>,
        high: Box<Expr>,
    },
    Case {
        expr: Option<Box<Expr>>,
        when_then_expr: Vec<(Box<Expr>, Box<Expr>)>,
        else_expr: Option<Box<Expr>>,
    },
    Cast {
        expr: Box<Expr>,
        data_type: DataType,
    },
    Sort {
        expr: Box<Expr>,
        asc: bool,
        nulls_first: bool,
    },
    ScalarFunction {
        fun: BuiltinScalarFunction,
        args: Vec<Expr>,
    },
    ScalarUDF {
        fun: Arc<ScalarUDF>,
        args: Vec<Expr>,
    },
    AggregateFunction {
        fun: AggregateFunction,
        args: Vec<Expr>,
        distinct: bool,
    },
    AggregateUDF {
        fun: Arc<AggregateUDF>,
        args: Vec<Expr>,
    },
    InList {
        expr: Box<Expr>,
        list: Vec<Expr>,
        negated: bool,
    },
    Wildcard,
}

Expr is a logical expression. A logical expression is something like 1 + 1, or CAST(c1 AS int). Logical expressions know how to compute its arrow::datatypes::DataType and nullability. Expr is a central struct of DataFusion's query API.

Examples

let expr = Expr::Column("c1".to_string()) + Expr::Column("c2".to_string());
println!("{:?}", expr);

Variants

Alias(Box<Expr>, String)

An expression with a specific name.

Column(String)

A named reference to a field in a schema.

ScalarVariable(Vec<String>)

A named reference to a variable in a registry.

Literal(ScalarValue)

A constant value.

BinaryExpr

A binary expression such as "age > 21"

Fields of BinaryExpr

left: Box<Expr>

Left-hand side of the expression

op: Operator

The comparison operator

right: Box<Expr>

Right-hand side of the expression

Not(Box<Expr>)

Negation of an expression. The expression's type must be a boolean to make sense.

IsNotNull(Box<Expr>)

Whether an expression is not Null. This expression is never null.

IsNull(Box<Expr>)

Whether an expression is Null. This expression is never null.

Negative(Box<Expr>)

arithmetic negation of an expression, the operand must be of a signed numeric data type

Between

Whether an expression is between a given range.

Fields of Between

expr: Box<Expr>

The value to compare

negated: bool

Whether the expression is negated

low: Box<Expr>

The low end of the range

high: Box<Expr>

The high end of the range

Case

The CASE expression is similar to a series of nested if/else and there are two forms that can be used. The first form consists of a series of boolean "when" expressions with corresponding "then" expressions, and an optional "else" expression.

CASE WHEN condition THEN result [WHEN ...] [ELSE result] END

The second form uses a base expression and then a series of "when" clauses that match on a literal value.

CASE expression WHEN value THEN result [WHEN ...] [ELSE result] END

Fields of Case

expr: Option<Box<Expr>>

Optional base expression that can be compared to literal values in the "when" expressions

when_then_expr: Vec<(Box<Expr>, Box<Expr>)>

One or more when/then expressions

else_expr: Option<Box<Expr>>

Optional "else" expression

Cast

Casts the expression to a given type. This expression is guaranteed to have a fixed type.

Fields of Cast

expr: Box<Expr>

The expression being cast

data_type: DataType

The DataType the expression will yield

Sort

A sort expression, that can be used to sort values.

Fields of Sort

expr: Box<Expr>

The expression to sort on

asc: bool

The direction of the sort

nulls_first: bool

Whether to put Nulls before all other data values

ScalarFunction

Represents the call of a built-in scalar function with a set of arguments.

Fields of ScalarFunction

fun: BuiltinScalarFunction

The function

args: Vec<Expr>

List of expressions to feed to the functions as arguments

ScalarUDF

Represents the call of a user-defined scalar function with arguments.

Fields of ScalarUDF

fun: Arc<ScalarUDF>

The function

args: Vec<Expr>

List of expressions to feed to the functions as arguments

AggregateFunction

Represents the call of an aggregate built-in function with arguments.

Fields of AggregateFunction

fun: AggregateFunction

Name of the function

args: Vec<Expr>

List of expressions to feed to the functions as arguments

distinct: bool

Whether this is a DISTINCT aggregation or not

AggregateUDF

aggregate function

Fields of AggregateUDF

fun: Arc<AggregateUDF>

The function

args: Vec<Expr>

List of expressions to feed to the functions as arguments

InList

Returns whether the list contains the expr value.

Fields of InList

expr: Box<Expr>

The expression to compare

list: Vec<Expr>

A list of values to compare against

negated: bool

Whether the expression is negated

Wildcard

Represents a reference to all fields in a schema.

Implementations

impl Expr

pub fn get_type(&self, schema: &DFSchema) -> Result<DataType>

Returns the arrow::datatypes::DataType of the expression based on arrow::datatypes::Schema.

Errors

This function errors when it is not possible to compute its arrow::datatypes::DataType. This happens when e.g. the expression refers to a column that does not exist in the schema, or when the expression is incorrectly typed (e.g. [utf8] + [bool]).

pub fn nullable(&self, input_schema: &DFSchema) -> Result<bool>

Returns the nullability of the expression based on arrow::datatypes::Schema.

Errors

This function errors when it is not possible to compute its nullability. This happens when the expression refers to a column that does not exist in the schema.

pub fn name(&self, input_schema: &DFSchema) -> Result<String>

Returns the name of this expression based on arrow::datatypes::Schema.

This represents how a column with this expression is named when no alias is chosen

pub fn to_field(&self, input_schema: &DFSchema) -> Result<DFField>

Returns a arrow::datatypes::Field compatible with this expression.

pub fn cast_to(
    &self,
    cast_to_type: &DataType,
    schema: &DFSchema
) -> Result<Expr>

Wraps this expression in a cast to a target arrow::datatypes::DataType.

Errors

This function errors when it is impossible to cast the expression to the target arrow::datatypes::DataType.

pub fn eq(&self, other: Expr) -> Expr

Equal

pub fn not_eq(&self, other: Expr) -> Expr

Not equal

pub fn gt(&self, other: Expr) -> Expr

Greater than

pub fn gt_eq(&self, other: Expr) -> Expr

Greater than or equal to

pub fn lt(&self, other: Expr) -> Expr

Less than

pub fn lt_eq(&self, other: Expr) -> Expr

Less than or equal to

pub fn and(&self, other: Expr) -> Expr

And

pub fn or(&self, other: Expr) -> Expr

Or

pub fn not(&self) -> Expr

Not

pub fn modulus(&self, other: Expr) -> Expr

Calculate the modulus of two expressions

pub fn like(&self, other: Expr) -> Expr

like (string) another expression

pub fn not_like(&self, other: Expr) -> Expr

not like another expression

pub fn alias(&self, name: &str) -> Expr

Alias

pub fn in_list(&self, list: Vec<Expr>, negated: bool) -> Expr

InList

pub fn sort(&self, asc: bool, nulls_first: bool) -> Expr

Create a sort expression from an existing expression.

let sort_expr = col("foo").sort(true, true); // SORT ASC NULLS_FIRST

Trait Implementations

impl Add<Expr> for Expr

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self

Performs the + operation.

impl Clone for Expr

fn clone(&self) -> Expr

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Expr

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Div<Expr> for Expr

type Output = Self

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self

Performs the / operation.

impl Mul<Expr> for Expr

type Output = Self

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self

Performs the * operation.

impl PartialEq<Expr> for Expr

fn eq(&self, other: &Expr) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Expr) -> bool

This method tests for !=.

impl StructuralPartialEq for Expr

impl Sub<Expr> for Expr

type Output = Self

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self

Performs the - operation.