Struct datafusion_physical_expr::utils::LiteralGuarantee

pub struct LiteralGuarantee {
    pub column: Column,
    pub guarantee: Guarantee,
    pub literals: HashSet<ScalarValue>,
}

Represents a guarantee that must be true for a boolean expression to evaluate to true.

The guarantee takes the form of a column and a set of literal (constant) ScalarValues. For the expression to evaluate to true, the column must satisfy the guarantee(s).

To satisfy the guarantee, depending on Guarantee, the values in the column must either:

1. be ONLY one of that set
2. NOT be ANY of that set

Uses LiteralGuarantees

LiteralGuarantees can be used to simplify filter expressions and skip data files (e.g. row groups in parquet files) by proving expressions can not possibly evaluate to true. For example, if we have a guarantee that a must be in (1) for a filter to evaluate to true, then we can skip any partition where we know that a never has the value of 1.

Important: If a LiteralGuarantee is not satisfied, the relevant expression is guaranteed to evaluate to false or null. However, the opposite does not hold. Even if all LiteralGuarantees are satisfied, that does not guarantee that the predicate will actually evaluate to true: it may still evaluate to true, false or null.

Creating LiteralGuarantees

Use LiteralGuarantee::analyze to extract literal guarantees from a filter predicate.

Details

A guarantee can be one of two forms:

1. The column must be one the values for the predicate to be true. If the column takes on any other value, the predicate can not evaluate to true. For example, (a = 1), (a = 1 OR a = 2) or a IN (1, 2, 3)

2. The column must NOT be one of the values for the predicate to be true. If the column can ONLY take one of these values, the predicate can not evaluate to true. For example, (a != 1), (a != 1 AND a != 2) or a NOT IN (1, 2, 3)

Fields

column: Column

guarantee: Guarantee

literals: HashSet<ScalarValue>

Implementations

impl LiteralGuarantee

pub fn analyze(expr: &Arc<dyn PhysicalExpr>) -> Vec<LiteralGuarantee>

Return a list of LiteralGuarantees that must be satisfied for expr to evaluate to true.

If more than one LiteralGuarantee is returned, they must all hold for the expression to possibly be true. If any is not satisfied, the expression is guaranteed to be null or false.

Notes:

1. expr must be a boolean expression or inlist expression.
2. expr is not simplified prior to analysis.

Trait Implementations

impl Clone for LiteralGuarantee

fn clone(&self) -> LiteralGuarantee

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for LiteralGuarantee

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

Formats the value using the given formatter.

impl Display for LiteralGuarantee

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

Formats the value using the given formatter.

impl PartialEq for LiteralGuarantee

fn eq(&self, other: &LiteralGuarantee) -> 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 StructuralPartialEq for LiteralGuarantee