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,
    },
    TryCast {
        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 central struct of DataFusion’s query API, and represent logical expressions such as A + 1, or CAST(c1 AS int).

An Expr can compute its DataType and nullability, and has functions for building up complex expressions.

Examples

Create an expression c1 referring to column named “c1”

let expr = col("c1");
assert_eq!(expr, Expr::Column("c1".to_string()));

Create the expression c1 + c2 to add columns “c1” and “c2” together

let expr = col("c1") + col("c2");

assert!(matches!(expr, Expr::BinaryExpr { ..} ));
if let Expr::BinaryExpr { left, right, op } = expr {
  assert_eq!(*left, col("c1"));
  assert_eq!(*right, col("c2"));
  assert_eq!(op, Operator::Plus);
}

Create expression c1 = 42 to compare the value in coumn “c1” to the literal value 42

let expr = col("c1").eq(lit(42));

assert!(matches!(expr, Expr::BinaryExpr { ..} ));
if let Expr::BinaryExpr { left, right, op } = expr {
  assert_eq!(*left, col("c1"));
  let scalar = ScalarValue::Int32(Some(42));
  assert_eq!(*right, Expr::Literal(scalar));
  assert_eq!(op, Operator::Eq);
}

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 and will return a runtime error if the expression cannot be cast. 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

TryCast

Casts the expression to a given type and will return a null value if the expression cannot be cast. This expression is guaranteed to have a fixed type.

Fields of TryCast

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

Return self == other

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

Return self != other

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

Return self > other

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

Return self >= other

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

Return self < other

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

Return self <= other

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

Return self && other

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

Return self || other

pub fn not(self) -> Expr

Return !self

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

Calculate the modulus of two expressions. Return self % other

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

Return self LIKE other

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

Return self NOT LIKE other

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

Return self AS name alias expression

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

Return self IN <list> if negated is false, otherwise return self NOT IN <list>.a

pub fn is_null(self) -> Expr

Return `IsNull(Box(self))

pub fn is_not_null(self) -> Expr

Return `IsNotNull(Box(self))

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

pub fn accept<V: ExpressionVisitor>(&self, visitor: V) -> Result<V>

Performs a depth first walk of an expression and its children, calling ExpressionVisitor::pre_visit and visitor.post_visit.

Implements the visitor pattern to separate expression algorithms from the structure of the Expr tree and make it easier to add new types of expressions and algorithms that walk the tree.

For an expression tree such as

BinaryExpr (GT)
   left: Column("foo")
   right: Column("bar")

The nodes are visited using the following order

pre_visit(BinaryExpr(GT))
pre_visit(Column("foo"))
pre_visit(Column("bar"))
post_visit(Column("bar"))
post_visit(Column("bar"))
post_visit(BinaryExpr(GT))

If an Err result is returned, recursion is stopped immediately

If Recursion::Stop is returned on a call to pre_visit, no children of that expression are visited, nor is post_visit called on that expression

pub fn rewrite<R>(self, rewriter: &mut R) -> Result<Self> where
    R: ExprRewriter, 

Performs a depth first walk of an expression and its children to rewrite an expression, consuming self producing a new Expr.

Implements a modified version of the visitor pattern to separate algorithms from the structure of the Expr tree and make it easier to write new, efficient expression transformation algorithms.

For an expression tree such as

BinaryExpr (GT)
   left: Column("foo")
   right: Column("bar")

The nodes are visited using the following order

pre_visit(BinaryExpr(GT))
pre_visit(Column("foo"))
mutatate(Column("foo"))
pre_visit(Column("bar"))
mutate(Column("bar"))
mutate(BinaryExpr(GT))

If an Err result is returned, recursion is stopped immediately

If false is returned on a call to pre_visit, no children of that expression are visited, nor is mutate called on that expression

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.