Trait PhysicalExpr

pub trait PhysicalExpr:
    Send
    + Sync
    + Display
    + Debug
    + DynEq
    + DynHash {
    // Required methods
    fn as_any(&self) -> &(dyn Any + 'static);
    fn data_type(
        &self,
        input_schema: &Schema,
    ) -> Result<DataType, DataFusionError>;
    fn nullable(&self, input_schema: &Schema) -> Result<bool, DataFusionError>;
    fn evaluate(
        &self,
        batch: &RecordBatch,
    ) -> Result<ColumnarValue, DataFusionError>;
    fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>>;
    fn with_new_children(
        self: Arc<Self>,
        children: Vec<Arc<dyn PhysicalExpr>>,
    ) -> Result<Arc<dyn PhysicalExpr>, DataFusionError>;

    // Provided methods
    fn evaluate_selection(
        &self,
        batch: &RecordBatch,
        selection: &BooleanArray,
    ) -> Result<ColumnarValue, DataFusionError> { ... }
    fn evaluate_bounds(
        &self,
        _children: &[&Interval],
    ) -> Result<Interval, DataFusionError> { ... }
    fn propagate_constraints(
        &self,
        _interval: &Interval,
        _children: &[&Interval],
    ) -> Result<Option<Vec<Interval>>, DataFusionError> { ... }
    fn evaluate_statistics(
        &self,
        children: &[&Distribution],
    ) -> Result<Distribution, DataFusionError> { ... }
    fn propagate_statistics(
        &self,
        parent: &Distribution,
        children: &[&Distribution],
    ) -> Result<Option<Vec<Distribution>>, DataFusionError> { ... }
    fn get_properties(
        &self,
        _children: &[ExprProperties],
    ) -> Result<ExprProperties, DataFusionError> { ... }
}

PhysicalExprs represent expressions such as A + 1 or CAST(c1 AS int).

PhysicalExpr knows its type, nullability and can be evaluated directly on a RecordBatch (see Self::evaluate).

PhysicalExpr are the physical counterpart to Expr used in logical planning. They are typically created from Expr by a PhysicalPlanner invoked from a higher level API

Some important examples of PhysicalExpr are:

• Column: Represents a column at a given index in a RecordBatch

To create PhysicalExpr from Expr, see

• SessionContext::create_physical_expr: A high level API
• create_physical_expr: A low level API

Required Methods

fn as_any(&self) -> &(dyn Any + 'static)

Returns the physical expression as Any so that it can be downcast to a specific implementation.

fn data_type(&self, input_schema: &Schema) -> Result<DataType, DataFusionError>

Get the data type of this expression, given the schema of the input

fn nullable(&self, input_schema: &Schema) -> Result<bool, DataFusionError>

Determine whether this expression is nullable, given the schema of the input

fn evaluate( &self, batch: &RecordBatch, ) -> Result<ColumnarValue, DataFusionError>

Evaluate an expression against a RecordBatch

fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>>

Get a list of child PhysicalExpr that provide the input for this expr.

fn with_new_children( self: Arc<Self>, children: Vec<Arc<dyn PhysicalExpr>>, ) -> Result<Arc<dyn PhysicalExpr>, DataFusionError>

Returns a new PhysicalExpr where all children were replaced by new exprs.

Provided Methods

fn evaluate_selection( &self, batch: &RecordBatch, selection: &BooleanArray, ) -> Result<ColumnarValue, DataFusionError>

Evaluate an expression against a RecordBatch after first applying a validity array

fn evaluate_bounds( &self, _children: &[&Interval], ) -> Result<Interval, DataFusionError>

Computes the output interval for the expression, given the input intervals.

Parameters

• children are the intervals for the children (inputs) of this expression.

Returns

A Result containing the output interval for the expression in case of success, or an error object in case of failure.

Example

If the expression is a + b, and the input intervals are a: [1, 2] and b: [3, 4], then the output interval would be [4, 6].

fn propagate_constraints( &self, _interval: &Interval, _children: &[&Interval], ) -> Result<Option<Vec<Interval>>, DataFusionError>

Updates bounds for child expressions, given a known interval for this expression.

This is used to propagate constraints down through an expression tree.

Parameters

• interval is the currently known interval for this expression.
• children are the current intervals for the children of this expression.

Returns

A Result containing a Vec of new intervals for the children (in order) in case of success, or an error object in case of failure.

If constraint propagation reveals an infeasibility for any child, returns None. If none of the children intervals change as a result of propagation, may return an empty vector instead of cloning children. This is the default (and conservative) return value.

Example

If the expression is a + b, the current interval is [4, 5] and the inputs a and b are respectively given as [0, 2] and [-∞, 4], then propagation would return [0, 2] and [2, 4] as b must be at least 2 to make the output at least 4.

fn evaluate_statistics( &self, children: &[&Distribution], ) -> Result<Distribution, DataFusionError>

Computes the output statistics for the expression, given the input statistics.

Parameters

• children are the statistics for the children (inputs) of this expression.

Returns

A Result containing the output statistics for the expression in case of success, or an error object in case of failure.

Expressions (should) implement this function and utilize the independence assumption, match on children distribution types and compute the output statistics accordingly. The default implementation simply creates an unknown output distribution by combining input ranges. This logic loses distribution information, but is a safe default.

fn propagate_statistics( &self, parent: &Distribution, children: &[&Distribution], ) -> Result<Option<Vec<Distribution>>, DataFusionError>

Updates children statistics using the given parent statistic for this expression.

This is used to propagate statistics down through an expression tree.

Parameters

• parent is the currently known statistics for this expression.
• children are the current statistics for the children of this expression.

Returns

A Result containing a Vec of new statistics for the children (in order) in case of success, or an error object in case of failure.

If statistics propagation reveals an infeasibility for any child, returns None. If none of the children statistics change as a result of propagation, may return an empty vector instead of cloning children. This is the default (and conservative) return value.

Expressions (should) implement this function and apply Bayes rule to reconcile and update parent/children statistics. This involves utilizing the independence assumption, and matching on distribution types. The default implementation simply creates an unknown distribution if it can narrow the range by propagating ranges. This logic loses distribution information, but is a safe default.

fn get_properties( &self, _children: &[ExprProperties], ) -> Result<ExprProperties, DataFusionError>

Calculates the properties of this PhysicalExpr based on its children’s properties (i.e. order and range), recursively aggregating the information from its children. In cases where the PhysicalExpr has no children (e.g., Literal or Column), these properties should be specified externally, as the function defaults to unknown properties.

Trait Implementations

impl AsRef<dyn PhysicalExpr> for PhysicalSortExpr

Access the PhysicalSortExpr as a PhysicalExpr

fn as_ref(&self) -> &(dyn PhysicalExpr + 'static)

Converts this type into a shared reference of the (usually inferred) input type.

impl DynTreeNode for dyn PhysicalExpr

fn arc_children(&self) -> Vec<&Arc<dyn PhysicalExpr>>

Returns all children of the specified TreeNode.

fn with_new_arc_children( &self, arc_self: Arc<dyn PhysicalExpr>, new_children: Vec<Arc<dyn PhysicalExpr>>, ) -> Result<Arc<dyn PhysicalExpr>, DataFusionError>

Constructs a new node with the specified children.

impl Hash for dyn PhysicalExpr

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

where H: Hasher,

Feeds this value into the given Hasher.

impl PartialEq for dyn PhysicalExpr

fn eq(&self, other: &(dyn PhysicalExpr + 'static)) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl Eq for dyn PhysicalExpr

Implementors

impl PhysicalExpr for BinaryExpr

impl PhysicalExpr for CaseExpr

impl PhysicalExpr for CastExpr

impl PhysicalExpr for Column

impl PhysicalExpr for InListExpr

impl PhysicalExpr for IsNotNullExpr

impl PhysicalExpr for IsNullExpr

impl PhysicalExpr for LikeExpr

impl PhysicalExpr for Literal

impl PhysicalExpr for NegativeExpr

impl PhysicalExpr for NoOp

impl PhysicalExpr for NotExpr

impl PhysicalExpr for TryCastExpr

impl PhysicalExpr for UnKnownColumn

impl PhysicalExpr for ScalarFunctionExpr