Enum datafusion_expr::expr::Expr

pub enum Expr {
    Alias(Box<Expr>, String),
    Column(Column),
    ScalarVariable(DataType, Vec<String>),
    Literal(ScalarValue),
    BinaryExpr(BinaryExpr),
    Like(Like),
    ILike(Like),
    SimilarTo(Like),
    Not(Box<Expr>),
    IsNotNull(Box<Expr>),
    IsNull(Box<Expr>),
    IsTrue(Box<Expr>),
    IsFalse(Box<Expr>),
    IsUnknown(Box<Expr>),
    IsNotTrue(Box<Expr>),
    IsNotFalse(Box<Expr>),
    IsNotUnknown(Box<Expr>),
    Negative(Box<Expr>),
    GetIndexedField(GetIndexedField),
    Between(Between),
    Case(Case),
    Cast(Cast),
    TryCast(TryCast),
    Sort(Sort),
    ScalarFunction {
        fun: BuiltinScalarFunction,
        args: Vec<Expr>,
    },
    ScalarUDF {
        fun: Arc<ScalarUDF>,
        args: Vec<Expr>,
    },
    AggregateFunction(AggregateFunction),
    WindowFunction(WindowFunction),
    AggregateUDF {
        fun: Arc<AggregateUDF>,
        args: Vec<Expr>,
        filter: Option<Box<Expr>>,
    },
    InList {
        expr: Box<Expr>,
        list: Vec<Expr>,
        negated: bool,
    },
    Exists {
        subquery: Subquery,
        negated: bool,
    },
    InSubquery {
        expr: Box<Expr>,
        subquery: Subquery,
        negated: bool,
    },
    ScalarSubquery(Subquery),
    Wildcard,
    QualifiedWildcard {
        qualifier: String,
    },
    GroupingSet(GroupingSet),
    Placeholder {
        id: String,
        data_type: Option<DataType>,
    },
}

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(Column::from_name("c1")));

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(binary_expr) = expr {
  assert_eq!(*binary_expr.left, col("c1"));
  assert_eq!(*binary_expr.right, col("c2"));
  assert_eq!(binary_expr.op, Operator::Plus);
}

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

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

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

Variants

Alias(Box<Expr>, String)

An expression with a specific name.

Column(Column)

A named reference to a qualified filed in a schema.

ScalarVariable(DataType, Vec<String>)

A named reference to a variable in a registry.

Literal(ScalarValue)

A constant value.

BinaryExpr(BinaryExpr)

A binary expression such as “age > 21”

Like(Like)

LIKE expression

ILike(Like)

Case-insensitive LIKE expression

SimilarTo(Like)

LIKE expression that uses regular expressions

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.

IsTrue(Box<Expr>)

Whether an expression is True. Boolean operation

IsFalse(Box<Expr>)

Whether an expression is False. Boolean operation

IsUnknown(Box<Expr>)

Whether an expression is Unknown. Boolean operation

IsNotTrue(Box<Expr>)

Whether an expression is not True. Boolean operation

IsNotFalse(Box<Expr>)

Whether an expression is not False. Boolean operation

IsNotUnknown(Box<Expr>)

Whether an expression is not Unknown. Boolean operation

Negative(Box<Expr>)

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

GetIndexedField(GetIndexedField)

Returns the field of a [arrow::array::ListArray] or [arrow::array::StructArray] by key

Between(Between)

Whether an expression is between a given range.

Case(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

Cast(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.

TryCast(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.

Sort(Sort)

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

ScalarFunction

Fields

fun: BuiltinScalarFunction

The function

args: Vec<Expr>

List of expressions to feed to the functions as arguments

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

ScalarUDF

Fields

fun: Arc<ScalarUDF>

The function

args: Vec<Expr>

List of expressions to feed to the functions as arguments

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

AggregateFunction(AggregateFunction)

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

WindowFunction(WindowFunction)

Represents the call of a window function with arguments.

AggregateUDF

Fields

fun: Arc<AggregateUDF>

The function

args: Vec<Expr>

List of expressions to feed to the functions as arguments

filter: Option<Box<Expr>>

Optional filter applied prior to aggregating

aggregate function

InList

Fields

expr: Box<Expr>

The expression to compare

list: Vec<Expr>

A list of values to compare against

negated: bool

Whether the expression is negated

Returns whether the list contains the expr value.

Exists

Fields

subquery: Subquery

subquery that will produce a single column of data

negated: bool

Whether the expression is negated

EXISTS subquery

InSubquery

Fields

expr: Box<Expr>

The expression to compare

subquery: Subquery

subquery that will produce a single column of data to compare against

negated: bool

Whether the expression is negated

IN subquery

ScalarSubquery(Subquery)

Scalar subquery

Wildcard

Represents a reference to all fields in a schema.

QualifiedWildcard

Fields

qualifier: String

Represents a reference to all fields in a specific schema.

GroupingSet(GroupingSet)

List of grouping set expressions. Only valid in the context of an aggregate GROUP BY expression list

Placeholder

Fields

id: String

The identifier of the parameter (e.g, $1 or $foo)

data_type: Option<DataType>

The type the parameter will be filled in with

A place holder for parameters in a prepared statement (e.g. $foo or $1)

Implementations

impl Expr

pub fn display_name(&self) -> Result<String>

Returns the name of this expression as it should appear in a schema. This name will not include any CAST expressions.

pub fn name(&self) -> Result<String>

👎Deprecated since 14.0.0: please use display_name instead

Returns the name of this expression as it should appear in a schema. This name will not include any CAST expressions.

pub fn canonical_name(&self) -> String

Returns a full and complete string representation of this expression.

pub fn variant_name(&self) -> &str

Return String representation of the variant represented by self Useful for non-rust based bindings

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 ilike(self, other: Expr) -> Expr

Return self ILIKE other

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

Return self NOT ILIKE other

pub fn alias(self, name: impl Into<String>) -> Expr

Return self AS name alias expression

pub fn unalias(self) -> Expr

Remove an alias from an expression if one exists.

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 is_true(self) -> Expr

Return IsTrue(Box(self))

pub fn is_not_true(self) -> Expr

Return IsNotTrue(Box(self))

pub fn is_false(self) -> Expr

Return IsFalse(Box(self))

pub fn is_not_false(self) -> Expr

Return IsNotFalse(Box(self))

pub fn is_unknown(self) -> Expr

Return IsUnknown(Box(self))

pub fn is_not_unknown(self) -> Expr

Return IsNotUnknown(Box(self))

pub fn try_into_col(&self) -> Result<Column>

pub fn to_columns(&self) -> Result<HashSet<Column>>

Return all referenced columns of this expression.

Trait Implementations

impl Add<Expr> for Expr

type Output = Expr

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.

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

Performs copy-assignment from source.

impl Debug for Expr

Format expressions for display as part of a logical plan. In many cases, this will produce similar output to Expr.name() except that column names will be prefixed with ‘#’.

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

Formats the value using the given formatter.

impl Display for Expr

Format expressions for display as part of a logical plan. In many cases, this will produce similar output to Expr.name() except that column names will be prefixed with ‘#’.

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

Formats the value using the given formatter.

impl Div<Expr> for Expr

type Output = Expr

The resulting type after applying the / operator.

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

Performs the / operation.

impl ExprRewritable for Expr

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

see comments on ExprRewritable for details

impl ExprSchemable for Expr

fn get_type<S: ExprSchema>(&self, schema: &S) -> Result<DataType>

Returns the [arrow::datatypes::DataType] of the expression based on ExprSchema

Note: DFSchema implements ExprSchema.

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]).

fn nullable<S: ExprSchema>(&self, input_schema: &S) -> Result<bool>

Returns the nullability of the expression based on ExprSchema.

Note: DFSchema implements ExprSchema.

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.

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

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

So for example, a projected expression col(c1) + col(c2) is placed in an output field named col(“c1 + c2”)

fn cast_to<S: ExprSchema>( self, cast_to_type: &DataType, schema: &S ) -> 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].

impl ExprVisitable for Expr

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

Performs a depth first walk of an expression and its children, see ExpressionVisitor for more details

impl Hash for Expr

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul<Expr> for Expr

type Output = Expr

The resulting type after applying the * operator.

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

Performs the * operation.

impl Not for Expr

type Output = Expr

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! 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: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<Expr> for Expr

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl Rem<Expr> for Expr

type Output = Expr

The resulting type after applying the % operator.

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

Performs the % operation.

impl Sub<Expr> for Expr

type Output = Expr

The resulting type after applying the - operator.

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

Performs the - operation.

impl Eq for Expr

impl StructuralEq for Expr

impl StructuralPartialEq for Expr