Enum NullableInterval 

pub enum NullableInterval {
    Null {
        datatype: DataType,
    },
    MaybeNull {
        values: Interval,
    },
    NotNull {
        values: Interval,
    },
}

An Interval that also tracks null status using a boolean interval.

This represents values that may be in a particular range or be null.

Examples

use arrow::datatypes::DataType;
use datafusion_common::ScalarValue;
use datafusion_expr_common::interval_arithmetic::Interval;
use datafusion_expr_common::interval_arithmetic::NullableInterval;

// [1, 2) U {NULL}
let maybe_null = NullableInterval::MaybeNull {
    values: Interval::try_new(
        ScalarValue::Int32(Some(1)),
        ScalarValue::Int32(Some(2)),
    )
    .unwrap(),
};

// (0, ∞)
let not_null = NullableInterval::NotNull {
    values: Interval::try_new(ScalarValue::Int32(Some(0)), ScalarValue::Int32(None))
        .unwrap(),
};

// {NULL}
let null_interval = NullableInterval::Null {
    datatype: DataType::Int32,
};

// {4}
let single_value = NullableInterval::from(ScalarValue::Int32(Some(4)));

Variants

Null

The value is always null. This is typed so it can be used in physical expressions, which don’t do type coercion.

Fields

datatype: DataType

MaybeNull

The value may or may not be null. If it is non-null, its is within the specified range.

Fields

values: Interval

NotNull

The value is definitely not null, and is within the specified range.

Fields

values: Interval

Implementations

impl NullableInterval

pub const FALSE: Self

An interval containing only the ‘false’ truth value. This interval is semantically equivalent to Interval::FALSE.

pub const TRUE: Self

An interval containing only the ‘true’ truth value. This interval is semantically equivalent to Interval::TRUE.

pub const UNKNOWN: Self

An interval containing only the ‘unknown’ truth value.

pub const TRUE_OR_FALSE: Self

An interval containing both the ‘true’, and ‘false’ truth values. This interval is semantically equivalent to Interval::TRUE_OR_FALSE.

pub const TRUE_OR_UNKNOWN: Self

An interval containing both the ‘true’ and ‘unknown’ truth values.

pub const FALSE_OR_UNKNOWN: Self

An interval containing both the ‘false’ and ‘unknown’ truth values.

pub const ANY_TRUTH_VALUE: Self

An interval that contains all possible truth values: ‘true’, ‘false’ and ‘unknown’.

pub fn values(&self) -> Option<&Interval>

Get the values interval, or None if this interval is definitely null.

pub fn data_type(&self) -> DataType

Get the data type

pub fn is_certainly_true(&self) -> bool

Return true if the value is definitely true (and not null).

pub fn is_true(&self) -> Result<Self>

Returns the set of possible values after applying the is true test on all values in this set. The resulting set can only contain ‘TRUE’ and/or ‘FALSE’, never ‘UNKNOWN’.

pub fn is_certainly_false(&self) -> bool

Return true if the value is definitely false (and not null).

pub fn is_false(&self) -> Result<Self>

Returns the set of possible values after applying the is false test on all values in this set. The resulting set can only contain ‘TRUE’ and/or ‘FALSE’, never ‘UNKNOWN’.

pub fn is_certainly_unknown(&self) -> bool

Return true if the value is definitely null (and not true or false).

pub fn is_unknown(&self) -> Result<Self>

Returns the set of possible values after applying the is unknown test on all values in this set. The resulting set can only contain ‘TRUE’ and/or ‘FALSE’, never ‘UNKNOWN’.

pub fn not(&self) -> Result<Self>

Returns an interval representing the set of possible values after applying SQL three-valued logical NOT on possible value in this interval.

This method uses the following truth table.

 A  | ¬A
----|----
 F  |  T
 U  |  U
 T  |  F

pub fn and<T: Borrow<Self>>(&self, rhs: T) -> Result<Self>

Returns an interval representing the set of possible values after applying SQL three-valued logical AND on each combination of possible values from self and other.

This method uses the following truth table.

      │   B
A ∧ B ├──────
      │ F U T
──┬───┼──────
  │ F │ F F F
A │ U │ F U U
  │ T │ F U T

pub fn or<T: Borrow<Self>>(&self, rhs: T) -> Result<Self>

Returns an interval representing the set of possible values after applying SQL three-valued logical OR on each combination of possible values from self and other.

This method uses the following truth table.

      │   B
A ∨ B ├──────
      │ F U T
──┬───┼──────
  │ F │ F U T
A │ U │ U U T
  │ T │ T T T

pub fn apply_operator(&self, op: &Operator, rhs: &Self) -> Result<Self>

Apply the given operator to this interval and the given interval.

Examples

use datafusion_common::ScalarValue;
use datafusion_expr_common::interval_arithmetic::Interval;
use datafusion_expr_common::interval_arithmetic::NullableInterval;
use datafusion_expr_common::operator::Operator;

// 4 > 3 -> true
let lhs = NullableInterval::from(ScalarValue::Int32(Some(4)));
let rhs = NullableInterval::from(ScalarValue::Int32(Some(3)));
let result = lhs.apply_operator(&Operator::Gt, &rhs).unwrap();
assert_eq!(
    result,
    NullableInterval::from(ScalarValue::Boolean(Some(true)))
);

// [1, 3) > NULL -> NULL
let lhs = NullableInterval::NotNull {
    values: Interval::try_new(
        ScalarValue::Int32(Some(1)),
        ScalarValue::Int32(Some(3)),
    )
    .unwrap(),
};
let rhs = NullableInterval::from(ScalarValue::Int32(None));
let result = lhs.apply_operator(&Operator::Gt, &rhs).unwrap();
assert_eq!(result.single_value(), Some(ScalarValue::Boolean(None)));

// [1, 3] > [2, 4] -> [false, true]
let lhs = NullableInterval::NotNull {
    values: Interval::try_new(
        ScalarValue::Int32(Some(1)),
        ScalarValue::Int32(Some(3)),
    )
    .unwrap(),
};
let rhs = NullableInterval::NotNull {
    values: Interval::try_new(
        ScalarValue::Int32(Some(2)),
        ScalarValue::Int32(Some(4)),
    )
    .unwrap(),
};
let result = lhs.apply_operator(&Operator::Gt, &rhs).unwrap();
// Both inputs are valid (non-null), so result must be non-null
assert_eq!(
    result,
    NullableInterval::NotNull {
        // Uncertain whether inequality is true or false
        values: Interval::TRUE_OR_FALSE,
    }
);

pub fn contains<T: Borrow<Self>>(&self, other: T) -> Result<Self>

Decide if this interval is a superset of, overlaps with, or disjoint with other by returning [true, true], [false, true] or [false, false] respectively.

NOTE: This function only works with intervals of the same data type. Attempting to compare intervals of different data types will lead to an error.

pub fn contains_value<T: Borrow<ScalarValue>>(&self, value: T) -> Result<bool>

Determines if this interval contains a ScalarValue or not.

pub fn single_value(&self) -> Option<ScalarValue>

If the interval has collapsed to a single value, return that value. Otherwise, returns None.

Examples

use datafusion_common::ScalarValue;
use datafusion_expr_common::interval_arithmetic::Interval;
use datafusion_expr_common::interval_arithmetic::NullableInterval;

let interval = NullableInterval::from(ScalarValue::Int32(Some(4)));
assert_eq!(interval.single_value(), Some(ScalarValue::Int32(Some(4))));

let interval = NullableInterval::from(ScalarValue::Int32(None));
assert_eq!(interval.single_value(), Some(ScalarValue::Int32(None)));

let interval = NullableInterval::MaybeNull {
    values: Interval::try_new(
        ScalarValue::Int32(Some(1)),
        ScalarValue::Int32(Some(4)),
    )
    .unwrap(),
};
assert_eq!(interval.single_value(), None);

Trait Implementations

impl Clone for NullableInterval

fn clone(&self) -> NullableInterval

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for NullableInterval

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

Formats the value using the given formatter.

impl Display for NullableInterval

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

Formats the value using the given formatter.

impl Eq for NullableInterval

impl From<ScalarValue> for NullableInterval

fn from(value: ScalarValue) -> Self

Create an interval that represents a single value.

impl PartialEq for NullableInterval

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