Enum datafusion_common::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>>),
    LargeBinary(Option<Vec<u8>>),
    List(Option<Vec<ScalarValue>>, Box<Field>),
    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>>, Box<Vec<Field>>),
    Dictionary(Box<DataType>, Box<ScalarValue>),
}

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

binary

LargeBinary(Option<Vec<u8>>)

large binary

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

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>>, Box<Vec<Field>>)

struct of nested ScalarValue

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

Dictionary type: index type and value

Implementations

impl ScalarValue

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

Create a decimal Scalar from value/precision and scale.

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

Returns a ScalarValue::Utf8 representing val

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

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

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

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

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

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

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

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<Self>

Calculate arithmetic negation for a scalar value

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

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

pub fn is_unsigned(&self) -> bool

pub fn is_null(&self) -> bool

whether this value is null or not.

pub fn to_array(&self) -> ArrayRef

Converts a scalar value into an 1-row array.

pub fn iter_to_array(
    scalars: impl IntoIterator<Item = ScalarValue>
) -> Result<ArrayRef>

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) -> ArrayRef

Converts a scalar value into an array of size rows.

pub fn try_from_array(array: &ArrayRef, index: usize) -> Result<Self>

Converts a value in array at index into a ScalarValue

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

Try to parse value into a ScalarValue of type target_type

pub fn eq_array(&self, array: &ArrayRef, 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

Formats the value using the given formatter.

impl Display for ScalarValue

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

Formats the value using the given formatter.

impl From<&str> for ScalarValue

fn from(value: &str) -> Self

Converts to this type from the input type.

impl From<Option<&str>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<bool>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<f32>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<f64>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<i16>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<i32>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<i64>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<i8>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<u16>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<u32>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<u64>> for ScalarValue

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

Converts to this type from the input type.

impl From<Option<u8>> for ScalarValue

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<bool> for ScalarValue

fn from(value: bool) -> Self

Converts to this type from the input type.

impl From<f32> for ScalarValue

fn from(value: f32) -> Self

Converts to this type from the input type.

impl From<f64> for ScalarValue

fn from(value: f64) -> Self

Converts to this type from the input type.

impl From<i16> for ScalarValue

fn from(value: i16) -> Self

Converts to this type from the input type.

impl From<i32> for ScalarValue

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<i64> for ScalarValue

fn from(value: i64) -> Self

Converts to this type from the input type.

impl From<i8> for ScalarValue

fn from(value: i8) -> Self

Converts to this type from the input type.

impl From<u16> for ScalarValue

fn from(value: u16) -> Self

Converts to this type from the input type.

impl From<u32> for ScalarValue

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for ScalarValue

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<u8> for ScalarValue

fn from(value: u8) -> Self

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<Self, Self::Err>

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

impl Hash for ScalarValue

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,

Feeds a slice of this type into the given Hasher.

impl PartialEq<ScalarValue> for ScalarValue

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

fn try_from(datatype: &DataType) -> Result<Self>

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 bool

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for f32

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for f64

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i128

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i16

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i32

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i64

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for i8

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for u16

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for u32

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for u64

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFrom<ScalarValue> for u8

type Error = DataFusionError

The type returned in the event of a conversion error.

fn try_from(value: ScalarValue) -> Result<Self>

Performs the conversion.

impl TryFromValue<u64> for ScalarValue

fn try_from_value(datatype: &DataType, value: u64) -> Result<ScalarValue>

impl Eq for ScalarValue