Enum datafusion::scalar::ScalarValue

pub enum ScalarValue {
    Null,
    Boolean(Option<bool>),
    Float32(Option<f32>),
    Float64(Option<f64>),
    Decimal128(Option<i128>, u8, u8),
    Int8(Option<i8>),
    Int16(Option<i16>),
    Int32(Option<i32>),
    Int64(Option<i64>),
    UInt8(Option<u8>),
    UInt16(Option<u16>),
    UInt32(Option<u32>),
    UInt64(Option<u64>),
    Utf8(Option<String>),
    LargeUtf8(Option<String>),
    Binary(Option<Vec<u8, Global>>),
    FixedSizeBinary(i32, Option<Vec<u8, Global>>),
    LargeBinary(Option<Vec<u8, Global>>),
    List(Option<Vec<ScalarValue, Global>>, Box<Field, Global>),
    Date32(Option<i32>),
    Date64(Option<i64>),
    Time64(Option<i64>),
    TimestampSecond(Option<i64>, Option<String>),
    TimestampMillisecond(Option<i64>, Option<String>),
    TimestampMicrosecond(Option<i64>, Option<String>),
    TimestampNanosecond(Option<i64>, Option<String>),
    IntervalYearMonth(Option<i32>),
    IntervalDayTime(Option<i64>),
    IntervalMonthDayNano(Option<i128>),
    Struct(Option<Vec<ScalarValue, Global>>, Box<Vec<Field, Global>, Global>),
    Dictionary(Box<DataType, Global>, Box<ScalarValue, Global>),
}

Represents a dynamically typed, nullable single value. This is the single-valued counter-part of arrow’s Array. https://arrow.apache.org/docs/python/api/datatypes.html https://github.com/apache/arrow/blob/master/format/Schema.fbs#L354-L375

Variants

Null

represents DataType::Null (castable to/from any other type)

Boolean(Option<bool>)

true or false value

Float32(Option<f32>)

32bit float

Float64(Option<f64>)

64bit float

Decimal128(Option<i128>, u8, u8)

128bit decimal, using the i128 to represent the decimal, precision scale

Int8(Option<i8>)

signed 8bit int

Int16(Option<i16>)

signed 16bit int

Int32(Option<i32>)

signed 32bit int

Int64(Option<i64>)

signed 64bit int

UInt8(Option<u8>)

unsigned 8bit int

UInt16(Option<u16>)

unsigned 16bit int

UInt32(Option<u32>)

unsigned 32bit int

UInt64(Option<u64>)

unsigned 64bit int

Utf8(Option<String>)

utf-8 encoded string.

LargeUtf8(Option<String>)

utf-8 encoded string representing a LargeString’s arrow type.

Binary(Option<Vec<u8, Global>>)

binary

FixedSizeBinary(i32, Option<Vec<u8, Global>>)

fixed size binary

LargeBinary(Option<Vec<u8, Global>>)

large binary

List(Option<Vec<ScalarValue, Global>>, Box<Field, Global>)

list of nested ScalarValue

Date32(Option<i32>)

Date stored as a signed 32bit int days since UNIX epoch 1970-01-01

Date64(Option<i64>)

Date stored as a signed 64bit int milliseconds since UNIX epoch 1970-01-01

Time64(Option<i64>)

Time stored as a signed 64bit int as nanoseconds since midnight

TimestampSecond(Option<i64>, Option<String>)

Timestamp Second

TimestampMillisecond(Option<i64>, Option<String>)

Timestamp Milliseconds

TimestampMicrosecond(Option<i64>, Option<String>)

Timestamp Microseconds

TimestampNanosecond(Option<i64>, Option<String>)

Timestamp Nanoseconds

IntervalYearMonth(Option<i32>)

Number of elapsed whole months

IntervalDayTime(Option<i64>)

Number of elapsed days and milliseconds (no leap seconds) stored as 2 contiguous 32-bit signed integers

IntervalMonthDayNano(Option<i128>)

A triple of the number of elapsed months, days, and nanoseconds. Months and days are encoded as 32-bit signed integers. Nanoseconds is encoded as a 64-bit signed integer (no leap seconds).

Struct(Option<Vec<ScalarValue, Global>>, Box<Vec<Field, Global>, Global>)

struct of nested ScalarValue

Dictionary(Box<DataType, Global>, Box<ScalarValue, Global>)

Dictionary type: index type and value

Implementations

impl ScalarValue

pub fn try_new_decimal128(
    value: i128,
    precision: u8,
    scale: u8
) -> Result<ScalarValue, DataFusionError>

Create a decimal Scalar from value/precision and scale.

pub fn new_utf8(val: impl Into<String>) -> ScalarValue

Returns a ScalarValue::Utf8 representing val

pub fn new_interval_ym(years: i32, months: i32) -> ScalarValue

Returns a ScalarValue::IntervalYearMonth representing years years and months months

pub fn new_interval_dt(days: i32, millis: i32) -> ScalarValue

Returns a ScalarValue::IntervalDayTime representing days days and millis milliseconds

pub fn new_interval_mdn(months: i32, days: i32, nanos: i64) -> ScalarValue

Returns a ScalarValue::IntervalMonthDayNano representing months months and days days, and nanos nanoseconds

pub fn new_list(
    scalars: Option<Vec<ScalarValue, Global>>,
    child_type: DataType
) -> ScalarValue

Create a new nullable ScalarValue::List with the specified child_type

pub fn get_datatype(&self) -> DataType

Getter for the DataType of the value

pub fn arithmetic_negate(&self) -> Result<ScalarValue, DataFusionError>

Calculate arithmetic negation for a scalar value

pub fn add<T>(&self, other: T) -> Result<ScalarValue, DataFusionError>where
    T: Borrow<ScalarValue>,

pub fn sub<T>(&self, other: T) -> Result<ScalarValue, DataFusionError>where
    T: Borrow<ScalarValue>,

pub fn is_unsigned(&self) -> bool

pub fn is_null(&self) -> bool

whether this value is null or not.

pub fn distance(&self, other: &ScalarValue) -> Option<usize>

Absolute distance between two numeric values (of the same type). This method will return None if either one of the arguments are null. It might also return None if the resulting distance is greater than usize::MAX. If the type is a float, then the distance will be rounded to the nearest integer.

Note: the datatype itself must support subtraction.

pub fn to_array(&self) -> Arc<dyn Array + 'static>

Converts a scalar value into an 1-row array.

pub fn iter_to_array(
    scalars: impl IntoIterator<Item = ScalarValue>
) -> Result<Arc<dyn Array + 'static>, DataFusionError>

Converts an iterator of references ScalarValue into an [ArrayRef] corresponding to those values. For example,

Returns an error if the iterator is empty or if the ScalarValues are not all the same type

Example

use datafusion_common::ScalarValue;
use arrow::array::{ArrayRef, BooleanArray};

let scalars = vec![
  ScalarValue::Boolean(Some(true)),
  ScalarValue::Boolean(None),
  ScalarValue::Boolean(Some(false)),
];

// Build an Array from the list of ScalarValues
let array = ScalarValue::iter_to_array(scalars.into_iter())
  .unwrap();

let expected: ArrayRef = std::sync::Arc::new(
  BooleanArray::from(vec![
    Some(true),
    None,
    Some(false)
  ]
));

assert_eq!(&array, &expected);

pub fn to_array_of_size(&self, size: usize) -> Arc<dyn Array + 'static>

Converts a scalar value into an array of size rows.

pub fn try_from_array(
    array: &Arc<dyn Array + 'static>,
    index: usize
) -> Result<ScalarValue, DataFusionError>

Converts a value in array at index into a ScalarValue

pub fn try_from_string(
    value: String,
    target_type: &DataType
) -> Result<ScalarValue, DataFusionError>

Try to parse value into a ScalarValue of type target_type

pub fn eq_array(&self, array: &Arc<dyn Array + 'static>, index: usize) -> bool

Compares a single row of array @ index for equality with self, in an optimized fashion.

This method implements an optimized version of:

    let arr_scalar = Self::try_from_array(array, index).unwrap();
    arr_scalar.eq(self)

Performance note: the arrow compute kernels should be preferred over this function if at all possible as they can be vectorized and are generally much faster.

This function has a few narrow usescases such as hash table key comparisons where comparing a single row at a time is necessary.

Trait Implementations

impl Clone for ScalarValue

fn clone(&self) -> ScalarValue

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ScalarValue

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

Formats the value using the given formatter.

impl Display for ScalarValue

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

Formats the value using the given formatter.

impl<T> From<&HyperLogLog<T>> for ScalarValuewhere
    T: Hash,

fn from(v: &HyperLogLog<T>) -> ScalarValue

Converts to this type from the input type.

impl From<&str> for ScalarValue

fn from(value: &str) -> ScalarValue

Converts to this type from the input type.

impl From<Option<&str>> for ScalarValue

fn from(value: Option<&str>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<bool>> for ScalarValue

fn from(value: Option<bool>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<f32>> for ScalarValue

fn from(value: Option<f32>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<f64>> for ScalarValue

fn from(value: Option<f64>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<i16>> for ScalarValue

fn from(value: Option<i16>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<i32>> for ScalarValue

fn from(value: Option<i32>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<i64>> for ScalarValue

fn from(value: Option<i64>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<i8>> for ScalarValue

fn from(value: Option<i8>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<u16>> for ScalarValue

fn from(value: Option<u16>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<u32>> for ScalarValue

fn from(value: Option<u32>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<u64>> for ScalarValue

fn from(value: Option<u64>) -> ScalarValue

Converts to this type from the input type.

impl From<Option<u8>> for ScalarValue

fn from(value: Option<u8>) -> ScalarValue

Converts to this type from the input type.

impl From<Vec<(&str, ScalarValue), Global>> for ScalarValue

fn from(value: Vec<(&str, ScalarValue), Global>) -> ScalarValue

Converts to this type from the input type.

impl From<bool> for ScalarValue

fn from(value: bool) -> ScalarValue

Converts to this type from the input type.

impl From<f32> for ScalarValue

fn from(value: f32) -> ScalarValue

Converts to this type from the input type.

impl From<f64> for ScalarValue

fn from(value: f64) -> ScalarValue

Converts to this type from the input type.

impl From<i16> for ScalarValue

fn from(value: i16) -> ScalarValue

Converts to this type from the input type.

impl From<i32> for ScalarValue

fn from(value: i32) -> ScalarValue

Converts to this type from the input type.

impl From<i64> for ScalarValue

fn from(value: i64) -> ScalarValue

Converts to this type from the input type.

impl From<i8> for ScalarValue

fn from(value: i8) -> ScalarValue

Converts to this type from the input type.

impl From<u16> for ScalarValue

fn from(value: u16) -> ScalarValue

Converts to this type from the input type.

impl From<u32> for ScalarValue

fn from(value: u32) -> ScalarValue

Converts to this type from the input type.

impl From<u64> for ScalarValue

fn from(value: u64) -> ScalarValue

Converts to this type from the input type.

impl From<u8> for ScalarValue

fn from(value: u8) -> ScalarValue

Converts to this type from the input type.

impl FromStr for ScalarValue

type Err = Infallible

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<ScalarValue, <ScalarValue as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for ScalarValue

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

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 Literal for ScalarValue

fn lit(&self) -> Expr

convert the value to a Literal expression

impl PartialEq<ScalarValue> for ScalarValue

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

fn partial_cmp(&self, other: &ScalarValue) -> 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 TryFrom<&DataType> for ScalarValue

fn try_from(datatype: &DataType) -> Result<ScalarValue, DataFusionError>

Create a Null instance of ScalarValue for this datatype

type Error = DataFusionError

The type returned in the event of a conversion error.

impl TryFrom<DataType> for ScalarValue

fn try_from(datatype: DataType) -> Result<ScalarValue, DataFusionError>

Create a Null instance of ScalarValue for this datatype

type Error = DataFusionError

The type returned in the event of a conversion error.

impl TryFrom<ScalarValue> for u32

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<u32, DataFusionError>

Performs the conversion.

impl Eq for ScalarValue